@sheetxl/skills 0.0.0-stage → 0.8.0-beta.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +21 -0
- package/README.md +67 -2
- package/SKILL.md +398 -0
- package/package.json +31 -3
- package/references/analysis.md +532 -0
- package/references/charts.md +173 -0
- package/references/cli.md +287 -0
- package/references/embedding.md +74 -0
- package/references/financial-models.md +364 -0
- package/references/interactive.md +194 -0
- package/references/reading.md +708 -0
- package/references/scripting.md +198 -0
- package/references/sessions.md +225 -0
- package/references/setup.md +74 -0
- package/references/showcase.md +32 -0
- package/references/udf.md +400 -0
- package/references/vector.md +129 -0
- package/references/writing.md +368 -0
|
@@ -0,0 +1,708 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: reading
|
|
3
|
+
description: "SheetXL read surface — the one map from subject to report: return the subject and it renders. Orientation (workbook, sheet, range, cell, formula, names, stats, counts), region detection (where the data blocks, formulas, styles and merges are, each region carrying the payload it was partitioned on), the contentful profile that describes each data block without a follow-up call (header detection, per-column type, bounds, distinct counts), working many blocks with a loop or with sub-agents, crossing features so one call pairs two dimensions, the feature vocabulary and its categories (including `anomalies`, the derived partition of what breaks a pattern), range statistics, style as authored layers, and the text-prefix read contract. Load when the task is understanding a sheet: structure, data regions, stats, profiling, content summary — or whenever you need to know what a report actually contains. Triggers on: getRegions, getCounts, getStats, getValues, getValuesRange, getCell, getFormula, getNames, getAnomalies, features, regions, contentful, anomalies, header detection, column types, unique values, outlier, conditional formatting, direct style, data profiling, range statistics, understand a sheet, sheet structure, explore spreadsheet, many regions, sub-agents, fan out."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Reading — Understand Before Acting
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing. Code below
|
|
9
|
+
> is run-context code (`scripting.md`): snippet form — no `await`, and nothing to
|
|
10
|
+
> import (the context is already in scope).
|
|
11
|
+
> To change what you find, see `writing.md`; to audit or repair a workbook,
|
|
12
|
+
> `analysis.md`.
|
|
13
|
+
|
|
14
|
+
**In this file:** Orientation — return the subject and it renders · Structure —
|
|
15
|
+
`getRegions()` (crossing features, the contentful profile, many blocks: loop or
|
|
16
|
+
fan out) · Defined names — the symbol table · Features — the vocabulary · Style
|
|
17
|
+
— authored layers · Profiling — `getStats()` · Reading values — the contract
|
|
18
|
+
(`IRange`, `getValues()` materializes) · The dependency graph — the tree and the
|
|
19
|
+
flat list · Common patterns
|
|
20
|
+
|
|
21
|
+
The first step is always **understand before acting** — and the cheap paths come
|
|
22
|
+
first. Every read is one line of `run`: **name the subject and its report
|
|
23
|
+
renders.** The only read that is not a subject is `grep`.
|
|
24
|
+
|
|
25
|
+
**`grep` when you have a string; regions when you have an attribute.** That is
|
|
26
|
+
the whole split. Searching for `"deferred revenue"` is grep; finding the cells
|
|
27
|
+
that are formatted as currency, or that hold an error, is `getRegions`.
|
|
28
|
+
|
|
29
|
+
## Orientation — return the subject and it renders
|
|
30
|
+
|
|
31
|
+
**Every run result renders** — *the thing you return is the thing you get
|
|
32
|
+
described.* Naming the subject in code is how you ask, and it reaches subjects an
|
|
33
|
+
address cannot name: the third region of a partition, a formula nobody has
|
|
34
|
+
written yet.
|
|
35
|
+
|
|
36
|
+
This is the whole read surface. Nothing below adds a call; it explains these.
|
|
37
|
+
|
|
38
|
+
| Subject | The line | What the report carries |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| workbook | `wb` | a short summary of **every** sheet, one line per non-empty layer — `content` (extent · cells · blocks · kinds), `formula` (extent · cells · regions · distinct), `errors` / `calc failures` / `circular` when non-zero, `anomalies` (extent · cells · regions · a count per check) when any fire, `tables` (extent · cells · names), `pivots`, a line per floating type — `charts` (count · names), `shapes` (count · how many carry text), `pictures`, `slicers` — `style` (used range · distinct fonts, formats, fills, borders, alignments), `twin of` (identical formula partition). Under a `shapes` line, the text written on that sheet's shapes, quoted and located: notes the workbook's author left for its reader, so use them to understand the model, as you would a label. Then `Errors` and `Calc Failures` as sheet-qualified region listings (`Errors` includes chart series whose reference is `#REF!`), `Anomalies` — the workbook's highest-ranked findings, sheet-qualified, with the call that lists the rest — the defined-name roster and code. Each sheet's structure is its own report |
|
|
41
|
+
| sheet | `wb.getWorksheet('Sales')` · `wb.getSelectedWorksheet()` (the active sheet — the first unless something selected another) | used range, selection, the scalar-kind census, `Errors` and `Calc Failures`, then `Anomalies` — what breaks a pattern, one line per region, highest rank first, each with its evidence (`analysis.md` §Flagged) — then one section per feature partition: data blocks one line each (shape and header, largest first), formula regions with their formulas, style features as per-attribute histograms (region lists via `getRegions(feature)`). Closes with `Tables` and `Pivot Tables`, then the floating layer — the only content that is not in cells — one section per type: `Charts` (labeled lines under each chart's row say what it plots: `series`, `names`, `categories`), `Shapes` (the text written on a shape rides its row, and those rows lead), `Pictures`, `Slicers` |
|
|
42
|
+
| regions | `sheet.getRegions(features?)` · also on any range | the uniform blocks carrying the feature, each with the payload it was partitioned on; the default `contentful` partition profiles each block instead (below). The same listing the sheet report embeds |
|
|
43
|
+
| cell range | `wb.getRange('Sales!A1:D9')` | **the values**, as an A1-labelled table, plus the kind census, the formula blocks, spills, intersecting tables, the charts, shapes and pictures floating over it (with the text written on those shapes), the conditional-format and data-validation rules over it, and the dependency graph, whose `Dependents` count the charts that plot the range — this is how you read cells |
|
|
44
|
+
| cell | `range.getCell()` · `wb.getCell('WACC!H2')` | one cell, every facet: type, display text, underlying value when it differs, formula, merge and spill state, the **rendered** style, the `Formula Row`/`Column` consistency run, the `Anomalies` that fire at it, precedents and dependents |
|
|
45
|
+
| anomalies | `getAnomalies({ checks, limit, offset })` on a range, sheet or `wb` · `range.getRegions('anomalies')` · `cell.getAnomalies()` | the findings: regions of cells carrying the same check and evidence; `getAnomalies` lists them in reading order (the named checks first, then by rank, a window at a time, sheet-qualified on `wb`), `getRegions` as a partition; at a cell, `{ check, evidence, rank }[]`. Crosses with any feature (`['anomalies', 'formula']`), counts with `getCounts('anomalies')` |
|
|
46
|
+
| formula | `range.getFormula()` · `range.createFormula('=…')` (a what-if anchored at the range) · `wb.createFormula('=NPV(0.08,B2:B9)')` | **its value** first, then status, flags, resolved symbols, indexed references and tokens |
|
|
47
|
+
| just the value | `wb.evaluate('=…')` · `formula.evaluate()` | the computed scalar alone, no diagnostics. Returns a **Promise**: a top-level snippet line awaits it for you; inside a loop or callback write `await` |
|
|
48
|
+
| stats | `range.getStats()` · `sheet.getStats()` · `wb.getStats()` | value analysis in one pass — counts, aggregates, kind breakdown |
|
|
49
|
+
| counts | `range.getCounts(features?)` | per-feature cell occupancy — presence, not location |
|
|
50
|
+
| defined names | `wb.getNames()` · `sheet.getNames()` for one sheet's view · `.getByName('TaxRate')` for one | the roster: target, dependents, validity — broken first, then load-bearing. One name renders as a formula report |
|
|
51
|
+
| table | `sheet.getTables().getByName('Sales')` · `range.getTables()` for the ones a range touches | one table — its range, header, style and columns. The **collection** does not render; the sheet report's `Tables` section is the listing |
|
|
52
|
+
| conditional format | `range.getConditionalFormats()` | one rule — its anchor, evaluation order, predicate (or color scale / data bar / icon set) and the format it paints |
|
|
53
|
+
| data validation | `range.getDataValidations()` | one rule — its anchor, predicate, **the values a list admits**, whether blanks pass, and whether a bad entry is refused or merely flagged |
|
|
54
|
+
| protection | `sheet.getProtection()` · `wb.getProtection()` · `sheet.getProtectedRanges()` for the unlocked ranges | whether it is locked (and behind a password), and the operations it still **allows** — anything not listed is refused. Reported only where it is in force: a protected sheet is marked `(protected)` and carries a `protected` line on the workbook report, a `Protection` section on its own (the editable regions, each with why), a `Protection:` first line on a range report and an `Editable:` fact on a cell. An unprotected sheet says nothing (`writing.md` §"Protected sheets") |
|
|
55
|
+
| movable | `sheet.getMovables().getItems()` · `range.getMovables()` for the ones over a range · `{ type: 'chart' }` to filter | the floating layer — pictures, charts, shapes, slicers. One movable renders its name, type, preset, text, alt text, anchor and bounds — and for a chart its type, title, series and axes: the ranges it plots (`chart.getSeries()` states each as a formula), and the axis titles, which are often the only place units are written down. The listing is the sheet report's per-type sections — `Charts`, `Shapes`, `Pictures`, `Slicers` |
|
|
56
|
+
| style | `range.getStyle()` · `cell.getStyle()` | the style itself — authored at range altitude, rendered at cell altitude (below) |
|
|
57
|
+
| vector values | `range.getValuesRange()` | `IRange` — compute without materializing (`vector.md`) |
|
|
58
|
+
| vector write | `range.setComputedValues(fn)` | `IRange` in, `IRange` out — the transform never leaves the engine |
|
|
59
|
+
| raw values | `range.getValues()` | `Scalar[][]` in your runtime — the exit door |
|
|
60
|
+
| dependencies | `range.getPrecedents()` / `getDependents()` · `getDirect*` for one hop · also on cells and names | the transitive reach as a **flat** range listing, qualified the way the tree is — one sheet named in the heading, every row qualified once the set crosses sheets; the shaped **tree** is the `## Precedents` / `## Dependents` sections of the cell, range and name reports (below) |
|
|
61
|
+
| hidden rows/cols | the sheet report's `Hidden Rows` / `Hidden Columns` sections | the data a plain read would report as absent |
|
|
62
|
+
| the *third* uniform region | `[...sheet.getRegions()][2]` | whatever that region is — subjects need no address |
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
sheetxl -e "wb" book.xlsx # the whole orientation report, one expression
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Start with the workbook.** Its roster is the fastest orientation signal on an
|
|
69
|
+
unfamiliar model — one row per sheet with used range and cell, formula and error
|
|
70
|
+
counts, and a totals row under them:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
# Workbook — Q3 Model.xlsx
|
|
74
|
+
Locale: en-US
|
|
75
|
+
|
|
76
|
+
## Sheets (3)
|
|
77
|
+
Sheet Used Cells Formulas Errors
|
|
78
|
+
Assumptions A1:D22 88 4 0
|
|
79
|
+
'Operating Model' (selected) A1:N45 82 22 12
|
|
80
|
+
'Cover Page' A1:C6 18 0 0
|
|
81
|
+
Total 188 26 12
|
|
82
|
+
|
|
83
|
+
## Errors (12)
|
|
84
|
+
'Operating Model'!H26:H31 6×1 #DIV/0! =H25/H24
|
|
85
|
+
'Operating Model'!N40:N45 6×1 #REF! =#REF!*N39
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Read the counts against each other before reading anything else — a sheet that is
|
|
89
|
+
mostly formulas is a model, one that is mostly values is data; reading the count
|
|
90
|
+
asymmetries as an audit is `analysis.md`'s shape sweep. Names are quoted
|
|
91
|
+
exactly when a formula would need the quotes, so every cell of the roster is
|
|
92
|
+
directly the next call's argument. `Errors` and `Calc Failures` are separate
|
|
93
|
+
sections and neither hides the other: an error is a successfully calculated error
|
|
94
|
+
*value* (`#DIV/0!`), a calc failure is the engine failing to evaluate at all
|
|
95
|
+
(mostly circular references).
|
|
96
|
+
|
|
97
|
+
**A formula report leads with its value**, then the analysis behind it — status,
|
|
98
|
+
resolved symbols, indexed references, tokens. So `createFormula` answers
|
|
99
|
+
*what does this come to* and *why* in one call; `wb.evaluate('=…')` is the same
|
|
100
|
+
number with none of the diagnostics, for when the number is all you want.
|
|
101
|
+
|
|
102
|
+
For a **committed** formula the cell is still the richer lens — `getCell()` adds
|
|
103
|
+
display text, number format, style and the precedents/dependents graph. Take the
|
|
104
|
+
formula object when the *expression* is the suspect. Its text is
|
|
105
|
+
`getExpression()`, without the leading `=`; the cell's `getFormulaText()` has it.
|
|
106
|
+
|
|
107
|
+
## Structure — `getRegions()`
|
|
108
|
+
|
|
109
|
+
**`getRegions` answers "where are the X?"** — it returns the rectangles that
|
|
110
|
+
*carry* a feature, so it is how you map a sheet you have never seen: where the
|
|
111
|
+
data blocks are, where the formulas are, which areas are merged.
|
|
112
|
+
|
|
113
|
+
`getRegions(features?)` returns the **maximal rectangles whose cells agree on
|
|
114
|
+
every requested feature**. It is on `IWorksheet` and on `ICellRange` — the sheet form
|
|
115
|
+
is how you start, the range form is how you *constrain*:
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
wb.getWorksheet('Operating Model').getRegions('formula')
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
# Regions — formula (2)
|
|
123
|
+
E4:E7 4×1 =C4*D4
|
|
124
|
+
E9:E11 3×1 =C9*D9
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
- **Every row carries its payload** — the anchor's read for the feature that
|
|
128
|
+
produced it, which is honest for the whole block because the block is uniform
|
|
129
|
+
in exactly that. A formula region shows its authored formula, a fill region its
|
|
130
|
+
color, an error region the error literal, a merge what the merged cell reads, a
|
|
131
|
+
comment its note, a `conditionals` or `dataValidations` region the **rule**
|
|
132
|
+
that covers it (several, joined by `|`, where rules overlap). `contentful` is
|
|
133
|
+
the exception by design: it is profiled instead (below). An `unlock` region
|
|
134
|
+
says why it is editable — `always unlocked` (the cell format) or `range Inputs`
|
|
135
|
+
(an unlocked range, `· password` when it has one). One partition, `autoTable`,
|
|
136
|
+
lists addresses alone.
|
|
137
|
+
- The default feature, `Contentful`, gives the contiguous blocks of data — found
|
|
138
|
+
without knowing their locations upfront. Other features (`Formula`, `Merge`,
|
|
139
|
+
styling features …) map that feature instead; the typed `ICellRange.Feature`
|
|
140
|
+
enum is the authority.
|
|
141
|
+
- **`Contentful` is the one feature whose regions are a locator, not a class.**
|
|
142
|
+
Every other feature partitions on payload identity — a `Fill` region is one
|
|
143
|
+
color, a `Formula` region one authored R1C1 — so its anchor read describes the
|
|
144
|
+
whole block. Occupancy has no such identity, so a contentful region is pure
|
|
145
|
+
geometry. That is why it is the one partition that comes back **profiled**
|
|
146
|
+
(below) rather than with a payload read off its anchor.
|
|
147
|
+
- **A contentful region is a maximal *solid* rectangle**, so it never contains a
|
|
148
|
+
blank. This has a consequence worth expecting before it surprises you: one hole
|
|
149
|
+
fragments a block. A table whose last column is sparse comes back as a header
|
|
150
|
+
row, a solid body, and the stragglers — three regions, not one. The profile
|
|
151
|
+
handles this (it looks *above* a block for a header that the partition left in
|
|
152
|
+
a different region), but the addresses will not always match the table you
|
|
153
|
+
see on screen.
|
|
154
|
+
- **Constraining the range clips the regions**, and the report says so. Called on
|
|
155
|
+
a sheet you get whole blocks; called on a range, a block that straddles the
|
|
156
|
+
boundary comes back **cut to your range** — so its address, its size and its
|
|
157
|
+
profile all describe a fragment. The listing marks those
|
|
158
|
+
`✂ clipped at the query edge — the block continues`, and `isClipped()` is the
|
|
159
|
+
same fact in code. Take the marker seriously: `A1:D50` on a table that runs to
|
|
160
|
+
row 200 will otherwise read as a fifty-row table. **Map with
|
|
161
|
+
`sheet.getRegions()`; constrain only when you mean to.** (`containment:
|
|
162
|
+
'fullyContained'` returns whole blocks only — and nothing at all when the block
|
|
163
|
+
is bigger than your range, which is why it is not the default.)
|
|
164
|
+
- **Only the feature-bearing side is yielded** — rectangles carrying none of the
|
|
165
|
+
requested features are elided. You get where the feature *is*, not a tour of
|
|
166
|
+
where it isn't.
|
|
167
|
+
- **A region answers *where*.** It is deliberately **not** a range: it carries its
|
|
168
|
+
address, its shape and `getFeatures()`, and it has exactly two bridges —
|
|
169
|
+
`getCell()` (the anchor, whose read *is* the region's payload) and `getRange()`
|
|
170
|
+
(the block, when you want to read or write it). One explicit hop, so you never
|
|
171
|
+
read a region for a feature you did not partition on.
|
|
172
|
+
- **A count is presence; a partition is payload identity.** `getCounts(Fill)`
|
|
173
|
+
counts the cells that have a fill; `getRegions(Fill)` splits them by *color*.
|
|
174
|
+
`getCounts(Formula)` counts formula cells; `getRegions(Formula)` splits them by
|
|
175
|
+
*authored R1C1* — so a filled block is ONE region and the value pasted over the
|
|
176
|
+
middle of it is a hole. This is the rule for every feature, and it is what makes
|
|
177
|
+
regions a defect detector rather than a map (`analysis.md`).
|
|
178
|
+
- **Regions are rectangles, not runs.** A block filled down *and* across is one
|
|
179
|
+
region, not one per column: `D8:AE45` sharing `=D7*$B$4` is a single 1,116-cell
|
|
180
|
+
region. Nothing here is 1-D.
|
|
181
|
+
- **Nothing is computed until you iterate or `getCount()`** the result. Iteration
|
|
182
|
+
order is the standard iterator contract — row-major forward, with `axis` and
|
|
183
|
+
`reverse` in the options — and a report lists them in exactly that order, so
|
|
184
|
+
`[...regions][2]` really is the third row you see. Nothing is re-sorted; a
|
|
185
|
+
small region is a finding you have to *notice*, not one the report floats.
|
|
186
|
+
|
|
187
|
+
`getCounts(features?)` is the cheap twin — per-feature cell counts straight off
|
|
188
|
+
the indexes. It answers "how much of each feature is here"; `getStats()` answers
|
|
189
|
+
"what are the values like". Use `getCounts` for *"is anything here?"* before
|
|
190
|
+
paying for a partition. The returned object carries **every** public feature as
|
|
191
|
+
an explicit key (absent ones are `0`, never missing); its *report* prints only
|
|
192
|
+
the non-zero ones.
|
|
193
|
+
|
|
194
|
+
### Crossing features — one call, two dimensions
|
|
195
|
+
|
|
196
|
+
Combining features **refines** the partition — a cross-product, never a
|
|
197
|
+
coarsening — and each region then carries one payload per feature, joined. That
|
|
198
|
+
is what makes a two-dimensional question a single call:
|
|
199
|
+
|
|
200
|
+
```typescript
|
|
201
|
+
wb.getWorksheet('Revenue Build').getRegions(['formula', 'font'])
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
```text
|
|
205
|
+
# Regions — formula, font (4)
|
|
206
|
+
C4:C11 8×1 #FF0000
|
|
207
|
+
E4:E7 4×1 =C4*D4 #0000FF
|
|
208
|
+
E8 1×1 #0000FF
|
|
209
|
+
E9:E11 3×1 =C9*D9 #0000FF
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Every region pairs an authored formula with the color a human sees — and `E8`,
|
|
213
|
+
which has the color but no formula, is the typed-in number sitting in a formula
|
|
214
|
+
column. No scan, no script, no threshold. Cross only when you mean it: each added
|
|
215
|
+
feature multiplies the partition, so three or four at once returns confetti. Two
|
|
216
|
+
features and a convention is the shape that works; the catalogue of which
|
|
217
|
+
convention lives in which feature is `analysis.md`.
|
|
218
|
+
|
|
219
|
+
### The contentful profile — what is actually in each block
|
|
220
|
+
|
|
221
|
+
The contentful partition does not just tell you where the blocks are; each one
|
|
222
|
+
comes back described. The follow-up call you would have made is already in the
|
|
223
|
+
answer — and it arrives the same way whether you asked for the partition
|
|
224
|
+
(`sheet.getRegions()`) or just returned the sheet, since the sheet report embeds
|
|
225
|
+
this listing:
|
|
226
|
+
|
|
227
|
+
```text
|
|
228
|
+
# Regions — contentful (4)
|
|
229
|
+
A1 1×1 'Q3 Actuals (draft)
|
|
230
|
+
A3:F11 9×6 header row 3
|
|
231
|
+
A Date 8 date 1/1/2024 … 1/8/2024
|
|
232
|
+
B Region 8 text 3 unique (EU 3 · NA 3 · APAC 2)
|
|
233
|
+
C Units 8 number 0 … 70 Σ 280 x̄ 35
|
|
234
|
+
D Price 8 number 1.2 Σ 9.6 x̄ 1.2
|
|
235
|
+
E Total 8 number 0 … 84 Σ 372 x̄ 46.5 · 7 formula
|
|
236
|
+
F Ref 8 text 8 distinct, no repeats
|
|
237
|
+
H3:H8 6×1 6 mixed number 5 · text 1
|
|
238
|
+
K20 1×1 'check me
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Read it the way you read `df.info()`. Five things are load-bearing:
|
|
242
|
+
|
|
243
|
+
- **The size is the shape** — a `1×1` prints its value, a one-wide run prints its
|
|
244
|
+
one series inline, and a block says where its header is. A header is **detected
|
|
245
|
+
and stated**, never assumed; when the partition left it in a different region
|
|
246
|
+
the note says `(above this block)`. If it says `no header detected`, the labels
|
|
247
|
+
genuinely are not there. `table Sales` means an authored table, and nothing
|
|
248
|
+
else does: on a sheet report a table is one block at its own extent (`part of
|
|
249
|
+
table Sales` when blank cells break it up), and its columns are under `Tables`.
|
|
250
|
+
- **The series axis is the longer one**, and the profile says `by row` when it
|
|
251
|
+
went the other way. A column line starts with its grid letter because that is
|
|
252
|
+
what your next read consumes.
|
|
253
|
+
- **A column that is formulas all the way down reports its authored formula**,
|
|
254
|
+
not N computed values. A column that is *mostly* formulas reports its values
|
|
255
|
+
and appends the count — `· 7 formula` on an 8-cell column is the hardcode.
|
|
256
|
+
- **`mixed` is a finding, not a formatting choice.** `H3:H8 · mixed · number 5 ·
|
|
257
|
+
text 1` is one text cell in a numeric column — exactly the defect the partition
|
|
258
|
+
exists to surface, visible without opening anything.
|
|
259
|
+
- **Errors are always reported** — itemized inside a `mixed` breakdown, or as a
|
|
260
|
+
trailing `· error N` note otherwise — so an error never hides inside a type
|
|
261
|
+
label. Blanks cannot appear here at all: a contentful region is solid by
|
|
262
|
+
construction, so a hole splits the block (above) rather than hiding inside a
|
|
263
|
+
profile. Profile a range of your own choosing (the range report, below) and
|
|
264
|
+
blanks do report, as a trailing `· N blank`.
|
|
265
|
+
|
|
266
|
+
Bounds are explicit. Above the scan budget a block is profiled from a leading
|
|
267
|
+
slice and says `profiled from the first N rows of M`; past the profile cap, the
|
|
268
|
+
remaining regions still list but say `not profiled`. Neither ever goes quiet, and
|
|
269
|
+
neither is a knob you turn — the note names the call that answers it. A sheet
|
|
270
|
+
report classifies up to 12 blocks, one line each (shape and header, no column
|
|
271
|
+
lines); `getRegions('contentful')` and the range report print the column lines, and
|
|
272
|
+
`getStats()` is the call when you want one block exactly.
|
|
273
|
+
|
|
274
|
+
**A profile is shape, not the cells.** It reports types, bounds, `Σ`, `x̄` and
|
|
275
|
+
distinct counts — plus the text that *names* a block, which is why a 1×1 region
|
|
276
|
+
prints its value and a table prints its header labels. All of it is bounded by
|
|
277
|
+
blocks × series, both capped, so no report above range altitude grows with your
|
|
278
|
+
data. The cells themselves are a `Values` section, and only the range report has
|
|
279
|
+
one — because only there did you say which cells.
|
|
280
|
+
|
|
281
|
+
### Many blocks — loop, or fan out
|
|
282
|
+
|
|
283
|
+
A sheet with dozens of contentful regions is a list of **independent** units of
|
|
284
|
+
work, and the right move depends on what each unit needs:
|
|
285
|
+
|
|
286
|
+
- **Computation over N regions → one `run` with a loop.** Cheap, exact, and it
|
|
287
|
+
costs nothing in context: the loop belongs in the run.
|
|
288
|
+
- **Judgment over N regions → fan out**, one sub-agent per region, if your
|
|
289
|
+
harness has them. "Does this block look wrong?" is not something a loop
|
|
290
|
+
answers. Give each agent the region's **address** and the same `session_id`;
|
|
291
|
+
it can call `run` and `grep` against the live workbook itself.
|
|
292
|
+
|
|
293
|
+
One rule if you fan out: **read in parallel, write through one agent.** Parallel
|
|
294
|
+
readers are fine. Parallel writers against one session collide on the drift guard
|
|
295
|
+
(`original_commit_id`) and you will spend the round trips you were trying to
|
|
296
|
+
save. Collect the findings, then apply the changes in a single sequence.
|
|
297
|
+
|
|
298
|
+
## Defined names — the symbol table
|
|
299
|
+
|
|
300
|
+
`=Revenue*(1+TaxRate)` is unreadable without it, and a name broken by a sheet
|
|
301
|
+
delete is a root cause that produces no cell error until something references
|
|
302
|
+
it. The workbook report carries the roster, so rung 1 already covers it; the
|
|
303
|
+
standalone forms are for drilling.
|
|
304
|
+
|
|
305
|
+
**Names that do not resolve lead the section as their own block** — its mere
|
|
306
|
+
existence is the alarm, its intro carries the count, and the `Error` column
|
|
307
|
+
carries the cause. A healthy book has no block at all. Below it, the roster is
|
|
308
|
+
sorted by **dependents descending, alphabetical on ties**: load-bearing
|
|
309
|
+
symbols, then trivia. Unreferenced junk (`_FilterDatabase` and friends) sinks
|
|
310
|
+
to the bottom on its own, so nothing has to be filtered out.
|
|
311
|
+
|
|
312
|
+
```text
|
|
313
|
+
## Names (6)
|
|
314
|
+
2 do not resolve:
|
|
315
|
+
Name Refers To Error Dependents
|
|
316
|
+
BadName =#REF!*12 #REF! 14 · Sheet1!G1:G14
|
|
317
|
+
Missing_Name =NoSuchName*2 #NAME?: NoSuchName 1 · Sheet1!G2
|
|
318
|
+
|
|
319
|
+
Name Refers To Dependents Hidden Comment
|
|
320
|
+
TaxRate =0.21 412 · EffectiveTax, Sheet1!D2:D13, +7 more 2026 statutory rate
|
|
321
|
+
Revenue =Sheet1!$B$2:$B$100 38 · Sheet1!C2:C39
|
|
322
|
+
Growth =RAND()*2 (volatile) 3 · TaxBase, Sheet1!C5, Sheet1!E9
|
|
323
|
+
OldRate =0.18 unused hidden
|
|
324
|
+
'EU Ops'!Rate =0.19 unused
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Reading the row:
|
|
328
|
+
|
|
329
|
+
- **Refers To is the expression**, so it says at a glance which names are
|
|
330
|
+
navigable (`=Sheet1!$B$2:$B$100`) and which hold a value (`=0.21`). There is
|
|
331
|
+
deliberately no `Value` column: a name with relative references evaluates
|
|
332
|
+
*per calling cell*, so a single value is not well defined — ask one name for
|
|
333
|
+
its value with `evaluate()` below.
|
|
334
|
+
- **`Error`** (broken block only) is the cause: `#REF!` for a delete, or
|
|
335
|
+
`#NAME?:` naming the identifiers that no longer exist.
|
|
336
|
+
- **`(volatile)`** means the resolved range depends on when it was read, so it
|
|
337
|
+
is not a stable navigation target.
|
|
338
|
+
- **Scope is spelled as a qualifier** (`'EU Ops'!Rate`), never as a column.
|
|
339
|
+
That is exactly what a formula writes, so the report's answer is directly the
|
|
340
|
+
next call's argument. No qualifier means global.
|
|
341
|
+
- **`Hidden` and `Comment` appear only when some name has one.**
|
|
342
|
+
|
|
343
|
+
**Dependents is SYMBOL-level, and counts names as well as cells.**
|
|
344
|
+
`=SUM(Revenue)` depends on the name; `=SUM(Sheet1!$B$2:$B$100)` does not, even
|
|
345
|
+
where that is exactly what `Revenue` designates — only the first goes `#NAME?`
|
|
346
|
+
if the name is deleted. Another *name* reading it is a dependent too, and the
|
|
347
|
+
heaviest kind: with `Doubled = Base*2`, no cell mentions `Base` and every cell
|
|
348
|
+
reading `Doubled` still breaks with it.
|
|
349
|
+
|
|
350
|
+
**The count leads every populated cell** — `412 · EffectiveTax, Sheet1!D2:D13,
|
|
351
|
+
+7 more`. The number is cells plus names, the same weight the sort uses, so the
|
|
352
|
+
column compares down its whole length. Behind it, names first, then addresses —
|
|
353
|
+
the next call's argument — spelled whole while they fit, with `+N more` for the
|
|
354
|
+
rest. `unused` means nothing references it in either currency, and it is the
|
|
355
|
+
only safe-to-delete answer; `unused · shadowed` warns that a sheet-scoped twin
|
|
356
|
+
wins the binding, which is often exactly why nothing reaches the global one.
|
|
357
|
+
`getByName('Revenue')` renders that one name in full — a formula report with an
|
|
358
|
+
identity header and its whole dependent tree.
|
|
359
|
+
|
|
360
|
+
### The three questions a name answers
|
|
361
|
+
|
|
362
|
+
Each has one call. They are easy to reach for interchangeably and they return
|
|
363
|
+
different things, so the wrong one silently answers a question you did not ask.
|
|
364
|
+
|
|
365
|
+
```typescript
|
|
366
|
+
const named = wb.getNames().getByName('Revenue');
|
|
367
|
+
named.getExpression() // 'Sheet1!$B$2:$B$100' — the refers-to TEXT, no leading '='
|
|
368
|
+
named.getRanges() // the cells it designates — null for a name holding an expression
|
|
369
|
+
await named.evaluate() // what it is worth NOW — a Scalar, or an IRange for a reference name
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
(`getValue()` is the same text — it is `INamed`'s generic accessor and a defined name
|
|
373
|
+
answers it with its expression.)
|
|
374
|
+
|
|
375
|
+
**`evaluate()` is the one to reach for when the question is "what is this
|
|
376
|
+
worth".** Do not read the text and re-query it: `wb.getRange(String(n.getValue()))`
|
|
377
|
+
is a parse of a formula expression that only *sometimes* happens to be an
|
|
378
|
+
address, which is why it needs a `try`/`catch` — and it is wrong for the names
|
|
379
|
+
that matter (`=0.21`, `=SUM(...)`, anything with a function). `evaluate()` is
|
|
380
|
+
async and settles the engine itself.
|
|
381
|
+
|
|
382
|
+
A name written with **relative** references evaluates per calling cell, so
|
|
383
|
+
`evaluate()` gives one anchored answer and each dependent cell sees its own.
|
|
384
|
+
That is the same reason the roster carries no `Value` column; for those names
|
|
385
|
+
the honest read is the dependent cell, not the name.
|
|
386
|
+
|
|
387
|
+
There is no `getRange()` (singular) and no `getReferenceText()`. Guessing one
|
|
388
|
+
throws — `n.getRange is not a function` — so a run that comes back with empty
|
|
389
|
+
columns instead is a `?.()` in your own loop swallowing the mistake. Do not
|
|
390
|
+
write defensive optional calls against this API; let it throw and read the
|
|
391
|
+
name.
|
|
392
|
+
|
|
393
|
+
## Features — the vocabulary
|
|
394
|
+
|
|
395
|
+
Same flat list everywhere a `features` argument appears. **In code, features are
|
|
396
|
+
the exact camelCase values** (`'formula'`, `'numberFormat'`) — the typed
|
|
397
|
+
`ICellRange.Feature` constants — while the report-option spelling
|
|
398
|
+
(`--md.features=…` on the CLI, `md: { features: "…" }` on MCP) is
|
|
399
|
+
case-insensitive. There is no group or wildcard grammar: every call names exactly
|
|
400
|
+
the features it means, which is a property, not a limitation — an audit that
|
|
401
|
+
asserts uniformity should say over which dimensions, and its meaning should not
|
|
402
|
+
drift when the engine grows a new feature.
|
|
403
|
+
|
|
404
|
+
Three categories to orient by (categories, not arguments — asking for several
|
|
405
|
+
features at once is the cross-product, see above):
|
|
406
|
+
|
|
407
|
+
| Category | Members | The question they answer |
|
|
408
|
+
|---|---|---|
|
|
409
|
+
| appearance | `fill` `borders` `numberFormat` `dateFormat` `alignment` `font` · `conditionals` · `table` `autoTable` | how does this look? |
|
|
410
|
+
| calculation | `formula` `spills` `calcError` `calcStatus` | is the calculation healthy? |
|
|
411
|
+
| scalar kind | `error` | what kind of data is this? |
|
|
412
|
+
| audit | `anomalies` | what breaks the pattern around it? — derived from the other partitions, never authored; a region is a run of cells with the same finding and evidence |
|
|
413
|
+
|
|
414
|
+
Outside the categories: **`contentful`** (the default — contiguous blocks of data),
|
|
415
|
+
`merge`, `dataValidations`, `hyperlink`, `comments`, and `unlock` — the cells that
|
|
416
|
+
still take a write on a protected sheet. `unlock` has no section on a sheet report:
|
|
417
|
+
it is the body of the `Protection` section, which prints only when the sheet is
|
|
418
|
+
protected.
|
|
419
|
+
|
|
420
|
+
Features also narrow a *report* rather than a query. A workbook or sheet report
|
|
421
|
+
over a heavily formatted sheet is dozens of region sections; passing `features`
|
|
422
|
+
as a **report option** — `--md.features=fill,borders` on the CLI, `md: { features:
|
|
423
|
+
"fill,borders" }` on MCP's `run` — prints only those sections without changing what
|
|
424
|
+
was asked for. Reach for it when the answer is in the report but buried; reach for
|
|
425
|
+
`getRegions` when the *question* is about specific features.
|
|
426
|
+
|
|
427
|
+
`features` and `mode` are the whole report surface — **it selects, it does not
|
|
428
|
+
size.** Nothing there makes a report longer, because a truncated report is a signal
|
|
429
|
+
to ask a narrower question, not to re-run the same one with a bigger budget. Every
|
|
430
|
+
truncation note names the query that returns the rest.
|
|
431
|
+
|
|
432
|
+
- **`string`/`number`/`boolean` are not features.** The vocabulary is for things
|
|
433
|
+
with a spatial identity — a fill, a formula, an occupied cell — and a scalar
|
|
434
|
+
kind has none: it is read straight off the value, which is the single pass
|
|
435
|
+
`range.getStats().getTypedCounts()` already makes, richer (aggregates and
|
|
436
|
+
frequencies come with it, at no extra cost). `error` is a feature — an error
|
|
437
|
+
value has spatial identity of its own — and it partitions like any other,
|
|
438
|
+
grouped by error value. `dateFormat` is a formatting predicate (the same tier
|
|
439
|
+
as `numberFormat`), not a value kind: it answers "does this cell carry a
|
|
440
|
+
date-category format", which includes a date-formatted blank or text cell. For
|
|
441
|
+
"how many cells are genuinely dates" (a numeric value under that format), read
|
|
442
|
+
values — `getInteropType()` per cell, or the report's own `date` line in its
|
|
443
|
+
`Kind` section, which already does this. That census is disjoint — each cell
|
|
444
|
+
under one kind (`number`, `date`, `text`, `formula`, …), summing to the heading —
|
|
445
|
+
so `formula` against the rest is how much of the sheet is model and how much is
|
|
446
|
+
input.
|
|
447
|
+
- Appearance spans all three authored layers on purpose, because "is the
|
|
448
|
+
formatting consistent" cannot know in advance which layer the convention lives
|
|
449
|
+
in — but asking about the layers together never composes them; see *Style*
|
|
450
|
+
below. `table` is in the appearance category as a source of it, and
|
|
451
|
+
`--md.features=table` on its own answers a different, structural question — what
|
|
452
|
+
tables exist, named, with headers.
|
|
453
|
+
|
|
454
|
+
## Style — authored layers, not resolved effect
|
|
455
|
+
|
|
456
|
+
Style comes back as **the layers a human authored**, each as its own set of uniform
|
|
457
|
+
ranges, never composed into a per-cell answer:
|
|
458
|
+
|
|
459
|
+
| Layer | What it is |
|
|
460
|
+
|---|---|
|
|
461
|
+
| direct style | what someone set on the cells — the `Fill`, `Border`, `NumberFormat`, `Alignment`, `Font` features |
|
|
462
|
+
| conditional formatting | the ranges the rules apply to, each row carrying the rule itself — the `Conditionals` feature |
|
|
463
|
+
| tables | the table, its style, banding and header — `Table` / `AutoTable` |
|
|
464
|
+
|
|
465
|
+
Colors arrive resolved: `#000000 (theme 1)`, never a bare theme index or tint.
|
|
466
|
+
|
|
467
|
+
Keeping the layers apart is what makes style readable at range altitude. A banded
|
|
468
|
+
table is *one* authored fact — `style Medium9 · banded rows` — and an unbounded
|
|
469
|
+
number of resolved ranges; a color scale is one rule and one distinct range per
|
|
470
|
+
cell. Composing would also erase the distinction a convention audit depends on: a
|
|
471
|
+
cell colored deliberately means something, a cell colored by an inherited band
|
|
472
|
+
means nothing, and resolved style makes them identical.
|
|
473
|
+
|
|
474
|
+
When you do want *what a human sees at one cell, and which layer won*, that is a
|
|
475
|
+
cell facet: `getCell().getStyle()`. One cell, on demand — never a column across a
|
|
476
|
+
range. (`getStyle(true)` is the *direct* read on a cell, which is what a
|
|
477
|
+
convention audit compares.)
|
|
478
|
+
|
|
479
|
+
**Range-level `getStyle()` reads the anchor** — exactly what the Excel ribbon
|
|
480
|
+
shows when a range is selected (writes apply to the whole range; `writing.md`).
|
|
481
|
+
The ribbon is safe because a human *sees* the selection disagree; an API return
|
|
482
|
+
carries no such signal — so never treat the anchor's read as evidence of
|
|
483
|
+
uniformity. The uniformity test is `getRegions(<style features>)` returning a
|
|
484
|
+
single region.
|
|
485
|
+
|
|
486
|
+
## Profiling — `getStats()`
|
|
487
|
+
|
|
488
|
+
`ICellRange.getStats()` computes an `IRangeStats` in a single pass. Prefer it
|
|
489
|
+
over hand-rolled loops for aggregation, profiling, and validation.
|
|
490
|
+
|
|
491
|
+
It exists at every tier: `wb.getStats()` (every sheet's used cells, hidden
|
|
492
|
+
included), `sheet.getStats()` (the used range, null-safe — an empty sheet is
|
|
493
|
+
empty statistics, not a `null` branch), and the range form below. All take
|
|
494
|
+
iterator options — at workbook scale pass `{ onError: 'ignore' }`, since one
|
|
495
|
+
error value anywhere makes the default `'throw'` policy fault the aggregate.
|
|
496
|
+
|
|
497
|
+
```typescript
|
|
498
|
+
const stats = wb.getWorksheet().getRange('A1:A100').getStats();
|
|
499
|
+
|
|
500
|
+
// Size and counts
|
|
501
|
+
stats.getSize() // total cells, including blanks
|
|
502
|
+
stats.getCount() // non-empty cells
|
|
503
|
+
|
|
504
|
+
// Type breakdown — keys are ScalarType values:
|
|
505
|
+
// 'number' | 'string' | 'boolean' | 'error' | 'richData' | 'null'
|
|
506
|
+
const counts = stats.getTypedCounts();
|
|
507
|
+
// counts.number ?? 0 → numeric cells; counts.error → error cells;
|
|
508
|
+
// counts.null → blanks
|
|
509
|
+
|
|
510
|
+
// Numeric aggregates (null when no numbers)
|
|
511
|
+
const agg = stats.getAggregates();
|
|
512
|
+
// agg.sum, agg.min, agg.max, agg.average, agg.stdDev — and more in the types
|
|
513
|
+
|
|
514
|
+
// Order statistics (LARGE, SMALL, PERCENTILE, RANK, MEDIAN)
|
|
515
|
+
const sorted = stats.getSortedNumbers();
|
|
516
|
+
sorted.getLarge(1); // maximum
|
|
517
|
+
sorted.getSmall(1); // minimum
|
|
518
|
+
sorted.getPercentile(0.5); // median
|
|
519
|
+
sorted.getRankOf(value); // 1-based rank
|
|
520
|
+
```
|
|
521
|
+
|
|
522
|
+
**Distinct values are also available directly off `getStats()`.**
|
|
523
|
+
`getFrequencies()` gives `getUniqueCount()` and `getValueCounts()` (top-N,
|
|
524
|
+
sorted by frequency or value) over the whole population — the contentful
|
|
525
|
+
profile's `3 unique (EU 3 · NA 3 · APAC 2)` and `8 distinct, no repeats` lines
|
|
526
|
+
are exactly this, already computed for you. Reach for `getFrequencies()`
|
|
527
|
+
directly when you want the full breakdown rather than the profile's capped
|
|
528
|
+
top-N, or need it restricted to one kind (`{ filterFn }`). `getRanked()`
|
|
529
|
+
answers top/bottom-N (LARGE/SMALL) without a full sort.
|
|
530
|
+
|
|
531
|
+
## Reading values — the contract
|
|
532
|
+
|
|
533
|
+
**A range is a reference, not its contents** — `getRange('B2:D10')` names a section
|
|
534
|
+
of a sheet and holds no values, which is why naming one is free at any size.
|
|
535
|
+
|
|
536
|
+
**Its report is another matter: returning the range prints the values.** That is
|
|
537
|
+
the read, and it is the better one — an A1-labelled table where `getValues()` is a
|
|
538
|
+
bare nested array you have to count rows against by eye. Reach past it only when
|
|
539
|
+
the values must *leave*, or when you are computing over them; *how* you ask decides
|
|
540
|
+
whether the work happens inside the engine or inside your loop.
|
|
541
|
+
|
|
542
|
+
```text
|
|
543
|
+
# Cell Range — 'Cover Page'!C12:C18, 7×1
|
|
544
|
+
|
|
545
|
+
## Kind (3 cells · 1 kind)
|
|
546
|
+
text 3
|
|
547
|
+
|
|
548
|
+
## Profile
|
|
549
|
+
3 text 3 distinct, no repeats · 4 blank
|
|
550
|
+
|
|
551
|
+
## Values (C12:C15, 4×1 · 3 cells)
|
|
552
|
+
C
|
|
553
|
+
12 'Profit and Loss Statement
|
|
554
|
+
14 'Table of Contents
|
|
555
|
+
15 'Profit and Loss (Monthly)
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
The table is capped (1000 cells) and elides rows and columns that came back
|
|
559
|
+
empty, which is why its labels are real A1 labels rather than `1..n` — with row
|
|
560
|
+
`13` gone, an index would assert an adjacency that is not there. The heading
|
|
561
|
+
states the shrunk bounds when they differ from what you asked for. Past the cap
|
|
562
|
+
the answer is a narrower address or `getStats()`, not a bigger table.
|
|
563
|
+
|
|
564
|
+
Below the values, the same report carries the formula blocks (one row per
|
|
565
|
+
authored formula, addressed as a range — not one row per cell), any spills, the
|
|
566
|
+
tables and names that intersect, and the precedents and dependents trees.
|
|
567
|
+
|
|
568
|
+
### `IRange` — the vector surface
|
|
569
|
+
|
|
570
|
+
`getValuesRange()` bridges a cell range into **`IRange`**: an immutable,
|
|
571
|
+
two-dimensional, mixed-type sparse array with functional vector semantics, shaped
|
|
572
|
+
for NumPy/JAX familiarity. Transforms are zero-copy and reads are SIMD-optimized;
|
|
573
|
+
computation happens inside the engine rather than in your runtime.
|
|
574
|
+
|
|
575
|
+
**The operations are in [vector](vector.md)**, along with `setComputedValues`, the
|
|
576
|
+
write half. Load it whenever you are about to transform, filter, sort or broadcast
|
|
577
|
+
over more than a couple of cells. The rule for choosing: `getStats()` when you are
|
|
578
|
+
**reducing** to an answer, `IRange` when you are **producing** new values,
|
|
579
|
+
`getValues()` only when the grid is leaving.
|
|
580
|
+
|
|
581
|
+
## The dependency graph — the tree and the flat list
|
|
582
|
+
|
|
583
|
+
The calculation graph renders in two shapes, and they answer different questions.
|
|
584
|
+
|
|
585
|
+
**The tree** is a section of the cell, range and name reports — `## Precedents`
|
|
586
|
+
and `## Dependents` — walked one hop at a time from the subject, so the *shape*
|
|
587
|
+
of the chain survives: the top level is one hop, anything nested is where the
|
|
588
|
+
influence keeps travelling.
|
|
589
|
+
|
|
590
|
+
```text
|
|
591
|
+
## Dependents
|
|
592
|
+
|
|
593
|
+
D2:D4 3×1 =B2*C2
|
|
594
|
+
D6 6308.8 =SUM(D2:D4)
|
|
595
|
+
B6 400 =SUM(B2:B4)
|
|
596
|
+
D6 ↑ shown above
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
- **Each node carries its payload at the right altitude** — a single cell shows
|
|
600
|
+
its value and formula, a multi-cell range its dimensions and the formula
|
|
601
|
+
shared across it. A range node is never expanded into its cells, and addresses
|
|
602
|
+
qualify with their sheet only when the tree spans sheets.
|
|
603
|
+
- **A defined name appears as a labeled node** — `EffectiveTax name`, or
|
|
604
|
+
`Revenue name → Sheet1!$B$2:$B$13` when it designates a range — and the tree
|
|
605
|
+
continues through it to whatever reads or feeds it. `=SUM(Revenue)` therefore
|
|
606
|
+
shows BOTH the `Revenue` node (the symbol that breaks if the name is deleted)
|
|
607
|
+
and the resolved cells (the data the value came from); they are different
|
|
608
|
+
facts, not a duplicate.
|
|
609
|
+
- **Two revisit marks, and they are opposite findings.** `↑ shown above` is
|
|
610
|
+
re-convergence — a node reached by more than one path, ordinary in any model:
|
|
611
|
+
a total fed both directly and through an intermediate. `↺ circular` is a
|
|
612
|
+
genuine cycle — deliberate in an iterative calculation, a defect otherwise.
|
|
613
|
+
- **Bounded three ways, each stated rather than silent** — depth (3 hops by
|
|
614
|
+
default), node count, and revisits. A cut at nodes means the graph is *wide*,
|
|
615
|
+
and the answer is to stand on one node and walk from there; a cut at depth is
|
|
616
|
+
what the flat list answers outright.
|
|
617
|
+
|
|
618
|
+
**The flat list** is what the graph calls themselves render. `getPrecedents()` /
|
|
619
|
+
`getDependents()` resolve to the whole transitive reach as ranges (an `ICellRanges`,
|
|
620
|
+
whose `getCount()` is the number of areas — cells are `getCounts()`), and
|
|
621
|
+
`getDirectPrecedents()` / `getDirectDependents()` one hop — on `ICell`,
|
|
622
|
+
`ICellRange` and defined names alike. All four are promises - the engine answers
|
|
623
|
+
them - so a script awaits one before reading it (`(await r.getPrecedents())?.getCount()`);
|
|
624
|
+
a snippet awaits its final value for you. Returning one prints a `# Ranges` listing
|
|
625
|
+
with the same per-row payloads as the tree and no hop structure, which is the
|
|
626
|
+
point: it is the countable, diffable form, and the answer to a tree branch cut
|
|
627
|
+
at the depth bound. It qualifies the way the tree does — a set that stays on one
|
|
628
|
+
sheet names it once in the heading and leaves its rows bare, one that crosses
|
|
629
|
+
qualifies every row instead. The same graph the tree above walked, flat:
|
|
630
|
+
|
|
631
|
+
```text
|
|
632
|
+
# Ranges — Sales (3)
|
|
633
|
+
D2:D4 3×1 =B2*C2
|
|
634
|
+
B6 400 =SUM(B2:B4)
|
|
635
|
+
D6 6308.8 =SUM(D2:D4)
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
The graph is indexed by range, so either shape reduces a column of four hundred
|
|
639
|
+
dependent cells to one entry. What a defect *feeds* and what a fix *moves* is
|
|
640
|
+
`analysis.md` §"Before you edit — the blast radius"; this section is only how
|
|
641
|
+
the answer prints.
|
|
642
|
+
|
|
643
|
+
### `getValues()` materializes — use it deliberately
|
|
644
|
+
|
|
645
|
+
`getValues()` copies the range into JavaScript. It is for values you are going to
|
|
646
|
+
*compute with* in your runtime — hand to another tool, write to a file — not
|
|
647
|
+
values you want to look at. **A loop over `getValues()` is the slow path twice
|
|
648
|
+
over**: it copies, and it moves the work out of the engine and into your code.
|
|
649
|
+
|
|
650
|
+
```typescript
|
|
651
|
+
range.getValues() // Scalar[][] — a real array in your runtime, maxSize-capped
|
|
652
|
+
range.getValue() // one Scalar — the top-left cell
|
|
653
|
+
range.getCell() // ICell — per-cell detail, top-left by default
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
Display text is a **cell** lens, not a range one: `getCell().getText()` for the
|
|
657
|
+
one cell you are diagnosing — there is no `getText()` on a range. Reaching for it
|
|
658
|
+
in a loop is the tell that the range report was the call.
|
|
659
|
+
|
|
660
|
+
One boundary to keep straight. `getValues()` hands back **typed** scalars, where
|
|
661
|
+
the JavaScript type carries the type: `"123"` is a string, `45292` a date serial.
|
|
662
|
+
The `'` prefix belongs to the *text* encoding — reports, grep, anything crossing a
|
|
663
|
+
text boundary — where type would otherwise be lost, and it is what makes
|
|
664
|
+
`'10/23/95` (text) distinguishable from `10/23/95` (a formatted number). The rule
|
|
665
|
+
and both directions are the **Value encoding** section of the root `SKILL.md`;
|
|
666
|
+
per-cell writing is `writing.md`.
|
|
667
|
+
|
|
668
|
+
## Common patterns
|
|
669
|
+
|
|
670
|
+
### Orient to an unfamiliar sheet
|
|
671
|
+
|
|
672
|
+
```typescript
|
|
673
|
+
wb.getSelectedWorksheet() // kind census, every feature partition, and the data blocks classified
|
|
674
|
+
```
|
|
675
|
+
|
|
676
|
+
One call. Reach for `getRegions()` on its own when you want a *single* partition
|
|
677
|
+
without the rest of the report around it, or the column profiles of its blocks.
|
|
678
|
+
|
|
679
|
+
When the profile is not the question you were sent with, the loop belongs in the
|
|
680
|
+
run:
|
|
681
|
+
|
|
682
|
+
```typescript
|
|
683
|
+
const report = [];
|
|
684
|
+
for (const region of wb.getWorksheet().getRegions()) {
|
|
685
|
+
const stats = region.getRange().getStats(); // getRange() = "now I want to read"
|
|
686
|
+
report.push(`${region.getAddress()}: ${stats.getCount()} values`);
|
|
687
|
+
}
|
|
688
|
+
report.join('\n')
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
### Profile a column for data quality
|
|
692
|
+
|
|
693
|
+
```typescript
|
|
694
|
+
const counts = wb.getWorksheet().getRange('B2:B100').getStats().getTypedCounts();
|
|
695
|
+
// (counts.null ?? 0) > 0 → blanks present
|
|
696
|
+
// (counts.error ?? 0) > 0 → errors present
|
|
697
|
+
// (counts.string ?? 0) > 0 in a numeric column → suspect cells
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
Bound the range. `A:A` is a million cells, and its `null` count is the million
|
|
701
|
+
empty ones — a true answer to a question nobody asked.
|
|
702
|
+
|
|
703
|
+
### Check a range is purely numeric
|
|
704
|
+
|
|
705
|
+
```typescript
|
|
706
|
+
const counts = wb.getWorksheet().getRange('B2:B100').getStats().getTypedCounts();
|
|
707
|
+
!(counts.string || counts.boolean || counts.error)
|
|
708
|
+
```
|