@sheetxl/query 0.7.23-beta.1

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

@@ -0,0 +1,16 @@
+import { Tool } from '../Tool';
+import { GrepArgs, GrepResult } from './GrepTypes';
+/**
+ * The `grep` capability, as both surfaces see it.
+ *
+ * @remarks
+ * Named `grep` rather than `find` on Unix semantics: `find` searches by name and attributes,
+ * `grep` searches contents by pattern. Selection by attribute is the regions read.
+ *
+ * No `sdk:` line, deliberately. `ICellRange.find` cannot reproduce grep — it takes
+ * `ICell.Content` fields (a different vocabulary), defaults to formulas only, and bypasses the
+ * shared encoder — so the line would graduate an agent into a macro that returns different
+ * answers. It returns when an SDK search with grep's contract lands.
+ */
+export declare const grepTool: Tool.Descriptor<GrepArgs, GrepResult>;
+//# sourceMappingURL=grepTool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grepTool.d.ts","sourceRoot":"","sources":["../../../../src/grep/grepTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAoC,MAAM,aAAa,CAAC;AAI/F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAqG1D,CAAC"}

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

@@ -0,0 +1,5 @@
+export * from './GrepTypes';
+export * from './grep';
+export * from './renderGrep';
+export * from './grepTool';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/grep/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}

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

@@ -0,0 +1,19 @@
+import { GrepResult } from './GrepTypes';
+/**
+ * Renders a {@link GrepResult} as an aligned listing.
+ *
+ * @remarks
+ * Aligned listing rather than a markdown table: the result is heterogeneous sections, not a grid,
+ * and terminal output (`ls -l`, `git status`) is enormously represented in training data while
+ * costing no pipe characters.
+ *
+ * Header carries scope, footer carries what is next — the footer is last because that is where
+ * the next-action decision happens. Both are one line and phrased identically every time, so a
+ * stable footer is skimmed in a couple of tokens once it has been seen twice.
+ *
+ * With context on, matches are grouped under the block they sit in — `rg --heading` groups
+ * hits under their file; the enclosing region is the grid's file. Twelve hits in one table
+ * cost one block line plus twelve short rows, not twelve fully-qualified addresses.
+ */
+export declare function renderGrep(result: GrepResult): string;
+//# sourceMappingURL=renderGrep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"renderGrep.d.ts","sourceRoot":"","sources":["../../../../src/grep/renderGrep.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AA0B9D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CA8ErD"}

package/types/src/index.d.ts

@@ -0,0 +1,20 @@
+import { Tool } from './Tool';
+export * from './Tool';
+export * from './encode';
+export * from './grep';
+export * from './markdown';
+/**
+ * The read surface, defined once.
+ *
+ * @remarks
+ * Every host surface generates its registrations from this list. A capability that appears on
+ * one surface and not another is a bug, not a decision — affordances are expected to differ,
+ * capabilities are not.
+ *
+ * Structural reads are deliberately NOT tools: `run -e "<expression>" --md` renders any SDK
+ * object through the renderer registry, so a `describe` verb would be a second copy of what
+ * code already expresses (a `describe` tool was built and removed 2026-07-30 for exactly this
+ * reason). A capability joins this list only when it is not a one-line run idiom.
+ */
+export declare const TOOLS: readonly Tool.Descriptor[];
+//# sourceMappingURL=index.d.ts.map

package/types/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAE3B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,CAAC,UAAU,EAE3C,CAAC"}

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

@@ -0,0 +1,84 @@
+import { ITextFrame } from '@sheetxl/sdk';
+/**
+ * One cell of a markdown table: its rendered text and horizontal alignment.
+ */
+export type TableCellDetails = {
+    text: string;
+    alignment: 'left' | 'right' | 'center';
+};
+/**
+ * Line-buffer markdown builder.
+ *
+ * @remarks
+ * Deliberately small — headings, text, bullets, inline decorations and tables; the vocabulary the
+ * agent-facing reports actually use, nothing speculative. Renderers compose reports from this so
+ * table layout (column widths, alignment padding) is written once.
+ */
+export declare class MarkdownBuilder {
+    private readonly _lines;
+    private _headingOffset;
+    /**
+     * Shifts every subsequent heading down by `offset` levels — how one report embeds another
+     * report's sections. The section functions stay written against their own altitude (`h2` for a
+     * sheet's `Type`), and the embedding report decides where that altitude sits.
+     */
+    setHeadingOffset(offset: number): this;
+    private _heading;
+    h1(s: string): this;
+    h2(s: string): this;
+    h3(s: string): this;
+    text(s: string): this;
+    blank(): this;
+    bullet(s: string | string[]): this;
+    /**
+     * A `Key: value` fact line, two-space indented.
+     *
+     * @remarks
+     * The reports' body convention — the same indent the address listings use, so every section
+     * body starts at the same column in raw text. Not a markdown bullet on purpose: renderers
+     * restyle bullets (markers, extra indent, list spacing), and these reports are read raw at
+     * least as often as rendered.
+     */
+    fact(s: string | string[]): this;
+    bold(s: string): string;
+    codespan(s: string): string;
+    code(s: string, lang?: string): string;
+    beginFrame(headers: string[]): MarkdownFrameSection;
+    /** @internal */
+    _addLines(lines: string[]): void;
+    toLines(): string[];
+}
+/**
+ * A dataframe-style grid: an index column, column labels, minimal padding, no rules.
+ *
+ * @remarks
+ * The form a values grid actually wants, and the reason it is not a GFM pipe table. Three things
+ * follow from the task the grid exists for — scanning a column for the value that does not match
+ * its neighbors:
+ *
+ * - **No box characters.** Pipes and the `|---|` rule are per-row overhead that carry no
+ *   information, and on a narrow screen they are what forces the wrap that breaks the column.
+ * - **Real A1 labels as index and header.** A1 addressing IS the coordinate system, and an index
+ *   plus `A B C D` columns preserves it natively — which is exactly what a CSV or a `1..n` index
+ *   would throw away.
+ * - **Per-cell alignment, one width per column.** A ragged column defeats the scan. Numbers
+ *   right and strings left is what makes the stray text in a numeric column visible at a glance,
+ *   so alignment is carried per cell and the header follows the column's dominant one.
+ */
+export declare class MarkdownFrameSection {
+    private readonly _parent;
+    private readonly _headers;
+    private readonly _colWidths;
+    private _indexWidth;
+    private readonly _rows;
+    constructor(_parent: MarkdownBuilder, _headers: string[]);
+    addRow(cells: (string | {
+        text: string;
+        alignment?: ITextFrame.HorizontalAlignment;
+    })[], index?: string): this;
+    endFrame(): MarkdownBuilder;
+    /** The alignment most of a column's cells use — what its header follows. */
+    private _columnAlignment;
+    private _renderLines;
+}
+//# sourceMappingURL=MarkdownBuilder.d.ts.map

package/types/src/markdown/MarkdownBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownBuilder.d.ts","sourceRoot":"","sources":["../../../../src/markdown/MarkdownBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,cAAc,CAAK;IAE3B;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAEtC,OAAO,CAAC,QAAQ;IAKhB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACnB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACnB,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACnB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IACrB,KAAK,IAAI,IAAI;IAEb,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAMlC;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAMhC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IACvB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM;IAC3B,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,SAAK,GAAG,MAAM;IAElC,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,oBAAoB;IAInD,gBAAgB;IAChB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIhC,OAAO,IAAI,MAAM,EAAE;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAM7B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAN3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;IACtC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmG;gBAGtG,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,EAAE;IAKrC,MAAM,CACJ,KAAK,EAAE,CAAC,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,UAAU,CAAC,mBAAmB,CAAA;KAAE,CAAC,EAAE,EAChF,KAAK,CAAC,EAAE,MAAM,GACb,IAAI;IAUP,QAAQ,IAAI,eAAe;IAK3B,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,YAAY;CAsBrB"}

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

@@ -0,0 +1,364 @@
+import { ICellRange, IAnchored, ICellRanges, INamed } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * Options for the feature sections.
+ */
+export interface AppendFeatureOptions {
+    /**
+     * Narrows `Counts` and the feature partition sections to these features.
+     *
+     * @defaultValue every public feature
+     *
+     * @remarks
+     * 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
+     * difference between an answer and a haystack.
+     *
+     * The scalar kinds are accepted and reach `Counts`; they have no partition to list, so they
+     * never produce a section.
+     */
+    features?: ICellRange.Feature | readonly ICellRange.Feature[];
+    /**
+     * Cap on regions listed per feature; the report notes truncation when exceeded.
+     *
+     * @defaultValue 200 — deferred to {@link appendRegionList}, the one place the default lives.
+     */
+    maxRegions?: number;
+    /**
+     * Profile the `Contentful` section's regions, as a standalone partition report does.
+     *
+     * @defaultValue false
+     *
+     * @remarks
+     * **This adds depth, never breadth.** Profiling describes the regions a partition already
+     * returned — it cannot produce more of them, so it is not the fragmentation that combining
+     * features causes. What it costs is report LENGTH: one line per series inside each profiled
+     * block, bounded by {@link maxProfiled} and by `ProfileRegionOptions.maxSeries`.
+     *
+     * Off by default because the two callers want different budgets, not because the answer is
+     * unwanted: a sheet report was directly asked about one sheet and can afford the depth, while
+     * a workbook report is routing across up to eight of them and profiles a few per sheet.
+     */
+    profile?: boolean;
+    /**
+     * Cap on regions profiled in the `Contentful` section — the rest list address and size only,
+     * and the listing says how many went undescribed.
+     *
+     * @defaultValue 12 — deferred to {@link appendRegionList}.
+     */
+    maxProfiled?: number;
+}
+/**
+ * Reporting order for the feature partitions: where the content is, then what was authored over
+ * it.
+ *
+ * @remarks
+ * Order only — **not a grouping.** Each feature is its own section headed by its own name,
+ * because a region *is* a feature partition and there is no category above it. A "Regions"
+ * heading over these would assert a thing that does not exist, and its empty case would read as
+ * "this sheet has no regions" — which cannot be true of any sheet with content.
+ *
+ * The formatting half is a set of authored layers, kept apart: direct style
+ * (`Fill`/`Border`/`NumberFormat`/`Alignment`/`Font`), conditional formatting and data validation
+ * are separate partitions and are never composed into a per-cell "what won" answer. Composition
+ * is both an expansion — a color scale produces one distinct range per cell — and lossy exactly
+ * where it matters, since a deliberately colored cell and one colored by an inherited band become
+ * indistinguishable.
+ */
+export declare const REPORTED_FEATURES: readonly ICellRange.Feature[];
+/**
+ * Parses a comma-separated feature list — the `--features fill,border` flag's value.
+ *
+ * @remarks
+ * Matching is case-insensitive against the enum's values, so `Fill`, `fill` and `numberFormat`
+ * all resolve; the enum's own spelling is what comes back. An unknown name **throws with the
+ * whole vocabulary** rather than being skipped — a silently dropped feature reads as "this
+ * sheet has no fills", which is the wrong answer rather than a short one.
+ */
+export declare function parseFeatures(value: string): ICellRange.Feature[];
+/** `A1:F11, 11×6` — the address plus its shape, in the same rows×columns form every region row uses. */
+export declare const describeExtent: (range: ICellRange) => string;
+/**
+ * The sheet name as a REFERENCE — quoted (`'My Sheet'`) exactly when a formula would need the
+ * quotes, unquoted (`Sheet1`) otherwise.
+ *
+ * @remarks
+ * Every place a report prints a sheet name prints it through this, so the name on a title or a
+ * roster row is directly usable in the next call's address argument. The SDK's own quoting rule
+ * (`AddressUtils.sheetNameToString`) decides, so the reports can never disagree with the formula
+ * language about which names need quoting.
+ */
+export declare const describeSheetName: (name: string | null | undefined) => string;
+/**
+ * `wb.getSheet("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
+ * name needing no formula quotes comes back bare — which is a syntax error the moment it is an
+ * argument. This quotes for the expression language a recovery hint is pasted into, so every
+ * name round-trips, apostrophes included.
+ */
+export declare const describeSheetCall: (range: ICellRange) => string;
+/** `A1:D10,F1:F20` — every range an item is anchored to, as one address. */
+export declare const describeRanges: (ranges: ICellRanges) => string;
+/**
+ * `Sheet1!A1:D10,F1:F20` — a ranged item's whole anchor, sheet-qualified.
+ *
+ * @remarks
+ * A conditional format, a data validation or any other {@link IAnchored} is anchored to a SET of
+ * ranges, which its own report leads with. Qualified for the same reason a title always is: the
+ * first line of a report is the next call's argument.
+ */
+export declare const describeQualifiedRanges: (ranges: ICellRanges) => string;
+/** `'My Sheet'!A1:F11, 11×6` — the extent, sheet-qualified the way a title carries it. */
+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".
+ *
+ * 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.
+ */
+export declare function appendKinds(md: MarkdownBuilder, range: ICellRange): void;
+/**
+ * Appends one section per feature partition, headed by the feature's own name.
+ *
+ * @remarks
+ * **A region is a feature partition, so the feature is the heading.** There is no umbrella
+ * section above these and deliberately so: a heading like `Regions` would name a category that
+ * does not exist, and its empty case — "Regions: None" — would assert something that cannot be
+ * true of a sheet holding content. What can be empty is one partition, and that is said by the
+ * section simply not being there.
+ *
+ * A feature with no regions is therefore elided; its absence needs no line. The addresses here
+ * are what a values read consumes, so the structural map and the follow-up call share one
+ * vocabulary.
+ *
+ * **Each heading carries both counts** — `Formula (401 cells · 2 regions)`. Cells is the
+ * decide-number (how much of this is here) and leads, everywhere; regions is the locate-number
+ * (how fragmented) — D6's line, on one heading. The ratio between them is the fragmentation
+ * signal: 401 cells in 2 regions is a model, 401 cells in 300 regions is noise, and the reader
+ * sees which before paying for a drill.
+ */
+export declare function appendRegions(md: MarkdownBuilder, range: ICellRange, options?: AppendFeatureOptions): void;
+/**
+ * Options for {@link appendNames}.
+ */
+export interface AppendNamesOptions {
+    /**
+     * Cap on listed names; the section notes truncation when exceeded.
+     *
+     * @defaultValue 200 — the standalone name manager's. The workbook report passes a tighter one.
+     */
+    maxNames?: number;
+    /**
+     * The section heading, without its count.
+     *
+     * @defaultValue `Names`
+     */
+    heading?: string;
+    /**
+     * How to recover the rows the cap ate — appended to the overflow line.
+     *
+     * @defaultValue a pointer at `getByName`
+     */
+    recovery?: string;
+    /**
+     * The full symbol table that identifier checks resolve against, when `names` is a subset.
+     *
+     * @defaultValue the `names` argument itself
+     *
+     * @remarks
+     * The roster often renders a FILTERED view — one kind's group, one sheet's intersecting names —
+     * and an identifier must not be reported missing merely because its target fell outside the
+     * filter. A caller rendering a subset passes the unfiltered collection here; tables included,
+     * since a bare `Sales` in an expression is a `named` token that resolves to a table.
+     */
+    symbols?: readonly INamed[];
+}
+/**
+ * A name's spelling as a formula would write it — qualified when it is scoped to one sheet.
+ *
+ * @remarks
+ * Decision over a `Scope` column: `'EU Ops'!Rate` is compact, distinguishes two names that differ
+ * only by scope without a second column to cross-read, and is exactly the text the next call takes
+ * as an argument. A blank scope column on every global name would cost more and say less.
+ */
+export declare const describeQualifiedName: (named: INamed) => string;
+/**
+ * Appends the defined-name roster — one row per name, sorted for triage.
+ *
+ * @remarks
+ * **The symbol table, at one altitude.** `=Revenue*(1+TaxRate)` is unreadable without it, and a
+ * name broken by a sheet delete is a root cause that produces no cell error until something
+ * references it. Names are bounded (tens of rows, a handful of tokens each), so they are shown in
+ * full by default; the cap is a guard against books that accumulated hundreds of junk names
+ * through sheet copying, not a budget.
+ *
+ * **One section, never split by kind.** A named formula and a named range are not separate
+ * listings: splitting them would defeat the sort below, letting a broken named formula sort under
+ * a healthy named range purely because of which section it landed in. Every question the
+ * distinction answers is already a mark on the row — whether `Refers To` is navigable
+ * (`=Sales!$B$2:$B$100` versus `=0.21`), `(volatile)`, `(does not resolve)`.
+ *
+ * **Broken names are their own block**, directly under the heading — `N do not resolve:` and a
+ * table whose `Error` column carries the cause (`#REF!`, `#NAME?: Gone`). A trailing
+ * `(does not resolve)` inside `Refers To` was the least findable place for the one fact that must
+ * be found: it landed at a varying x-position at the end of the widest column. The block's mere
+ * EXISTENCE is the alarm, its heading carries the count, and the `Error` column is populated on
+ * every row it prints — where the same column in one shared table would be blank padding on every
+ * healthy row. A healthy book pays nothing: no broken names, no block, exactly as `Hidden` and
+ * `Comment` only exist when some row has one.
+ *
+ * **Then the main table, sorted by dependents descending, alphabetical on ties.** A reader's
+ * order — load-bearing symbols, then trivia — and it makes the cap safe by construction, since
+ * truncation can only eat the tail. It needs no special case for zeros: they sink on their own,
+ * which is how hidden junk like `_FilterDatabase` disappears without being filtered.
+ *
+ * **Dependents counts cells AND names** — see {@link describeDependents}. A name referenced only
+ * by other names is load-bearing, and counting cells alone reported it as `unused` and sorted it
+ * to the bottom with the junk. A global name that is unused while a sheet-scoped twin wins the
+ * binding says `unused · shadowed` — the word alone reads as safe-to-delete, and the shadow is
+ * often exactly why nothing reaches it. There is deliberately no `Value` column: a name with relative
+ * references or implicit intersection evaluates PER CALLING CELL, so a single value is not well
+ * defined, and for a reference name the value is grid data — which structure reports never carry.
+ *
+ * `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;
+}
+/**
+ * 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.
+ *
+ * @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.
+ */
+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;
+/**
+ * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
+ *
+ * @remarks
+ * **Anchored by ranges, so the row leads with them rather than with a cell address.** These are
+ * the ranged items' own extents, which is the fact a region listing cannot give: a partition says
+ * which CELLS a rule reaches inside the report's scope, and this says what the rule itself covers —
+ * `A1:D10` even when the report is about `B2`. The two together are how a reader tells a rule that
+ * happens to clip this range from one written for it.
+ *
+ * The rules are listed in evaluation order, which is the order the collection holds them in: for
+ * conditional formats that order decides which of two rules paints a cell, so re-sorting the
+ * 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;
+/**
+ * Appends the sheet-level objects that intersect `range`: named ranges, hidden headers, tables,
+ * conditional formats and data validations.
+ *
+ * @remarks
+ * Scoped, not sheet-wide — a report about `A1:D4` that lists a table over `H40:M90` is
+ * answering a question nobody asked. The sheet report passes the used range, so at that scope
+ * the filter is a no-op and the two reports stay one code path.
+ *
+ * **A section with nothing in it is not printed.** Most sheets have no named ranges, no hidden
+ * headers and no tables, so the alternative is four headings of `None` on every report — pure
+ * 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;
+//# sourceMappingURL=appendSections.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"appendSections.d.ts","sourceRoot":"","sources":["../../../../src/markdown/appendSections.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,24 @@
+/**
+ * Where a listing stops.
+ *
+ * @remarks
+ * Every capped section answers the same question — *print the next row, or print the notice that
+ * says I am not going to?* — and near the end of a list the notice is the worse answer.
+ */
+/**
+ * How many of `total` to print, given a page size.
+ *
+ * @param total How many there are.
+ * @param pageSize The page — a caller's cap where they named one, otherwise the section's default.
+ *
+ * @returns `total` when the remainder is too short to be worth a truncation notice, else `pageSize`.
+ *
+ * @remarks
+ * Applied the same way whoever chose the page size, because it is a property of paging and not of
+ * provenance: a reader who asks for thirty and has thirty-two wants the thirty-two just as much as
+ * a reader who asked for nothing. What it needs is `total` up front, so it belongs to listings over
+ * something already counted — a name roster, a materialized partition — not to a streaming scan
+ * that would have to read further to find out.
+ */
+export declare const pageWithLookahead: (total: number, pageSize: number) => number;
+//# sourceMappingURL=caps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../../../../src/markdown/caps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,EAAE,UAAU,MAAM,KAAG,MAClB,CAAC"}

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

@@ -0,0 +1,46 @@
+import { ICellRange, ICellRegion, IStyle } from '@sheetxl/sdk';
+/**
+ * Describes one region's payload — the anchor cell's read for the feature that produced it.
+ *
+ * @remarks
+ * A region is uniform by construction, so a single line of payload describes every cell in it.
+ * Returning `null` means "this feature has nothing to say per region" (the address *is* the
+ * fact) and the listing prints the address alone.
+ */
+export interface RegionPayload {
+    (region: ICellRegion): string | null;
+}
+/**
+ * The payload describer for one feature, or `undefined` when the address is the whole fact.
+ *
+ * @remarks
+ * A region is uniform by construction, so the anchor cell's read describes every cell in it —
+ * that is what makes a payload one line rather than a column of repeats. It is also why the
+ * formula payload is honest for a block: `getRegions` groups formulas by canonical R1C1, so
+ * `D2:D4` really is one authored `=B2*C2`.
+ *
+ * **A payload is never a computed value.** `=B2*C2` is authored content, the same kind of fact
+ * as a fill color; `2398.8` is data, and data is a values read. This is the line that keeps the
+ * sheet report bounded.
+ *
+ * **A feature with no describer here prints its address alone**, which for most of them is a
+ * lie of omission rather than a fact — see the TODOs below. The goal is that every partition
+ * says something useful about what it found.
+ */
+export declare function regionPayload(feature: ICellRange.Feature, normal: IStyle | null): RegionPayload | undefined;
+/**
+ * One payload describer covering **every** feature a partition was built from.
+ *
+ * @remarks
+ * A refined partition is asked for precisely when the *relationship between* features is the
+ * question — `['formula', 'font']` pairs what each cell computes with the color a human sees, and
+ * a listing that showed only one half answered half of it. Each feature contributes its own
+ * payload and they join in the order the caller named them, so the row reads as the tuple the
+ * partition actually splits on.
+ *
+ * Features with nothing to say per region (`AutoTable`, `Unlock`) contribute nothing rather than
+ * an empty column, and a partition where none of them do returns `undefined` so the listing stays
+ * addresses-only.
+ */
+export declare function regionPayloads(features: readonly ICellRange.Feature[], normal: IStyle | null): RegionPayload | undefined;
+//# sourceMappingURL=describeRegionPayload.d.ts.map

package/types/src/markdown/describeRegionPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describeRegionPayload.d.ts","sourceRoot":"","sources":["../../../../src/markdown/describeRegionPayload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAczE;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;CACtC;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,UAAU,CAAC,OAAO,EAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,aAAa,GAAG,SAAS,CAoF3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,SAAS,UAAU,CAAC,OAAO,EAAE,EACvC,MAAM,EAAE,MAAM,GAAG,IAAI,GACpB,aAAa,GAAG,SAAS,CAU3B"}