Skip to content

feat(excel): formula dependency trace — get --prop trace=precedents|dependents - #395

Open
ylz92871-dotcom wants to merge 1 commit into
iOfficeAI:mainfrom
ylz92871-dotcom:pr/formula-trace
Open

ylz92871-dotcom wants to merge 1 commit into
iOfficeAI:mainfrom
ylz92871-dotcom:pr/formula-trace

Conversation

@ylz92871-dotcom

Copy link
Copy Markdown

feat(excel): formula dependency trace — get --prop trace=precedents|dependents

What: get <file> '/Sheet1/F2' --prop trace=precedents [--prop depth=N]
returns the formula dependency graph around a cell (dependents likewise).
Precedents collect references from the evaluator's token stream — there is
no table-formula AST, and defined names are already folded by the tokenizer,
so cell, range, sheet-qualified, and named references all come out of one
pass. Range leaves expand with caps (<=5000 per range, 20000 leaves / 5000
edges overall; overflow sets truncated: true). Dependents answer from a
lazily-built in-process reverse index (every formula cell scanned once,
range refs clamped to the used range), invalidated on every mutation: the
row-index hook, the Set() entry, sheet rename and sheet remove. JSON adds
format.trace = {root, edges: [{from, to[]}], truncated} to the existing
cell node — nothing else in the envelope changes; text mode renders an
indented tree. Errors are explicit with codes: precedents on a constant ->
unsupported_element (+suggestion), missing cell -> not_found, bad depth or
unknown prop -> invalid_argument.

Why: formula audits today stop at the cell — nothing shows what a formula
depends on or what breaks when an input changes, so agents re-derive
dependency chains by grepping formula text. A token-stream trace is exact
for the grammar the evaluator itself accepts (including the same defined-
name folding), needs no evaluation, and gives the dependency question a
one-command answer.

How to verify:
officecli get report.xlsx '/Sheet1/F2' --prop trace=precedents --json
officecli get report.xlsx '/Sheet1/F2' --prop trace=precedents --prop depth=3 --json
officecli get report.xlsx '/Sheet1/B2' --prop trace=dependents --json
(drop --json for the indented text tree)
Build 0 errors; local harness T-11 21 assertions green (chain + cross-sheet
/Sheet1!B1 qualification + reverse-index invalidation rebuild + range-entry
matching + truncation caps + text tree); regression moat 26/26.

…ependents

What: `get <file> '/Sheet1/F2' --prop trace=precedents [--prop depth=N]`
returns the formula dependency graph around a cell (dependents likewise).
Precedents collect references from the evaluator's token stream — there is
no table-formula AST, and defined names are already folded by the tokenizer,
so cell, range, sheet-qualified, and named references all come out of one
pass. Range leaves expand with caps (<=5000 per range, 20000 leaves / 5000
edges overall; overflow sets `truncated: true`). Dependents answer from a
lazily-built in-process reverse index (every formula cell scanned once,
range refs clamped to the used range), invalidated on every mutation: the
row-index hook, the Set() entry, sheet rename and sheet remove. JSON adds
`format.trace = {root, edges: [{from, to[]}], truncated}` to the existing
cell node — nothing else in the envelope changes; text mode renders an
indented tree. Errors are explicit with codes: precedents on a constant ->
unsupported_element (+suggestion), missing cell -> not_found, bad depth or
unknown prop -> invalid_argument.

Why: formula audits today stop at the cell — nothing shows what a formula
depends on or what breaks when an input changes, so agents re-derive
dependency chains by grepping formula text. A token-stream trace is exact
for the grammar the evaluator itself accepts (including the same defined-
name folding), needs no evaluation, and gives the dependency question a
one-command answer.

How to verify:
  officecli get report.xlsx '/Sheet1/F2' --prop trace=precedents --json
  officecli get report.xlsx '/Sheet1/F2' --prop trace=precedents --prop depth=3 --json
  officecli get report.xlsx '/Sheet1/B2' --prop trace=dependents --json
  (drop --json for the indented text tree)
Build 0 errors; local harness T-11 21 assertions green (chain + cross-sheet
/Sheet1!B1 qualification + reverse-index invalidation rebuild + range-entry
matching + truncation caps + text tree); regression moat 26/26.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant