Add `xlflow formulas inspect` for formula snapshot exploration

[harumiWeb]

Background

xlflow now supports extracting worksheet formulas into Git-friendly, region-based JSONL snapshots.

The next step is to make those snapshots easy for humans and AI agents to inspect. Reading raw *.regions.jsonl files directly is possible, but it is not ideal for understanding workbook calculation logic, affected ranges, sheet dependencies, or expanded formulas for specific cells.

xlflow formulas inspect should provide a high-level read interface over formula snapshots.

Goal

Add an inspection command for formula snapshots that helps users and AI agents understand worksheet-level business logic embedded in formulas.

The command should answer questions such as:

• Which sheets contain formulas?
• How many formula regions and formula cells exist?
• What does each formula region calculate?
• Which formula regions depend on other sheets?
• Which region does a specific cell belong to?
• What formula would be expanded at a specific cell?
• Which formulas are only partially parsed?

Proposed command

xlflow formulas inspect

Optional forms:

xlflow formulas inspect --summary
xlflow formulas inspect --sheet Invoice
xlflow formulas inspect --cell Invoice!E500
xlflow formulas inspect --range Invoice!D2:F1001
xlflow formulas inspect --json

Input

The command should read formula snapshot files generated by xlflow formulas pull.

Expected layout:

formulas/
  manifest.json
  names.jsonl
  sheets/
    001-Invoice.regions.jsonl
    002-Summary.regions.jsonl

Output behavior

1. Summary view

Default or --summary should print a workbook-level overview.

Example:

Formula summary

Sheets:
  Invoice
    formula regions: 3
    formula cells: 3000
    parse: ok 3, partial 0, failed 0
    depends on sheets:
      Config

  StructuredRefSummary
    formula regions: 5
    formula cells: 5
    parse: ok 0, partial 5, failed 0
    features:
      structured_reference

The summary should include:

• sheet name
• formula region count
• formula cell count
• parse status counts
• notable features
• dependency summary, when available

2. Sheet view

--sheet <name> should print formula regions for one sheet.

Example:

Invoice formulas

D2:D1001
  pattern: =RC[-2]*RC[-1]
  example: D2 = B2*C2
  cells: 1000
  parse: ok

E2:E1001
  pattern: =RC[-1]*Config!R2C2
  example: E2 = D2*Config!$B$2
  cells: 1000
  parse: ok
  depends on:
    Config

F2:F1001
  pattern: =RC[-2]+RC[-1]
  example: F2 = D2+E2
  cells: 1000
  parse: ok

3. Cell view

--cell <sheet>!<address> should locate the formula region that contains the specified cell.

Example:

xlflow formulas inspect --cell Invoice!E500

Expected output:

Invoice!E500

Region:
  E2:E1001

Formula pattern:
  =RC[-1]*Config!R2C2

Example:
  E2 = D2*Config!$B$2

Expanded formula at E500:
  =D500*Config!$B$2

Parse:
  ok

If the cell does not belong to any formula region, the command should report that clearly.

Example:

Invoice!A10 is not part of any formula region.

4. Range view

--range <sheet>!<range> should list formula regions overlapping the specified range.

Example:

xlflow formulas inspect --range Invoice!D2:F1001

Expected output:

Formula regions overlapping Invoice!D2:F1001

D2:D1001
  pattern: =RC[-2]*RC[-1]
  example: D2 = B2*C2

E2:E1001
  pattern: =RC[-1]*Config!R2C2
  example: E2 = D2*Config!$B$2

F2:F1001
  pattern: =RC[-2]+RC[-1]
  example: F2 = D2+E2

5. JSON output

--json should emit machine-readable output suitable for AI agents.

Summary example:

{
  "sheets": [
    {
      "name": "Invoice",
      "formula_region_count": 3,
      "formula_cell_count": 3000,
      "parse_status": {
        "ok": 3,
        "partial": 0,
        "failed": 0
      },
      "features": [],
      "depends_on_sheets": ["Config"]
    }
  ]
}

Cell example:

{
  "cell": "Invoice!E500",
  "region": {
    "sheet": "Invoice",
    "range": "E2:E1001",
    "kind": "formula",
    "formula_r1c1": "=RC[-1]*Config!R2C2",
    "example_cell": "E2",
    "example_formula": "=D2*Config!$B$2",
    "parse_status": "ok"
  },
  "expanded_formula": "=D500*Config!$B$2"
}

R1C1 expansion

For --cell, if a region has formula_r1c1, the command should attempt to expand it to an A1-style formula at the requested cell.

Example:

Region pattern:
  =RC[-2]*RC[-1]

Cell:
  D500

Expanded:
  =B500*C500

If expansion is not supported for a formula, the command should still show the region and raw formula data.

Partial formulas

The command must treat parse_status: "partial" as inspectable, not as a hard failure.

Example:

{"range":"B2","kind":"formula","formula":"=SUM(SalesTable[Amount])","parse_status":"partial","features":["structured_reference"]}

Human output should show:

B2
  formula: =SUM(SalesTable[Amount])
  parse: partial
  features:
    structured_reference

Defined names

If formulas/names.jsonl exists, summary output should mention defined names.

Example:

Defined names:
  TaxRate -> =Config!$B$2

JSON output should include a defined_names section.

Error handling

The command should fail clearly when:

• formulas/manifest.json does not exist
• a referenced *.regions.jsonl file is missing
• the requested sheet does not exist
• the requested cell or range has invalid syntax

It should not fail merely because individual formulas have partial or failed parse status.

Acceptance criteria

• xlflow formulas inspect reads existing formula snapshots

• Summary view prints formula region counts and formula cell counts per sheet

• Sheet view lists formula regions in deterministic order

• Cell view finds the containing formula region for a given cell

• Cell view expands simple R1C1 patterns to A1 formulas when possible

• Range view lists overlapping formula regions

• Partial formulas are displayed without failing the command

• names.jsonl is included in summary output when present

• --json is supported for summary, sheet, cell, and range views

• Missing snapshot files and invalid sheet/cell/range inputs produce clear errors

• Tests cover:

  • basic copied formulas
  • mixed absolute/relative references
  • quoted sheet names
  • partial structured-reference formulas
  • formula cells not belonging to any region
  • missing snapshot files