@sheetxl/query 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/grep/GrepTypes.d.ts

@@ -1,5 +1,5 @@
 /**
- * The cell layers `grep` can match against.
+ * The layers `grep` can match against.
  *
  * @remarks
  * These are *not* `ICell.Content`. That enum also carries `formats`, `tables`, `merges` and
@@ -8,19 +8,21 @@
  * The rule, which predicts any future member:
  * **a grep field is a layer whose text was authored by a person or is read by one.**
  *
- * `display`, `value` and `raw` are read; `formula`, `hyperlink` and `numberFormat` are authored.
+ * `display` and `value` are read; `formula`, `hyperlink` and `numberFormat` are authored.
  * A layer that fails the rule fails it because its payload has no canonical text — a fill's
  * "red" may be stored as `FF0000`, a theme slot, or an indexed palette entry, so any pattern
  * against it silently matches less than it claims: a confident wrong answer, which is worse
  * than a missing feature. Color wants *nearness*, not matching — that is selection by
  * attribute, and it belongs to the regions read.
  *
- * Two layers are deliberately absent for the same reason:
- * - `note` — `ICell.Content.Notes` is marked NOT IMPLEMENTED.
- * - `comment` — `IComment.Properties.content` is `any` pending `IRichText.JSON`, so any text
- *   extractor written against it today would quietly miss the shapes it did not anticipate.
+ * The rule does not stop at the cell. A callout, a chart title, a comment and a defined name are
+ * all text a person wrote into the workbook, and none of it is in any cell — so `comment`,
+ * `shape`, `chart` and `name` are layers too, tagged the same way. A search that finds the cell
+ * reading `Fund Size` and misses the callout explaining it has answered a narrower question than
+ * the one asked.
  *
- * Both are additive once the SDK shapes settle.
+ * There is no `note` field: a note is a comment that says so (`IComment.isNote`), and `comment`
+ * searches both.
  */
 export type GrepField = 
 /**
@@ -38,28 +40,18 @@ export type GrepField =
  */
 'display'
 /**
- * The cell as the formula bar shows it — most formatting stripped, **category kept**.
+ * The stored scalar — what `getValue()` returns, with no number format applied.
  *
- * `1234.5678` where {@link GrepField | display} shows `$1,234.57` — but `40%` stays `40%`
- * and dates stay dates, because the formula bar keeps minimal formatting for percents,
- * dates and times (Excel's behavior, faithfully). This is *not* the underlying scalar:
- * a percent cell storing `0.4` reads `40%` here. The stored scalar is
- * {@link GrepField | raw}.
+ * `1234.5678` where {@link GrepField | display} shows `$1,234.57`, `0.4` where it shows `40%`,
+ * dates as serial numbers. This is the layer a cell report's `Value` line and the `IRange` /
+ * stats reads print, so it is the field that makes *those* printed values greppable — the
+ * round-trip that `display` provides for formatted reads. Not a default: serials and
+ * unrounded floats are noise until they are the question.
  *
  * Identical to `display` for every cell whose format only decorates (`General`, plain
- * text) — the default search dedupes that case per cell rather than reporting both.
+ * text) — a search of both dedupes that case per cell rather than reporting it twice.
  */
  | 'value'
-/**
- * The stored scalar, encoded bare — what the stateless value layer prints.
- *
- * `0.4` where {@link GrepField | value} shows `40%`; dates as serial numbers. This is the
- * layer `IRange` / stats reads print (they have no cell to format through), so it is the
- * field that makes *those* printed values greppable — the round-trip that `display`
- * provides for formatted reads. Not a default: serials and unrounded floats are noise
- * until they are the question.
- */
- | 'raw'
 /** Formula text, A1 style (`=SUM(A1:A10)`). Cells without a formula contribute nothing. */
  | 'formula'
 /** Hyperlink target — the address, not the display text (which is already `display`). */
@@ -72,14 +64,48 @@ export type GrepField =
  * cells are percentages" — the rendered `40%` is not. Matches cells with a *direct*
  * format, including value-less ones (a formatted-but-empty column is a real finding).
  */
- | 'numberFormat';
+ | 'numberFormat'
+/**
+ * The comment or note on a cell, and every reply in its thread — each its own row.
+ *
+ * A cell layer like the others: the match is the commented cell, and a cell that matches in
+ * its display AND its comment is one cell. A comment on an empty cell is still found.
+ */
+ | 'comment'
+/**
+ * The text written on a shape — a text box, a callout — and its alt text.
+ *
+ * The match is the shape, addressed by the cells it is anchored over (`F2:H6`), which is what
+ * `range.getMovables()` takes to get back to it.
+ */
+ | 'shape'
+/**
+ * What a chart says in words: its title, its axis titles, the series names written into it,
+ * and its alt text. Addressed like a {@link GrepField | shape}.
+ *
+ * A series named by a cell (`=Sales!$C$3`) is not repeated here — that text is the cell's, and
+ * `display` already finds it there.
+ */
+ | 'chart'
+/**
+ * Defined names and tables: the name, what it refers to (`=Summary!$B$4`, `=0.21`) and its
+ * comment.
+ *
+ * The match is the name, spelled as a formula writes it (`'EU Ops'!Rate` when sheet-scoped) —
+ * a name has no cell of its own. Under a {@link GrepArgs.scope | scope} a name is searched
+ * when it is scoped to a searched sheet or designates cells inside the searched range.
+ */
+ | 'name';
 export declare const GrepField: {
     readonly Display: "display";
     readonly Value: "value";
-    readonly Raw: "raw";
     readonly Formula: "formula";
     readonly Hyperlink: "hyperlink";
     readonly NumberFormat: "numberFormat";
+    readonly Comment: "comment";
+    readonly Shape: "shape";
+    readonly Chart: "chart";
+    readonly Name: "name";
 };
 /** Every field, in the order they are searched and reported. */
 export declare const GREP_FIELDS: readonly GrepField[];
@@ -87,12 +113,15 @@ export declare const GREP_FIELDS: readonly GrepField[];
  * The default field set.
  *
  * @remarks
- * What you can see, what the formula bar shows, and what is structurally behind both.
- * `value` is a default *because* the search dedupes it: for the majority of cells it is
- * byte-identical to `display` and is suppressed per cell, so it only surfaces where it
- * carries new information — `1234.5678` behind `$1,234.57`. A duplicate hit costs an agent
- * a second look for no new information; a missing layer costs a silent zero-hit miss on
- * full-precision searches, which is worse.
+ * What you can see and what is structurally behind it. `value` is opt-in: a search is almost
+ * always for text as the grid shows it, and the stored scalar in a default search makes every
+ * numeric pattern hit date serials and unrounded floats nobody was looking at. The search that
+ * wants it — a full-precision number copied from a stats read or a cell report's `Value` line —
+ * knows it does, and asks with `fields: ['value']`.
+ *
+ * The layers off the grid are defaults. A caller who has to ask for `shape` already knows the
+ * callout is there; the search that needs it is the one that does not. They cost one pass over a
+ * sheet's objects, not over its cells.
  */
 export declare const GREP_FIELDS_DEFAULT: readonly GrepField[];
 /** What a grep result should carry. */
@@ -134,9 +163,10 @@ export interface GrepArgs {
      */
     pattern: string;
     /**
-     * Which cell layers to search.
+     * Which layers to search.
      *
-     * @defaultValue {@link GREP_FIELDS_DEFAULT} — `['display', 'value', 'formula']`
+     * @defaultValue {@link GREP_FIELDS_DEFAULT} —
+     * `['display', 'formula', 'comment', 'shape', 'chart', 'name']`
      */
     fields?: readonly GrepField[];
     /**
@@ -166,11 +196,11 @@ export interface GrepArgs {
      */
     word?: boolean;
     /**
-     * Invert the match — report cells where **no** requested field matched (`rg -v`).
+     * Invert the match — report cells and objects where **no** requested field matched (`rg -v`).
      *
      * @remarks
-     * Scoped to cells grep visits: a cell must have text in at least one requested field to be
-     * reported (an empty cell is not a finding, and "every blank cell" is not an answer).
+     * Scoped to what grep visits: a cell or object must have text in at least one requested field
+     * to be reported (an empty cell is not a finding, and "every blank cell" is not an answer).
      * Reported rows carry the first requested field that has text, as the evidence line.
      */
     invert?: boolean;
@@ -200,14 +230,16 @@ export interface GrepArgs {
      */
     hidden?: boolean;
     /**
-     * Stop after this many matching cells. Truncation is always reported, never silent.
+     * Stop after this many matches — cells and objects together. Truncation is always reported,
+     * never silent.
      *
      * @defaultValue 200 — a grep result returns into a context window, not a terminal stream,
      * so unbounded output is a cost the caller did not ask for. `0` removes the cap.
      *
      * @remarks
-     * Counts **cells**, not match rows — a cell matching in two fields is one unit of budget.
-     * The search looks one cell past the cap, so a result that ends exactly at `maxCount` is
+     * Counts **cells and objects**, not match rows — a cell matching in two fields is one unit of
+     * budget, and so is a chart matching in its title and an axis.
+     * The search looks one match past the cap, so a result that ends exactly at `maxCount` is
      * only reported truncated when a further match actually exists.
      */
     maxCount?: number;
@@ -240,6 +272,10 @@ export interface GrepMatchContext {
  * order.
  *
  * @remarks
+ * Text that is not in a cell keeps the same shape. A shape or a chart is an entry per matched
+ * text, addressed by the cells it is anchored over, after its sheet's cells; a defined name is an
+ * entry addressed by the name itself, after every sheet.
+ *
  * Deliberately not coalesced into blocks: uniform runs of identical values are *regions* — a
  * payload feature splits where the value changes, so the regions read already owns that shape,
  * in 2-D and with the full partition to rank against. Grep answering cell-grain and regions
@@ -248,9 +284,15 @@ export interface GrepMatchContext {
  * renderer merely groups by it.
  */
 export interface GrepMatch {
-    /** Sheet name. */
+    /**
+     * Sheet name — for a `name` match, the sheet the name is scoped to, or `''` for a
+     * workbook-scoped one.
+     */
     sheet: string;
-    /** A1 cell address within the sheet. */
+    /**
+     * A1 cell address within the sheet; the anchor range (`F2:H6`) for a shape or chart; the name
+     * itself for a defined name. Qualified with `sheet`, each is something a follow-up call takes.
+     */
     address: string;
     /**
      * Which layer matched.
@@ -272,6 +314,8 @@ export interface GrepSheetMatches {
     sheet: string;
     /** Distinct cells that produced at least one match in this sheet. */
     cells: number;
+    /** Shapes and charts on this sheet that produced at least one match. */
+    objects: number;
 }
 /** The result of a {@link grep}. */
 export interface GrepResult {
@@ -283,6 +327,8 @@ export interface GrepResult {
     matches: readonly GrepMatch[];
     /** Distinct cells that produced at least one match. */
     cellCount: number;
+    /** Shapes, charts and names that produced at least one match. */
+    objectCount: number;
     /** Per-sheet counts, in search order — only sheets with at least one match appear. */
     sheets: readonly GrepSheetMatches[];
     /**

package/types/src/grep/grep.d.ts

@@ -1,9 +1,12 @@
 import { IWorkbook } from '@sheetxl/sdk';
 import { GrepArgs, GrepResult } from './GrepTypes';
 /**
- * Searches a workbook's cell contents by pattern.
+ * Searches a workbook's text by pattern — its cells, and what is written off the grid.
  *
  * @remarks
+ * Per sheet: the cells in reading order (a comment rides its cell), then the shapes and charts
+ * in reading order of their anchors. Defined names follow every sheet, since they belong to none.
+ *
  * Deliberately shaped after ripgrep — args, defaults and vocabulary are pretrained, and every
  * novel idiom is paid for in error loops.
  *

package/types/src/index.d.ts

@@ -2,7 +2,9 @@ import { Tool } from './Tool';
 export * from './Tool';
 export * from './encode';
 export * from './grep';
+export * from './api';
 export * from './markdown';
+export * from './delta';
 /**
  * The read surface, defined once.
  *
@@ -17,4 +19,12 @@ export * from './markdown';
  * reason). A capability joins this list only when it is not a one-line run idiom.
  */
 export declare const TOOLS: readonly Tool.Descriptor[];
+/**
+ * The reference surface — capabilities that read the install rather than a workbook.
+ *
+ * @remarks
+ * Registered by every host surface exactly as {@link TOOLS} is, minus the part that names a
+ * workbook. See {@link Tool.Reference}.
+ */
+export declare const REFERENCES: readonly Tool.Reference[];
 //# sourceMappingURL=index.d.ts.map

package/types/src/markdown/appendDependencies.d.ts

@@ -0,0 +1,106 @@
+import { ICellRange, ICellRanges, IRange, IWorksheet } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * Options for the dependency sections.
+ */
+export interface AppendDependencyOptions {
+    /**
+     * Rows each tree prints before the rest of the graph is left to the flat call.
+     *
+     * @remarks
+     * A line budget, not a depth cut: the tree is filled level by level, so a budget that runs out
+     * drops the deepest nodes first, and every node with unshown children says how many.
+     *
+     * @defaultValue 12
+     */
+    maxTreeRows?: number;
+}
+/** The calculation-graph surface shared by {@link ICell}, {@link ICellRange} and a defined name. */
+export interface DependencySource {
+    getDirectPrecedents(): Promise<ICellRanges | null>;
+    getPrecedents(): Promise<ICellRanges | null>;
+    getDirectDependents(): Promise<ICellRanges | null>;
+    getDependents(): Promise<ICellRanges | null>;
+}
+/**
+ * How the caller wants empty sections and sheet crossings reported.
+ *
+ * @remarks
+ * Not a render option — these are facts about the SUBJECT that only the calling report knows. A
+ * formula cell with no dependents is an output and `Dependents (0)` says so; a text label with no
+ * dependents is just a label, and the same heading would be noise on every one of them.
+ */
+export interface DependencyContext {
+    /** Print `## Precedents (0)` rather than omitting the section. */
+    zeroPrecedents?: boolean;
+    /** Print `## Dependents (0)` rather than omitting the section. */
+    zeroDependents?: boolean;
+    /** The sheet the report is about; members elsewhere are listed as crossings. */
+    home?: IWorksheet | null;
+    /** The cells the report is about, when it is about cells: charts that plot them are dependents too. */
+    subject?: ICellRange | null;
+}
+/**
+ * Appends the `Precedents` and `Dependents` sections for anything that exposes the calculation
+ * graph — a cell, a range or a name, which answer the same questions with the same shape.
+ *
+ * @remarks
+ * **The heading carries the reach; the tree beneath shows the path.** The flat reach
+ * (`getPrecedents()` / `getDependents()`) is what the engine already holds for recalculation, so
+ * its size costs one call: `(239 cells · 216 inputs · depth 6 · 9 areas)`. That is the answer to
+ * the common question — how much does this read, how much reads it — without any code. The tree
+ * is the explanation, and it is budgeted by rows (see {@link AppendDependencyOptions.maxTreeRows}).
+ *
+ * `inputs` are the typed (non-formula) cells in the precedent reach — the values a change to the
+ * model is actually made in. `outputs` are the dependents nothing else reads — the reported
+ * figures a change here ends up in, which is why they are listed by address and row label.
+ *
+ * `depth` is the longest chain of hops, which is the number of levels the full tree would have.
+ * It is the one measure the engine does not hold, so it is a walk, bounded, and stated as a lower
+ * bound (`depth ≥ n`) when the bound fires.
+ */
+export declare function appendDependencies(md: MarkdownBuilder, target: DependencySource, options?: AppendDependencyOptions, context?: DependencyContext): Promise<void>;
+/**
+ * `row "Net Earnings" col "JUN"` — the labels of a single-cell node that is not itself text.
+ *
+ * @remarks
+ * `G33 21.7 =+G30-G32` does not say what G33 is; its labels do. Read with {@link findLabel}, so the
+ * rule is the cell report's. `origin` is the subject the tree hangs from: a label the node shares
+ * with it — the same row, the same column — is left off, since the reader already has it.
+ */
+export declare function describeNodeLabels(range: ICellRange, origin?: Readonly<IRange.Coords> | null): string;
+/**
+ * How a graph member LABELS itself: its address, the sheet it lives on, and whether it is a name.
+ *
+ * @remarks
+ * Shared by the tree and the flat {@link ICellRanges} listing, so the two cannot label the same
+ * member differently — the flat list is the tree's rows without the hop structure, and a reader
+ * comparing them is comparing the same text.
+ *
+ * A name member leads with its NAME: its address is only an anchor, and two names authored from
+ * the same cell would otherwise print as identical, anonymous cells.
+ *
+ * The address comes back **unqualified**. A listing standing on one sheet says so once, in its
+ * heading; a qualifier goes back on every row only when the collection spans sheets, which is the
+ * caller's decision because only the caller has seen every member. A trailing `!` is `#REF!`, not
+ * a qualifier, so it is left whole.
+ */
+export declare function describeNodeLabel(range: ICellRange): {
+    address: string;
+    sheet: string;
+    isName: boolean;
+};
+/**
+ * A node's payload: the value for a single cell, the size for a range.
+ *
+ * @remarks
+ * The whole point of walking as a tree rather than listing addresses — `1,204,880` beside
+ * `Model!O30` is what makes the chain readable as a model rather than as a set of coordinates.
+ * A formula node shows its expression too, because at that point the node explains itself.
+ *
+ * Shared with the flat {@link ICellRanges} listing (`renderRanges`) for the same reason
+ * {@link describeNodeLabel} is: the flat list is these rows without the hop structure, so the two
+ * shapes cannot be allowed to drift into describing one member two ways.
+ */
+export declare function describeNode(range: ICellRange): string;
+//# sourceMappingURL=appendDependencies.d.ts.map

package/types/src/markdown/appendPivotTables.d.ts

@@ -0,0 +1,22 @@
+import { IPivotTable } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * Where a pivot table is laid out, as the address its markup declares — or `''`.
+ *
+ * @remarks
+ * Read from {@link IPivotTable.getXML} because the table has no model yet and that markup is the
+ * documented way to what it does not expose. The address is as the file wrote it: it does not
+ * follow rows and columns inserted since, which is the table's own stated limit and not this
+ * report's.
+ */
+export declare const describePivotLocation: (pivot: IPivotTable) => string;
+/**
+ * `## Pivot Tables (2)` over `  A3:D20  PivotTable1` rows.
+ *
+ * @remarks
+ * A pivot table's output is ordinary cells, so `Contentful` already lists the block — as numbers
+ * and labels, with nothing to say they are a summary of data held elsewhere and will be
+ * overwritten by the next refresh in Excel. This section is what says so.
+ */
+export declare function appendPivotTables(md: MarkdownBuilder, pivots: readonly IPivotTable[]): void;
+//# sourceMappingURL=appendPivotTables.d.ts.map

package/types/src/markdown/appendSections.d.ts

@@ -1,4 +1,4 @@
-import { ICellRange, IAnchored, ICellRanges, INamed } from '@sheetxl/sdk';
+import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, IWorksheet } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
  * Options for the feature sections.
@@ -13,7 +13,7 @@ export interface AppendFeatureOptions {
      * A **reporting** filter, not a query one. Partitioning by feature is what
      * {@link ICellRange.getRegions} is for and this does not duplicate it — it decides which of
      * those partitions a report bothers to print, which is why it lives on the renderer and not on
-     * the range. `--features fill,border` on a sheet with forty formatted regions is the
+     * the range. `--features fill,borders` on a sheet with forty formatted regions is the
      * difference between an answer and a haystack.
      *
      * The scalar kinds are accepted and reach `Counts`; they have no partition to list, so they
@@ -69,7 +69,7 @@ export interface AppendFeatureOptions {
  */
 export declare const REPORTED_FEATURES: readonly ICellRange.Feature[];
 /**
- * Parses a comma-separated feature list — the `--features fill,border` flag's value.
+ * Parses a comma-separated feature list — the `--features fill,borders` flag's value.
  *
  * @remarks
  * Matching is case-insensitive against the enum's values, so `Fill`, `fill` and `numberFormat`
@@ -92,7 +92,7 @@ export declare const describeExtent: (range: ICellRange) => string;
  */
 export declare const describeSheetName: (name: string | null | undefined) => string;
 /**
- * `wb.getSheet("My Sheet")` — the range's sheet as a callable expression.
+ * `wb.getWorksheet("My Sheet")` — the range's sheet as a callable expression.
  *
  * @remarks
  * Not {@link describeSheetName}: that quotes for the *formula* language (`'My Sheet'!A1`), and a
@@ -118,28 +118,25 @@ export declare const describeQualifiedExtent: (range: ICellRange) => string;
  * Appends the `Kind` section — what the contentful cells ARE, kind by kind.
  *
  * @remarks
- * The heading carries the contentful count; the fact lines are the scalar kinds. This replaced
- * the old `Counts` section, which mixed two vocabularies: the kinds (which have no partition to
- * list) and the features (which do, and now carry their cell counts on their own section
- * headings). What remains here is exactly the value-shape question — "5 cells: 3 strings, 2
- * numbers".
+ * The heading carries the contentful count; the lines are the census, largest first, and they
+ * sum to it — see {@link countKinds}, which the workbook's `content` row reads too, so a sheet is
+ * described in the same words and the same numbers at both altitudes. Features are not here: each
+ * has a partition to list, and carries its cell count on its own section heading.
  *
- * Read off `range.getStats().getTypedCounts()` — the same single value-scan `renderStats` and
- * `profileKinds` already read — rather than `getCounts()`: `getCounts([Feature.Number, ...])` is a
- * SECOND, independent value-scan inside the engine (`Sheet._featureCounts`'s own comment says so
- * — "the scalar kinds ... count from values in one pass"), answering the identical question. One
- * scan, one source of truth, and `RichData` is no longer a silent zero — it falls out of the same
- * typed counts for free, where the old `Feature`-keyed list had nowhere to carry it (`Feature` has
- * no `RichData` member).
- *
- * `Date` is the one line still read through a dedicated pass — `countDates`, a value scan via
- * `getInteropType()`. It is not a `ScalarType` at all — it is numeric value ∩ date-category
- * format — and `Feature.DateFormat` alone would overcount (a blank or text cell carrying that
- * format is not a date). A date cell counts as both `Number` and `Date`, so the lines need not
- * sum to the heading. Zero kinds are elided, and blanks appear nowhere — empty is not a kind of
- * content.
+ * Zero kinds are elided, and blanks appear nowhere — empty is not a kind of content.
  */
 export declare function appendKinds(md: MarkdownBuilder, range: ICellRange): void;
+/**
+ * The role census: per role (`ICellRange.Feature.Role`), how many cells and the font colors they
+ * are written in — `input  36 · #0000FF 34 · #000000 2`.
+ *
+ * @remarks
+ * The pairing the `styleRole` check reads, laid out for the reader: the check names a link in
+ * the wrong color and says nothing about a typed cell, whose color reads like the data beside it,
+ * so the census carries the constants' colors and the reader judges them with the counts in
+ * hand. A color is the authored font color (`#RRGGBB`), the Normal style's where none is authored.
+ */
+export declare function appendRoles(md: MarkdownBuilder, range: ICellRange): void;
 /**
  * Appends one section per feature partition, headed by the feature's own name.
  *
@@ -161,6 +158,21 @@ export declare function appendKinds(md: MarkdownBuilder, range: ICellRange): voi
  * sees which before paying for a drill.
  */
 export declare function appendRegions(md: MarkdownBuilder, range: ICellRange, options?: AppendFeatureOptions): void;
+/**
+ * The blocks of content in `range` — occupancy, cut where an authored table begins and ends.
+ *
+ * @remarks
+ * Occupancy alone yields maximal SOLID rectangles, and a table is not one: a title sitting over
+ * its first column makes that column run one cell longer than the rest, so the table came back as
+ * `C3:J111` plus a `B2:B111` list — two blocks, neither of them the table, at a size the `Tables`
+ * section contradicts. A table's edge is a boundary its author drew, so the partition honors it:
+ * the table is one block, at its own extent, and the title is a 1×1 above it.
+ *
+ * Refinement only ever cuts at a table's edge, so a sheet with no tables partitions exactly as
+ * occupancy does. A refined partition yields every region carrying EITHER feature, so a blank cell
+ * inside a table comes back too; a region is uniform, which makes its anchor the test.
+ */
+export declare const contentfulBlocks: (range: ICellRange) => ICellRegion[];
 /**
  * Options for {@link appendNames}.
  */
@@ -246,91 +258,16 @@ export declare const describeQualifiedName: (named: INamed) => string;
  * `Hidden` and `Comment` appear only when some row has one — per block. `false` on every visible
  * row is token noise, and blank-means-normal is how these reports already speak.
  */
-export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): void;
-/**
- * Options for the dependency trees.
- */
-export interface AppendDependencyOptions {
-    /**
-     * How many hops from the subject to walk.
-     *
-     * @defaultValue 3
-     */
-    maxDepth?: number;
-    /**
-     * Cap on nodes per tree; the tree notes truncation when exceeded.
-     *
-     * @defaultValue 50
-     */
-    maxNodes?: number;
-}
-/** The calculation-graph surface shared by {@link ICell} and {@link ICellRange}. */
-export interface DependencySource {
-    getDirectPrecedents(): ICellRanges | null;
-    getPrecedents(): ICellRanges | null;
-    getDirectDependents(): ICellRanges | null;
-    getDependents(): ICellRanges | null;
-}
+export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): Promise<void>;
 /**
- * Appends the `Precedents` and `Dependents` trees for anything that exposes the calculation
- * graph — a cell or a range, which answer the same questions with the same shape.
+ * The outline in a line — `rows 2 levels, 3 groups (1 collapsed) · columns 1 level, 1 group` —
+ * or `null` when nothing is grouped.
  *
  * @remarks
- * **A tree, walked one hop at a time, rather than a `direct`/`all` pair.** The flat form gives
- * the two ends of the chain and throws away everything between them: `D6` reading `B2:D4`
- * "eventually" does not say whether that is one indirection or nine, and the shape is the thing a
- * reader is actually trying to see. Repeated `getDirect*` calls cost the same as one `getAll*`
- * — the graph is indexed either way — so the tree is strictly more answer for the same work.
- *
- * Each node carries its **payload at the right altitude**: a single cell shows its value, a
- * multi-cell range shows its size. A range node is not expanded into cells; that is the same
- * expansion the region rules exist to prevent.
- *
- * Bounded three ways, each stated in the output rather than applied silently — depth, node count,
- * and revisits.
- *
- * **The two kinds of revisit get different marks, and that distinction is the point.** A node
- * reached twice by different branches is a re-convergence: completely normal in any model, and
- * marked `↑ shown above`. A node reached again while it is still on the current path is a
- * genuine cycle — a defect, or a deliberate iterative calculation — and is marked `↺ circular`.
- * One glyph for both would bury the second inside a busy tree, and it is the one finding here
- * that cannot afford to be missed.
- */
-export declare function appendDependencies(md: MarkdownBuilder, target: DependencySource, options?: AppendDependencyOptions): void;
-/**
- * How a graph member LABELS itself: its address, the sheet it lives on, and whether it is a name.
- *
- * @remarks
- * Shared by the tree and the flat {@link ICellRanges} listing, so the two cannot label the same
- * member differently — the flat list is the tree's rows without the hop structure, and a reader
- * comparing them is comparing the same text.
- *
- * A name member leads with its NAME: its address is only an anchor, and two names authored from
- * the same cell would otherwise print as identical, anonymous cells.
- *
- * The address comes back **unqualified**. A listing standing on one sheet says so once, in its
- * heading; a qualifier goes back on every row only when the collection spans sheets, which is the
- * caller's decision because only the caller has seen every member. A trailing `!` is `#REF!`, not
- * a qualifier, so it is left whole.
+ * Counts only: the groups themselves (level, span, summary, collapsed) are `IOutline.getGroups`,
+ * which is also what a script reads, so the report routes there instead of listing them.
  */
-export declare function describeNodeLabel(range: ICellRange): {
-    address: string;
-    sheet: string;
-    isName: boolean;
-};
-/**
- * A node's payload: the value for a single cell, the size for a range.
- *
- * @remarks
- * The whole point of walking as a tree rather than listing addresses — `1,204,880` beside
- * `Model!O30` is what makes the chain readable as a model rather than as a set of coordinates.
- * A formula node shows its expression too, because at that point the node explains itself.
- *
- * Shared with the flat {@link ICellRanges} listing (`renderRanges`) for the same reason
- * {@link describeNodeLabel} is: the flat list is these rows without the hop structure, so the two
- * shapes cannot be allowed to drift into describing one member two ways.
- */
-export declare function describeNode(range: ICellRange): string;
+export declare function describeOutline(sheet: IWorksheet): string | null;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *
@@ -346,6 +283,21 @@ export declare function describeNode(range: ICellRange): string;
  * listing would hide the very relationship `stop if true` is read against.
  */
 export declare function appendRules<T extends IAnchored>(md: MarkdownBuilder, heading: string, items: readonly T[], describe: (item: T) => string): void;
+/**
+ * The defined names whose target region intersects `range`, by name.
+ *
+ * @remarks
+ * Asked of the sheet's collection by address rather than resolved name by name here: the
+ * collection scope-checks (a name pointing at `Sheet2!A1:D4` overlaps this sheet's `A1:D4` as
+ * coordinates and is a different region entirely), and it resolves what the names designate as
+ * ONE step. A legacy file carries thousands of names nothing reads; asked one at a time, each
+ * compiled on its own, and a cell report over such a file ran out of memory. Defined names only — a
+ * table's name has its own section.
+ *
+ * @param includeOwned Also admit this sheet's private names that designate no region
+ * (`TaxRate = 0.21`), which have nothing to intersect and belong to the sheet by ownership.
+ */
+export declare function findNames(range: ICellRange, includeOwned?: boolean): INamed[];
 /**
  * Appends the sheet-level objects that intersect `range`: named ranges, hidden headers, tables,
  * conditional formats and data validations.
@@ -360,5 +312,5 @@ export declare function appendRules<T extends IAnchored>(md: MarkdownBuilder, he
  * token cost on the common path, and it buries the sections that do carry something. Absence is
  * already how these reports say "not here".
  */
-export declare function appendSheetObjects(md: MarkdownBuilder, range: ICellRange): void;
+export declare function appendSheetObjects(md: MarkdownBuilder, range: ICellRange): Promise<void>;
 //# sourceMappingURL=appendSections.d.ts.map

package/types/src/markdown/caps.d.ts

@@ -21,4 +21,8 @@
  * that would have to read further to find out.
  */
 export declare const pageWithLookahead: (total: number, pageSize: number) => number;
+/** `ICellRange.getValues()`'s default `maxSize`: a range over it is too big to copy out in one read. */
+export declare const GET_VALUES_LIMIT = 10000;
+/** The value sample a report prints for a range over {@link GET_VALUES_LIMIT}. */
+export declare const OVERSIZED_SAMPLE_CELLS = 200;
 //# sourceMappingURL=caps.d.ts.map