feat(excel): formula dependency trace — get --prop trace=precedents|dependents - #395
Open
ylz92871-dotcom wants to merge 1 commit into
Open
ylz92871-dotcom wants to merge 1 commit into
ylz92871-dotcom wants to merge 1 commit into
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 alazily-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 existingcell 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.