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

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

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

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

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

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

@@ -1,4 +1,4 @@
-import { ICellRange, IAnchored, ICellRanges, INamed } from '@sheetxl/sdk';
+import { ICellRange, IAnchored, ICellRanges, ICellRegion, INamed, ISheet } 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,16 @@ export declare const describeQualifiedName: (named: INamed) => string;
  * `Hidden` and `Comment` appear only when some row has one — per block. `false` on every visible
  * row is token noise, and blank-means-normal is how these reports already speak.
  */
-export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): void;
-/**
- * Options for the dependency trees.
- */
-export interface AppendDependencyOptions {
-    /**
-     * How many hops from the subject to walk.
-     *
-     * @defaultValue 3
-     */
-    maxDepth?: number;
-    /**
-     * Cap on nodes per tree; the tree notes truncation when exceeded.
-     *
-     * @defaultValue 50
-     */
-    maxNodes?: number;
-}
-/** The calculation-graph surface shared by {@link ICell} and {@link ICellRange}. */
-export interface DependencySource {
-    getDirectPrecedents(): ICellRanges | null;
-    getPrecedents(): ICellRanges | null;
-    getDirectDependents(): ICellRanges | null;
-    getDependents(): ICellRanges | null;
-}
-/**
- * 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;
+export declare function appendNames(md: MarkdownBuilder, names: readonly INamed[], options?: AppendNamesOptions): Promise<void>;
 /**
- * How a graph member LABELS itself: its address, the sheet it lives on, and whether it is a name.
+ * The outline in a line — `rows 2 levels, 3 groups (1 collapsed) · columns 1 level, 1 group` —
+ * or `null` when nothing is grouped.
  *
  * @remarks
- * Shared by the tree and the flat {@link ICellRanges} listing, so the two cannot label the same
- * member differently — the flat list is the tree's rows without the hop structure, and a reader
- * comparing them is comparing the same text.
- *
- * A name member leads with its NAME: its address is only an anchor, and two names authored from
- * the same cell would otherwise print as identical, anonymous cells.
- *
- * The address comes back **unqualified**. A listing standing on one sheet says so once, in its
- * heading; a qualifier goes back on every row only when the collection spans sheets, which is the
- * caller's decision because only the caller has seen every member. A trailing `!` is `#REF!`, not
- * a qualifier, so it is left whole.
+ * Counts only: the groups themselves (level, span, summary, collapsed) are `IOutline.getGroups`,
+ * which is also what a script reads, so the report routes there instead of listing them.
  */
-export declare function describeNodeLabel(range: ICellRange): {
-    address: string;
-    sheet: string;
-    isName: boolean;
-};
-/**
- * A node's payload: the value for a single cell, the size for a range.
- *
- * @remarks
- * The whole point of walking as a tree rather than listing addresses — `1,204,880` beside
- * `Model!O30` is what makes the chain readable as a model rather than as a set of coordinates.
- * A formula node shows its expression too, because at that point the node explains itself.
- *
- * Shared with the flat {@link ICellRanges} listing (`renderRanges`) for the same reason
- * {@link describeNodeLabel} is: the flat list is these rows without the hop structure, so the two
- * shapes cannot be allowed to drift into describing one member two ways.
- */
-export declare function describeNode(range: ICellRange): string;
+export declare function describeOutline(sheet: ISheet): string | null;
 /**
  * One rule listing — `## Conditional Formats (2)` over `  A1:D10  > 100 → fill #FFFF00` rows.
  *
@@ -346,6 +272,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 +298,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, 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: ISheet, 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.