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

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

@@ -0,0 +1,22 @@
+import { ICell, IRange } from '@sheetxl/sdk';
+/** The reader's name for each check, in the order a report lists them. */
+export declare const ANOMALY_LABELS: ReadonlyMap<string, string>;
+/** `inconsistent formula` — the label, or the check's own name for one without a label. */
+export declare const anomalyLabel: (check: string) => string;
+/**
+ * One finding as a reader's line, its positions read at `cell`: `inconsistent formula · the cells
+ * above and below have =B2*2`.
+ *
+ * @remarks
+ * The evidence holds positions relative to the cell (R1C1), which is what lets a filled row share
+ * one finding. Read at the region's anchor they become the addresses a next call takes.
+ */
+export declare function describeAnomaly(anomaly: ICell.Anomaly, cell: ICell): string;
+/** Every finding at `cell`, `;`-joined; `null` when none fires. */
+export declare function describeAnomalies(cell: ICell): string | null;
+/**
+ * R1C1 references in `text` as A1, read from `at`: `=R[-1]C*2` at `B3` is `=B2*2`. Absolute
+ * parts take a `$`, as Excel writes them.
+ */
+export declare function r1c1ToA1(text: string, at: IRange.CellCoords): string;
+//# sourceMappingURL=describeAnomaly.d.ts.map

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

@@ -0,0 +1,72 @@
+import { IWorksheet, 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: IWorksheet): 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/describeExternalCitation.d.ts

@@ -0,0 +1,27 @@
+import { ICalculation, IWorkbook } from '@sheetxl/sdk';
+/** One external citation that resolves to nothing, and why. */
+export interface BrokenExternalCitation {
+    /** The scope as the formula spells it: `'[1]ex 1 - ibo'`. */
+    scope: string;
+    /** `no external link [1] — this workbook has none`. */
+    reason: string;
+    /** How many references in the formula carry this scope. */
+    uses: number;
+}
+/**
+ * The external citations in a formula that resolve to nothing: a `[n]` past the workbook's links,
+ * or a sheet its link does not list. Each evaluates to `#REF!`.
+ *
+ * @remarks
+ * Excel stores a reference to a sheet that does not exist as a reference to another workbook, so
+ * `'[1]ex 1 - ibo'!F27` is often a misspelled local sheet whose link was later lost (LibreOffice
+ * drops every link on save and keeps the `[1]`). The scope's text is the only record of what was
+ * meant, so it is quoted back rather than summarized.
+ *
+ * A citation that binds is never reported. A DDE or OLE slot holds its position without a book, so
+ * a `[n]` naming one is not broken either.
+ */
+export declare function findBrokenExternalCitations(tokens: readonly ICalculation.FormulaToken[], workbook: IWorkbook | null | undefined): BrokenExternalCitation[];
+/** `cites '[1]ex 1 - ibo': no external link [1] — this workbook has none`, `; `-joined; `''` when none. */
+export declare function describeBrokenExternalCitations(citations: readonly BrokenExternalCitation[]): string;
+//# sourceMappingURL=describeExternalCitation.d.ts.map

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

@@ -0,0 +1,186 @@
+import { ICellRange, ICellRegion, IRange, IWorksheet, ICellStyle } 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: IWorksheet, feature: ICellRange.Feature, normal: ICellStyle | 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: ICellStyle): string | null;
+export {};
+//# sourceMappingURL=describeHistogram.d.ts.map

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

@@ -1,4 +1,4 @@
-import { ICellRange, ICellRegion, IStyle } from '@sheetxl/sdk';
+import { ICellRange, ICellRegion, ICellStyle } from '@sheetxl/sdk';
 /**
  * Describes one region's payload — the anchor cell's read for the feature that produced it.
  *
@@ -27,7 +27,7 @@ export interface RegionPayload {
  * 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;
+export declare function regionPayload(feature: ICellRange.Feature, normal: ICellStyle | null): RegionPayload | undefined;
 /**
  * One payload describer covering **every** feature a partition was built from.
  *
@@ -38,9 +38,9 @@ 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.
  */
-export declare function regionPayloads(features: readonly ICellRange.Feature[], normal: IStyle | null): RegionPayload | undefined;
+export declare function regionPayloads(features: readonly ICellRange.Feature[], normal: ICellStyle | null): RegionPayload | undefined;
 //# sourceMappingURL=describeRegionPayload.d.ts.map

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

@@ -1,4 +1,4 @@
-import { ICondition, IConditionalFormat, IDataValidation, IStyle } from '@sheetxl/sdk';
+import { ICondition, IConditionalFormat, IDataValidation, ICellStyle } from '@sheetxl/sdk';
 /**
  * The differential style a rule applies — the OOXML `dxf`, as the facets it actually names.
  *
@@ -7,7 +7,7 @@ import { ICondition, IConditionalFormat, IDataValidation, IStyle } from '@sheetx
  * property present in it is by construction something the rule author set. Absent facets are not
  * reported — a rule that only fills says `fill #FFFF00` and nothing about the font it leaves alone.
  */
-export declare const describeRuleStyle: (style: IStyle.Properties | null | undefined) => string | null;
+export declare const describeRuleStyle: (style: ICellStyle.Properties | null | undefined) => string | null;
 /**
  * A value→visual mapping — `colorScale · min #FFFFFF → max #FF0000`.
  *
@@ -46,9 +46,9 @@ export declare const describeDataValidation: (validation: IDataValidation) => st
  * @remarks
  * **A list validation IS a vocabulary**, and frequently the only place a sheet states one: what
  * `Region` is allowed to contain is exactly what a writer needs before writing, and what a reader
- * needs to recognize `ZZ` as wrong rather than as new. The rule text reports it as a count (`In 3
- * Items`) because a filter dropdown cannot show a hundred values, so a report that only carried the
- * rule left the vocabulary unreadable.
+ * needs to recognize `ZZ` as wrong rather than as new. The rule text reports a picked set as a
+ * count (`List 3 Items`) because a filter dropdown cannot show a hundred values, so a report
+ * that only carried the rule left the vocabulary unreadable.
  *
  * A list sourced from cells carries its formula instead of its values — that IS the answer, and it
  * is the address to read next.

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

@@ -0,0 +1,41 @@
+import { IShape, IGroup, IMovable, IMovableCollection } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * A shape's text as one quoted row cell.
+ *
+ * @remarks
+ * Quoted, and never paraphrased, so it reads as what it is: content of the workbook, written by
+ * whoever could edit the file, not a statement of the report's. Newlines become a visible mark
+ * rather than a space because authors break lines on purpose — a callout listing three steps is
+ * three lines.
+ *
+ * @param max The cap, or `null` to print all of it.
+ * @param recovery The call that prints the rest; only read when the text is cut.
+ */
+export declare const quoteShapeText: (text: string, max: number | null, recovery: string) => string;
+/**
+ * The facts of a shape a report states beyond its placement: what it is, what it says, how it is
+ * drawn, what it links to and what it is glued to. Each fact only where the shape states it or it
+ * is not the default, so a plain rectangle stays a few lines.
+ *
+ * @remarks
+ * Read from the shape's JSON, which is the model: the accessors cover only its type, text and
+ * adjust values. A fill or line the shape does not state is named by where it comes from (its
+ * theme style) rather than resolved to a color — the theme is the workbook's, and the report says
+ * which reference to follow.
+ */
+export declare function appendShapeFacts(md: MarkdownBuilder, shape: IShape): void;
+/** `getContent()` as a group, when it is one. */
+export declare const groupOf: (movable: IMovable) => IGroup | null;
+/**
+ * A group's members, in z-order, one line each and indented by depth; a nested group's members
+ * beneath it. A picture is named by its file, a shape by its preset, and what is written on a
+ * member rides its line.
+ */
+export declare const appendGroupMembers: (md: MarkdownBuilder, members: IMovableCollection, depth: number) => void;
+/**
+ * The facts of a group a report states beyond its placement: what it holds, in z-order, and the
+ * fill it gives members that take the group's.
+ */
+export declare function appendGroupFacts(md: MarkdownBuilder, group: IGroup): void;
+//# sourceMappingURL=describeShape.d.ts.map

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

@@ -1,4 +1,4 @@
-import { IColor, IStyle } from '@sheetxl/sdk';
+import { IColor, ICellStyle } from '@sheetxl/sdk';
 /**
  * One-line descriptions of a style's authored facets.
  *
@@ -31,7 +31,7 @@ export declare const describeColor: (color: IColor | null | undefined) => string
  * paints for `solid` too. The fill's generic `getColor()` returns the *background*, which is
  * how a yellow cell once reported `pattern #000000 (auto)`.
  */
-export declare const describeFill: (style: IStyle) => string | null;
+export declare const describeFill: (style: ICellStyle) => string | null;
 /**
  * Describes borders — the edges that carry a style, each as `edge style color`.
  *
@@ -42,7 +42,7 @@ export declare const describeFill: (style: IStyle) => string | null;
  * `vertical` are `null` on a cell-scoped style, which is why the region payload reads through
  * `getRange()`.
  */
-export declare const describeBorder: (style: IStyle) => string | null;
+export declare const describeBorder: (style: ICellStyle) => string | null;
 /**
  * The border as a list of parts, identical edges grouped.
  *
@@ -54,11 +54,11 @@ export declare const describeBorder: (style: IStyle) => string | null;
  * genuinely distinct strokes produce distinct parts — which is what makes the multi-line form
  * (one part per line) worth printing.
  */
-export declare const describeBorderParts: (style: IStyle) => string[];
+export declare const describeBorderParts: (style: ICellStyle) => string[];
 /** Describes a number format — the format string itself is the payload. */
-export declare const describeNumberFormat: (style: IStyle) => string | null;
+export declare const describeNumberFormat: (style: ICellStyle) => string | null;
 /** Describes alignment — only the parts that differ from `normal`. */
-export declare const describeAlignment: (style: IStyle, normal: IStyle) => string | null;
+export declare const describeAlignment: (style: ICellStyle, normal: ICellStyle) => string | null;
 /** Describes a font — only the parts that differ from `normal`. */
-export declare const describeFont: (style: IStyle, normal: IStyle) => string | null;
+export declare const describeFont: (style: ICellStyle, normal: ICellStyle) => string | null;
 //# sourceMappingURL=describeStyle.d.ts.map

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

@@ -0,0 +1,19 @@
+import { IRange, IWorksheet } 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'`): the first text cell at the
+ * line's edge of the cell's current region, else the nearest text before it on that line. The
+ * SDK's label model, which the anomaly checks read too.
+ *
+ * `null` when the cell is itself the first cell of the line or nothing before it is text.
+ */
+export declare function findLabel(sheet: IWorksheet, 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,6 +1,8 @@
+export * from './appendDependencies';
 export * from './appendSections';
 export * from './describeRegionPayload';
 export * from './describeRule';
+export * from './describeShape';
 export * from './describeStyle';
 export * from './MarkdownBuilder';
 export * from './parseRenderOptions';
@@ -11,13 +13,16 @@ export * from './renderConditionalFormat';
 export * from './renderCounts';
 export * from './renderDataValidation';
 export * from './renderFormula';
+export * from './renderModules';
 export * from './renderMovable';
 export * from './renderNames';
+export * from './renderPageLayout';
+export * from './renderProtection';
 export * from './renderRecords';
 export * from './renderRanges';
 export * from './renderRegions';
 export * from './renderResult';
-export * from './renderSheet';
+export * from './renderWorksheet';
 export * from './renderStats';
 export * from './renderStyle';
 export * from './renderTable';

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,12 +1,13 @@
 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';
 import { RenderRegionsOptions } from './renderRegions';
-import { RenderSheetOptions } from './renderSheet';
+import { RenderWorksheetOptions } from './renderWorksheet';
 import { RenderValuesOptions } from './renderValues';
 /**
  * The renderer registry: one entry per renderable kind.
@@ -17,7 +18,7 @@ import { RenderValuesOptions } from './renderValues';
  * Renderer.Entry.is}. Both paths land on the same entry, so a kind cannot render differently
  * depending on how it was reached.
  *
- * Detection uses the SDK's `isI*` runtime brands (`isIWorkbook`, `isISheet`, `isICellRange`,
+ * Detection uses the SDK's `isI*` runtime brands (`isIWorkbook`, `isIWorksheet`, `isICellRange`,
  * …) — the SDK's own convention for runtime type checking. The registry knows the SDK's
  * interfaces, never its classes, and a brand survives any transport that preserves methods.
  */
@@ -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 & RenderWorksheetOptions & 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.
  *
@@ -90,6 +99,11 @@ export declare function resolveRenderer(target: unknown): Renderer.Entry | null;
  * and it is the whole async surface: the renderers themselves are synchronous, and a caller
  * invoking one directly is responsible for settling first.
  *
+ * A render can itself start calculation: a cell's effective style reads a conditional format
+ * whose whole-column answer is evaluated only where it is read, and the read asks for it. When a
+ * render leaves the engine calculating, it settles again and renders again, so the report carries
+ * what the first read asked for.
+ *
  * @throws If no registered renderer accepts the object.
  */
 export declare function renderMarkdown(workbook: IWorkbook | null, target: unknown, options?: Renderer.Options): Promise<string>;