@sheetxl/query 0.7.28-beta.4 → 0.8.0-beta.2

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 } 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`
@@ -118,26 +118,12 @@ 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;
 /**
@@ -161,6 +147,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 +247,7 @@ 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;
-}
-/**
- * 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;
+export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): Promise<void>;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *
@@ -346,6 +263,18 @@ 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`, in collection order.
+ *
+ * @remarks
+ * Scope-checked, not merely rectangle-checked: a name pointing at `Sheet2!A1:D4` overlaps this
+ * sheet's `A1:D4` as coordinates and is a different region entirely. 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 +289,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/describeChart.d.ts

@@ -0,0 +1,72 @@
+import { ISheet, ICellRange, ICellRanges, IChart, IMovable } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/** The chart a movable holds, or `null` for any other content. */
+export declare const chartOf: (movable: IMovable) => IChart | null;
+/**
+ * `line · 8 series · values NOI!C4:J111 · categories NOI!B4:B111` — a chart as one listing row's
+ * prose, or `null` when nothing about it is known.
+ *
+ * @remarks
+ * What the chart PLOTS leads, because it is the fact that ties the floating layer to the cells: it
+ * says which ranges the author treats as the output, and it is what breaks when the sheet under
+ * it is restructured. Series that do not collapse to one block are counted here and listed on the
+ * chart's own report.
+ *
+ * Each range is labeled with its role. `A by B` read as a formula to anyone who did not already
+ * know the convention, and `by` is the word the series line uses for orientation (`by column`).
+ */
+export declare function describeChartRow(chart: IChart): string | null;
+/**
+ * A chart's facts as `label`/`value` pairs — the lines a `Charts` section indents under its row,
+ * the way a `Tables` section does.
+ *
+ * @remarks
+ * The type is not here: it is the row's own column. Series that do not tile are counted, and
+ * listed one by one on the chart's own report.
+ */
+export declare function describeChartDetails(chart: IChart): [label: string, value: string][];
+/** `line`, for the type column of a `Charts` row; `''` where the model has no answer. */
+export declare const describeChartType: (chart: IChart) => string;
+/**
+ * The `Type` / `Title` / `Series` / `Axes` facts of a chart's own report.
+ *
+ * @remarks
+ * `Title: (none)` is printed rather than omitted: that a chart is untitled is information, and a
+ * reader asked to tidy a model wants it. An axis with no title says so for the same reason — axis
+ * titles are where a chart states its units, often the only place anything does.
+ */
+export declare function appendChartFacts(md: MarkdownBuilder, chart: IChart): void;
+/** A series reference that no longer names cells. */
+export interface BrokenChartReference {
+    movable: IMovable;
+    /** `series "South" values Data!#REF!` */
+    detail: string;
+}
+/**
+ * Every series on `sheet` whose name, values or categories reference is `#REF!`.
+ *
+ * @remarks
+ * A broken series reference is an audit finding exactly like one in a formula — the chart has
+ * stopped plotting what its author pointed it at — and no cell carries it, so no cell scan finds it.
+ */
+export declare function collectBrokenChartReferences(sheet: ISheet): BrokenChartReference[];
+/** A chart that plots the subject of a report, or something computed from it. */
+export interface ChartReader {
+    movable: IMovable;
+    /** `true` when a series names the subject's own cells; `false` when it names cells that depend on them. */
+    direct: boolean;
+}
+/**
+ * The charts that read `subject`, or that read what depends on it.
+ *
+ * @remarks
+ * A chart is a dependent the calculation graph does not hold: it reads cells and is changed by
+ * them, and nothing recalculates it. For "what else moves if I write here" it belongs in the same
+ * answer, so this is the graph's dependents carried one step further — into the floating layer.
+ *
+ * @param dependents The subject's full downstream reach, as the graph answers it.
+ */
+export declare function findChartReaders(subject: ICellRange, dependents: ICellRanges | null): ChartReader[];
+/** `Charts!B2:H15 "Chart 1"`, marked when the chart reads the subject only through its dependents. */
+export declare const describeChartReader: (reader: ChartReader) => string;
+//# sourceMappingURL=describeChart.d.ts.map

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

@@ -0,0 +1,186 @@
+import { ICellRange, ICellRegion, IRange, ISheet, IStyle } from '@sheetxl/sdk';
+/**
+ * Per-attribute histograms for the style feature sections.
+ *
+ * @remarks
+ * A style partition lists blocks; a reader wants **conventions**: which colors mean input, how
+ * many fonts there are, whether one cell is formatted differently from its row. A histogram per
+ * *attribute* answers that on one line each — `color blue ×216 · white ×18 · #0070C0 ×1 R13` — and
+ * degrades to a count when there is no convention to find.
+ *
+ * Pipeline, per feature: **project** each region's authored style onto one attribute → **coalesce**
+ * adjacent rectangles with the same projected value (a region is uniform in the whole feature,
+ * so `bold 10pt` and `10pt` are two regions with one family) → **promote** whole-column and
+ * whole-row rectangles to their own tiers, the way the file format does, so a column style is
+ * named once instead of counted as a million cells → **histogram** the cell tier.
+ *
+ * Every count is cells, never blocks. Content cells lead — the intersection with the
+ * `Contentful` partition — and the styled cells that hold nothing follow in parentheses, so a
+ * format over empty cells (`Currency 0dp ×0 (+1 blank) K2`) is stated rather than hidden. A value that lives
+ * in one block prints its address whatever its size; a scattered one prints its largest block
+ * and how many more.
+ *
+ * **Only authored differences are histogrammed.** An attribute equal to the workbook's `Normal`
+ * style is not a choice anyone made — every cell has *some* family — so it does not appear; the
+ * base itself is stated once, on the `normal` line, which is where "Calibri is the base" comes
+ * from without any clustering.
+ */
+/** A rectangle in sheet coordinates, closed on both ends. */
+type Rect = Readonly<IRange.Coords>;
+/**
+ * Merges adjacent rectangles that share a key into maximal rectangles.
+ *
+ * @remarks
+ * Greedy: a column pass joins horizontal neighbors with equal row extents, a row pass joins
+ * vertical neighbors with equal column extents, repeated until nothing merges. Not guaranteed
+ * minimal, but the input is already a partition (no overlaps), the count is blocks not cells, and
+ * the store's own seams are exactly the horizontal-then-vertical cuts this undoes.
+ */
+export declare function coalesceRects<T extends Rect & {
+    key: string;
+}>(rects: readonly T[]): T[];
+/** One value of one attribute: where it is and how much of it there is. */
+export interface HistogramEntry {
+    /** Display form of the value. */
+    label: string;
+    /** Cells carrying the value that also hold content. */
+    content: number;
+    /** All cells carrying the value (cell tier only — never a whole column). */
+    styled: number;
+    /** The value's blocks, largest first. */
+    blocks: readonly Rect[];
+}
+/**
+ * Options for {@link describeHistogramLine}.
+ */
+export interface HistogramLineOptions {
+    /** Values printed in full before the line degrades to a count. @defaultValue 8 */
+    maxValues?: number;
+    /** Above this many distinct values the line leads with the count, not the values. @defaultValue 20 */
+    manyDistinct?: number;
+    /** How to get the rest — appended after `+n more`. */
+    recovery?: string;
+    /**
+     * A label to leave off the line — the attribute's own name, for a boolean attribute whose
+     * value IS its name (`bold  87` rather than `bold  bold 87`).
+     */
+    hideLabel?: string;
+    /**
+     * How a count reads: `cells` (`blue ×216 (+105 blank)` — content cells, then the styled cells
+     * holding nothing) for a style attribute, `times` (`2.5 ×4`) for a value, whose count is
+     * occurrences and has no second figure.
+     *
+     * @defaultValue `'cells'`
+     */
+    countStyle?: 'cells' | 'times';
+}
+/** Width of the attribute-name column; every line of a histogram section aligns on it. */
+export declare const HISTOGRAM_LABEL_WIDTH = 10;
+/**
+ * One histogram line — the values of one attribute, most common first, degrading to a count.
+ *
+ * @remarks
+ * The flood rule, stated once for every histogram (style attributes, formulas, values):
+ *
+ * 1. Up to `maxValues` distinct values print in full, sorted by content cells (then styled).
+ * 2. Beyond that, the top half of the budget prints, then the **rarest values that hold
+ *    content** — a one-off format on a data cell is the finding, and a sort by count alone
+ *    would bury it — then `+n more` with the call that lists everything.
+ * 3. Beyond `manyDistinct`, the line leads with the count and says **no convention** when the
+ *    most common value does not even cover half the content: a random-color sheet is described
+ *    by its count, not by a sample of its colors, and it costs one line however many there are.
+ */
+export declare function describeHistogramLine(entries: readonly HistogramEntry[], options?: HistogramLineOptions): string;
+/**
+ * `Accounting 1dp` — the dialog category plus its decimals, so ten spellings of one intent read
+ * as one value. `General` is the absence of a format and contributes nothing.
+ */
+export declare function describeNumberFormatCategory(code: string | null | undefined): string | null;
+/** Whether a feature gets a histogram. */
+export declare const hasStyleHistogram: (feature: ICellRange.Feature) => boolean;
+/**
+ * One feature's histogram: the tier lines and one line per attribute, ready to append.
+ */
+export interface StyleHistogram {
+    /** Distinct authored payloads across every region of the feature. */
+    distinct: number;
+    /**
+     * Styled cells in the cell tier, inside the used range — the finite number a heading can
+     * carry. The column and row tiers are named on their own lines, never counted.
+     */
+    cells: number;
+    /** `normal  Arial Narrow · 11pt · #000000` — what `Normal` says about this feature; see {@link describeNormal}. */
+    normal: string | null;
+    /** `sheet` / `columns` / `rows` tier lines, each `label  runs  payload`. */
+    tiers: string[];
+    /**
+     * `family  Open Sans ×355 (+230 blank) B14:M25, +38 blocks · …`, one per attribute with a value —
+     * or, for number formats, one row per category (see `describeNumberFormatRows`).
+     */
+    attributes: string[];
+}
+/**
+ * Builds the histogram for a style feature over a whole sheet.
+ *
+ * @remarks
+ * Reads the sheet's **entire** partition rather than the used range's, because a column style
+ * is only recognizable unclipped: the used-range view cuts `O:Q` to `O1:Q43` and it looks like a
+ * block. Cell counts are then taken inside the used range, where finite numbers live.
+ */
+export declare function describeStyleHistogram(sheet: ISheet, feature: ICellRange.Feature, normal: IStyle | null, options?: HistogramLineOptions & {
+    /** The sheet's contentful rectangles, when the caller already has them (one partition serves every feature). */
+    content?: readonly IRange.Coords[];
+}): StyleHistogram | null;
+/** The formula section's histogram lines. */
+export interface FormulaHistogram {
+    /** Distinct formulas by R1C1 text — `=SUM(B5:B7)` and `=SUM(C5:C7)` are one. */
+    distinct: number;
+    /** `distinct   =R[-3]C-R[-1]C ×26 B11:N11, +1 block · …` and `functions  SUM ×44 · no function ×52`. */
+    lines: string[];
+}
+/**
+ * Builds the formula section's histograms from its partition.
+ *
+ * @remarks
+ * The partition already groups by R1C1 — a region IS one formula filled across cells — so the
+ * `distinct` line is the partition re-keyed: the same R1C1 in several regions (a total column
+ * split by blank rows) is one value with several blocks. A one-off R1C1 in a row of thirteen is
+ * the H26 finding, printed with its address. `functions` counts cells, not regions, so `SUM ×44`
+ * is how many cells sum; `no function` is arithmetic-only cells — on a P&L that is most of them.
+ *
+ * `most complex` is deliberately absent: by function count every formula on a typical model ties
+ * at one, and a tie printed as a superlative is a lie. It arrives with the precedents depth.
+ */
+export declare function describeFormulaHistogram(regions: readonly ICellRegion[], options?: HistogramLineOptions): FormulaHistogram | null;
+/**
+ * The kind census of `range` — `number 864 · date 108 · text 10` — largest first.
+ *
+ * @remarks
+ * **Disjoint, so the counts sum to the contentful cells.** Every cell is counted under exactly
+ * one kind, which is what lets a reader check the census against the heading above it; a census
+ * whose lines overlap cannot be told from one that is wrong.
+ *
+ * A formula cell's value is a number or a string too, so the typed counts alone say `number 313`
+ * where 96 of those are computed; the reader wants how much was TYPED (the inputs) against how
+ * much is formula (the model). Formula cells are counted once, under `formula`, and their values
+ * are subtracted from the typed kinds — read off the formula partition's own stats.
+ *
+ * `date` is carved out of `number` the same way: a date IS a number, under a date-category format,
+ * and a column of them is a time axis — the one fact about a block of numbers that changes how
+ * every other column in it is read.
+ */
+export declare function countKinds(range: ICellRange, formulaRegions: readonly ICellRegion[]): [label: string, count: number][];
+/** The census as one row's prose: `number ×217 · formula ×96 · text ×45`, or `null` when empty. */
+export declare function describeKinds(range: ICellRange, formulaRegions: readonly ICellRegion[]): string | null;
+/**
+ * What the workbook's `Normal` style says about `feature`, or `null` when it says nothing.
+ *
+ * @remarks
+ * **The style of every cell no section lists.** A font always has one — and the font lines are
+ * differences from it, so it is always stated. For the rest `Normal` is nearly always empty, and
+ * then there is no line; but a `Normal` that carries a fill or a number format paints every
+ * untouched cell in the book, and no region reports it, because nobody authored it on a cell.
+ */
+export declare function describeNormal(feature: ICellRange.Feature, normal: IStyle): string | null;
+export {};
+//# sourceMappingURL=describeHistogram.d.ts.map

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

@@ -38,7 +38,7 @@ export declare function regionPayload(feature: ICellRange.Feature, normal: IStyl
  * 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
+ * Features with nothing to say per region (`AutoTable`) contribute nothing rather than
  * an empty column, and a partition where none of them do returns `undefined` so the listing stays
  * addresses-only.
  */

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

@@ -0,0 +1,26 @@
+import { IRange, ISheet } from '@sheetxl/sdk';
+/** A label and where it was read from. */
+export interface FoundLabel {
+    text: string;
+    address: string;
+}
+/**
+ * The text that labels a cell's row (`'row'`) or column (`'column'`).
+ *
+ * @remarks
+ * Deterministic, and the address is always returned so a reader can judge it:
+ *
+ * 1. The first cell of the line within the cell's current region (Ctrl+Shift+*), when it is text —
+ *    the row label at the left edge of the block, the header at its top.
+ * 2. Otherwise the nearest text cell before the cell on that line — leftward for a row, upward for
+ *    a column. Only contentful cells are visited, so the walk costs the populated cells between,
+ *    not the distance; there is no cap, because a cap is only a different arbitrary answer.
+ *
+ * `null` when the cell is itself the first cell of the line or nothing before it is text.
+ */
+export declare function findLabel(sheet: ISheet, cell: IRange.CellCoords, axis: 'row' | 'column'): FoundLabel | null;
+/** `"JUN" (G4)` — a label as the reports print it. */
+export declare const describeLabel: (label: FoundLabel | null) => string | null;
+/** 0-based column index to its A1 letter. */
+export declare function columnLetter(index: number): string;
+//# sourceMappingURL=findLabels.d.ts.map

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

@@ -1,3 +1,4 @@
+export * from './appendDependencies';
 export * from './appendSections';
 export * from './describeRegionPayload';
 export * from './describeRule';
@@ -11,8 +12,10 @@ export * from './renderConditionalFormat';
 export * from './renderCounts';
 export * from './renderDataValidation';
 export * from './renderFormula';
+export * from './renderModules';
 export * from './renderMovable';
 export * from './renderNames';
+export * from './renderProtection';
 export * from './renderRecords';
 export * from './renderRanges';
 export * from './renderRegions';

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

@@ -1,4 +1,5 @@
 import { ICellRange, ICellRegion } from '@sheetxl/sdk';
+import { FoundLabel } from './findLabels';
 /**
  * What {@link profileRegion} needs to read — the anchor cell and the extent, nothing a partition
  * knows that a plain range does not.
@@ -48,6 +49,10 @@ export interface ProfileRegionOptions {
  * exactly one, and a block has one per column (or row). This is the same discipline that keeps a
  * range from rendering cell facets — bounded by construction rather than by a limit that has to
  * fire.
+ *
+ * Data for a caller, never printed: a listing row already carries the size (`1×1`, `110×1`) and
+ * the header note, so a shape word beside them is a second vocabulary for the same fact — and
+ * `table` has to stay free to mean an authored {@link ITable}.
  */
 export type RegionShape = 'cell' | 'list' | 'table' | 'block';
 /**
@@ -58,7 +63,7 @@ export type RegionShape = 'cell' | 'list' | 'table' | 'block';
  */
 export interface RegionProfile {
     shape: RegionShape;
-    /** The one-line description that sits beside the address — `table · header row 1`. */
+    /** The one-line description that sits beside the address — `header row 1`, or a 1×1's value. */
     summary: string;
     /** One line per column (or row); empty for `cell` and `list`, whose profile is in `summary`. */
     series: string[];
@@ -88,6 +93,56 @@ export interface RegionProfile {
  *   elision is explicit, per the same rule that governs every truncated listing here.
  */
 export declare function profileRegion(region: ProfileSource, options?: ProfileRegionOptions): RegionProfile;
+/** A line the stats leave out, and why. */
+export interface TotalsLine {
+    /** Absolute row (or column, on a block profiled by row). */
+    index: number;
+    label: FoundLabel | null;
+    /** Set on the first line only when it was found by value: how it compares with the Σ above it. */
+    sums?: TotalsSums;
+}
+/** How a totals line's values compare with the sums of the body above them. */
+export interface TotalsSums {
+    matches: number;
+    candidates: number;
+    /** The line holds no formulas. */
+    typed: boolean;
+    /** The sums run down columns (the line is a row) rather than across rows. */
+    byColumn: boolean;
+    /** The cells that do not equal their Σ — `H26 text`, `C26 400 ≠ Σ 411`. */
+    misses: string[];
+}
+/** Where a block's body stops. */
+export interface Totals {
+    /** The block runs down its rows (`true`) or across its columns. */
+    byColumn: boolean;
+    /** Absolute index of the first line left out of the body. */
+    start: number;
+    /** Every line from {@link start} to the block's end. */
+    lines: TotalsLine[];
+    /** The profile summary's fragment — `rows 26:27 not profiled: …`. */
+    note: string;
+}
+/**
+ * Where a block's body stops: the first line whose values equal the Σ of the body above them.
+ *
+ * @remarks
+ * One deterministic test, the same for a `=SUM` row and a pasted one — a total equals the sum it
+ * totals by value, however it was entered. It needs two matches and a majority of the numeric
+ * series, so a coincidence in one column does not end a block. A table's totals row is taken as
+ * authored.
+ *
+ * Every line from there to the end of the block is left out of the stats, and each is named with
+ * its label so a reader can see what was set aside: the total, and whatever runs on below it
+ * (`Earnings Before Interest & Taxes` under `Total Expenses`). Labels are reported, never
+ * interpreted — deciding by its wording that a line is "a total" is the call a reader makes better.
+ *
+ * The first line's comparison is part of the fact: `typed` when it holds no formulas, and the cells
+ * that do not match, which on a pasted total are the finding.
+ */
+export declare function detectTotals(range: ICellRange, maxProfileCells?: number): Totals | null;
+/** `= Σ above (13 of 13)` / `typed, = Σ above (12 of 13; H26 text)` / `= Σ to the left (2 of 2)`. */
+export declare function describeSums(sums: TotalsSums): string;
 /**
  * Per-kind stats, pooled across the WHOLE range regardless of column — "what's actually in here,
  * broken down by type" in one shot, as opposed to {@link profileSeries}'s per-column breakdown.

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

@@ -1,7 +1,8 @@
 import { IWorkbook } from '@sheetxl/sdk';
-import { AppendDependencyOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
 import { RenderCellRangeOptions } from './renderCellRange';
 import { RenderFormulaOptions } from './renderFormula';
+import { RenderModulesOptions } from './renderModules';
 import { RenderNamesOptions } from './renderNames';
 import { RenderRecordsOptions } from './renderRecords';
 import { RenderRangesOptions } from './renderRanges';
@@ -31,7 +32,7 @@ export declare namespace Renderer {
      * alternative is making the caller name the kind, which is the dispatch the registry exists
      * to remove.
      */
-    type Options = RenderCellRangeOptions & RenderSheetOptions & RenderRegionsOptions & RenderValuesOptions & RenderFormulaOptions & RenderRecordsOptions & RenderNamesOptions & RenderRangesOptions & AppendDependencyOptions;
+    type Options = RenderCellRangeOptions & RenderSheetOptions & RenderRegionsOptions & RenderValuesOptions & RenderFormulaOptions & RenderRecordsOptions & RenderNamesOptions & RenderRangesOptions & RenderModulesOptions & AppendDependencyOptions;
     /**
      * One renderable kind.
      */
@@ -54,6 +55,14 @@ export declare namespace Renderer {
  * must be read as a table rather than as its first element or as N reports.
  */
 export declare const RENDERERS: readonly Renderer.Entry[];
+/**
+ * The name of every renderable kind, in dispatch order.
+ *
+ * @remarks
+ * What a host's help text lists. Derived, because a hand-written copy of this list is a second
+ * registry that nothing keeps in step with the first.
+ */
+export declare const RENDERABLE_KINDS: readonly string[];
 /**
  * Thrown by {@link renderMarkdown} when nothing in the registry accepts the value.
  *