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

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

@@ -1,23 +1,25 @@
 import { ICell } from '@sheetxl/sdk';
-import { AppendDependencyOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
 /**
- * Renders a cell's report: value, formula, spans, spill, the effective style, and its position in
- * the dependency graph.
+ * Renders a cell's report: value, formula, the block it sits in, whether it agrees with its
+ * siblings, its reach through the dependency graph, and the effective style.
  *
  * @remarks
+ * A cell is usually arrived at cold — a chat mention, a grep hit, a node in someone else's tree —
+ * so the report orients before it details: which block this is and what its labels say, whether
+ * this formula is the same as the ones beside it, and how much of the model it reads and feeds.
+ * Each of those is an index read, not a scan.
+ *
  * A cell is the one altitude where **resolved effect** belongs. A range reports style as authored
  * layers and never composes them, because composition is an expansion — a banded table is one
  * authored fact and an unbounded number of effective ranges. For a single cell the expansion is
  * one row, and "what does a human actually see here" is the question being asked, so `getStyle()`
- * is read rendered rather than direct.
- *
- * The dependency graph, by contrast, is NOT cell-only. It is indexed by range, so a range
- * answers the same four questions in one call and {@link renderCellRange} reports them too — the
- * cell form is that one over a 1×1.
+ * is read rendered rather than direct, and the line says so.
  *
  * Facets that are not present are omitted rather than reported as absent — merge spans on an
- * unmerged cell, a spill range on a cell that is not spilled. Value text goes through
- * {@link encodeCell}, so whatever this prints, grep can find.
+ * unmerged cell, a spill range on a cell that is not spilled. Zeros that ARE facts are printed:
+ * a formula nothing reads is an output, and `Dependents (0)` is how the report says it. Value text
+ * goes through {@link encodeCell}, so whatever this prints, grep can find.
  */
-export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): string;
+export declare function renderCell(cell: ICell, options?: AppendDependencyOptions): Promise<string>;
 //# sourceMappingURL=renderCell.d.ts.map

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

@@ -1,6 +1,7 @@
 import { ICellRange } from '@sheetxl/sdk';
 import { CellEncoding } from '../encode';
-import { AppendDependencyOptions, AppendFeatureOptions } from './appendSections';
+import { AppendDependencyOptions } from './appendDependencies';
+import { AppendFeatureOptions } from './appendSections';
 import { ProfileRegionOptions } from './profileRegion';
 /**
  * Options for {@link renderCellRange}.
@@ -57,5 +58,5 @@ export interface RenderCellRangeOptions extends AppendFeatureOptions, AppendDepe
  *
  * Cell text goes through {@link encodeCell}, so whatever a report prints, grep can find.
  */
-export declare function renderCellRange(range: ICellRange, options?: RenderCellRangeOptions): string;
+export declare function renderCellRange(range: ICellRange, options?: RenderCellRangeOptions): Promise<string>;
 //# sourceMappingURL=renderCellRange.d.ts.map

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

@@ -0,0 +1,55 @@
+import { IModule, IModuleCollection, IWorkbook } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+/**
+ * Options for {@link renderModules} and {@link renderModule}.
+ */
+export interface RenderModulesOptions {
+    /** Maximum modules listed before the tail is reported as a count. */
+    maxModules?: number;
+    /** Maximum source lines shown per module in the full listing. */
+    maxSourceLines?: number;
+}
+/**
+ * Every module in the workbook, its own and its sheets', in one list.
+ *
+ * @remarks
+ * Both levels, because "does this workbook contain code" is one question and a reader who has to
+ * ask it per sheet will not ask it at all. Unfiltered by language — the default TypeScript filter
+ * exists to protect callers that only want runnable scripts, and this report exists precisely to
+ * say what is there.
+ */
+export declare function collectModules(workbook: IWorkbook): IModule[];
+/**
+ * Appends the code announcement — what has code, what runs itself, and what SheetXL will not run.
+ *
+ * @remarks
+ * **Names the modules that have source, and only those.** Excel writes an empty `ThisWorkbook`
+ * and an empty document module per sheet whether or not anyone wrote a line in them, so listing
+ * every module reports scaffolding as content — a five-row table for one macro, in which the
+ * reader has to work out which row matters. The heading still counts the whole collection, so
+ * nothing is hidden; the rows are the part worth reading, and `getModules()` reaches the rest.
+ *
+ * Nothing is printed for a workbook with no modules at all. Absence of code is the norm and does
+ * not need a section saying so.
+ */
+export declare function appendModules(md: MarkdownBuilder, modules: readonly IModule[], options?: RenderModulesOptions): void;
+/**
+ * Renders one module — its facts, then its source.
+ *
+ * @remarks
+ * The report that answers "what does this code do", which is why it prints the body rather than
+ * measuring it.
+ */
+export declare function renderModule(module: IModule, options?: RenderModulesOptions): string;
+/**
+ * Renders a module collection — the roster, then each module's source.
+ *
+ * @remarks
+ * **What it holds is decided by where the collection came from**, the same rule
+ * `renderNames` follows: `wb.getScripts().getModules()` is the workbook's own modules,
+ * `sheet.getModules()` is that sheet's. Neither is filtered here — a caller who reached this
+ * report asked to see what exists, so `language` is left wide open rather than defaulting to
+ * TypeScript the way an ordinary `getItems()` does.
+ */
+export declare function renderModules(modules: IModuleCollection, options?: RenderModulesOptions): string;
+//# sourceMappingURL=renderModules.d.ts.map

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

@@ -1,31 +1,87 @@
 import { IMovable } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
+/** A shape with something written on it, the text already read. */
+export interface ShapeTextEntry {
+    movable: IMovable;
+    text: string;
+}
+/** The anchor as a plain A1 address — `toString()` may carry the sheet, and these rows decide that themselves. */
+export declare const describeAnchor: (movable: IMovable) => string;
+/** A shape's text as a listing prints it: quoted, capped, the recovery named where it was cut. */
+export declare const describeShapeText: ({ movable, text }: ShapeTextEntry) => string;
+/** The text written on a shape — `''` for a bare one — or `null` for content that is not a shape. */
+export declare const readShapeText: (movable: IMovable) => string | null;
 /**
- * `## Movables (3)` over `  C3:F12  chart  Chart 1 — column` rows — the pictures, charts, shapes
- * and slicers floating over the report's range.
+ * The shapes among `movables` that have something written on them, in reading order.
+ *
+ * @remarks
+ * **Only non-empty text.** On a shape with an empty body "no text" is itself the information: a
+ * bare rectangle is a box drawn around the cells under it.
+ *
+ * **Reading order, not z-order**: by the anchor's top-left, row-major. Z-order is the order the
+ * author happened to draw them in; callouts are written to be read down the sheet.
+ *
+ * Hidden shapes are included. Hidden text is exactly what a reviewer wants surfaced, and the row
+ * marks it so the reader knows a human looking at the grid does not see it.
+ */
+export declare function collectShapeText(movables: readonly IMovable[]): ShapeTextEntry[];
+/**
+ * One movable as one line of prose: `Picture 1 — logo.png`, or for a chart
+ * `line · 8 series · values NOI!C4:J111 · categories NOI!B4:B111 · Chart 2`.
+ *
+ * @remarks
+ * Name first because it is what the object is called everywhere else — the OOXML `cNvPr/@name`,
+ * the UI's selection pane — and because for a slicer or a shape it is the ONLY description
+ * anything can offer. A chart is the exception and its name goes last: `Chart 2` says nothing, and
+ * what the chart plots is the one fact on the row that points back at cells.
+ *
+ * The alt text joins it when set. It is prose a human wrote about a graphic a text report cannot
+ * show, so here it is not decoration: for a chart or a smart-art frame it is frequently the only
+ * sentence in the whole file that says what the graphic shows.
+ */
+export declare const describeMovableSummary: (movable: IMovable) => string;
+/** `Charts` for `chart` — a type the table does not know still gets a section, named after itself. */
+export declare const describeTypeHeading: (type: string) => string;
+/**
+ * `movables` by content type, in section order: the known types as {@link TYPE_HEADINGS} lists
+ * them, then any other in the order it first appears. Z-order is kept within a type.
+ */
+export declare function groupMovables(movables: readonly IMovable[]): Map<string, IMovable[]>;
+/**
+ * One section per content type — `## Charts (1)`, `## Shapes (11 · 4 with text)` — over the
+ * pictures, charts, shapes and slicers floating over the report's range.
  *
  * @remarks
  * **The one class of sheet content that appears in no other section.** Everything else these
  * reports describe lives in cells and is reachable by address; a movable floats over the grid and
- * is invisible to every values, region and rule listing — so without this section a report about
- * a dashboard sheet says the sheet is nearly empty, which is true of its cells and false of what
+ * is invisible to every values, region and rule listing — so without these a report about a
+ * dashboard sheet says the sheet is nearly empty, which is true of its cells and false of what
  * anyone looking at it sees.
  *
- * Rows are `anchor · type · prose`, and both leading columns are arguments rather than labels: the
- * address is what `getRange()` takes, and the type is exactly what `getMovables({ type })` filters
- * on — the filter compares this same string.
+ * **A section per type, the way tables have one.** A reader looks for charts, or for the notes an
+ * author left; nobody looks for "movables", which is the SDK's word for how these are stored. The
+ * heading is the type, so no row spends a column repeating it.
+ *
+ * Rows are `anchor · preset · prose · "text"`. The anchor is what `getRange()` takes and says which
+ * cells the object is about; the preset says what kind of shape it is — a callout points at
+ * something, a text box stands alone. A chart's type takes the preset's column, and what it plots
+ * is labeled lines beneath its row, the way a table's facts are: a chart states three ranges, and
+ * on one line nothing says which is which.
  *
- * Listed in z-order, which is the order the collection returns them in and the order they paint,
- * so where two movables overlap the later row is the one on top. Hidden movables are listed and
- * marked; they are the ones a reader cannot otherwise learn about.
+ * **What is written on a shape rides its row, and those rows lead** — in reading order, ahead of
+ * the rest in z-order. Text on a shape is almost never decoration: it is a note from the author to
+ * the reader — what a block means, which cell to change, what not to touch — and the heading
+ * counts them so a reader knows to look. Leading also makes the cap safe: what it eats is bare
+ * rectangles. Hidden movables are listed and marked; they are the ones a reader cannot otherwise
+ * learn about.
  */
 export declare function appendMovables(md: MarkdownBuilder, movables: readonly IMovable[]): void;
 /**
- * Renders one movable's report — what it is, where it is anchored, and whether anyone can see it.
+ * Renders one movable's report — what it is, where it is anchored, and whether it is hidden.
  *
  * @remarks
- * The listing carries the identity; this adds what does not fit on a row: the pixel bounds, the
- * anchor behavior that decides what an insert does to this object, and the display note in full.
+ * The listing carries the identity; this adds what does not fit on a row: the pixel bounds and
+ * the anchor behavior that decides what an insert does to this object.
  *
  * **A movable has no name-based lookup**, so unlike a table this report leads with the anchor —
  * the address is how a reader gets back to it (`range.getMovables()`), and the name is the first

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

@@ -24,9 +24,9 @@ export interface RenderNamesOptions extends AppendNamesOptions {
  * the workbook roster), and this is the report that has to be complete: a hidden broken name with
  * dependents is precisely the row a debugging agent must see, and the triage sort surfaces it.
  *
- * Synchronous, like every renderer: the dependents column is read off COMPILED formulas, so the
+ * The dependents column is the engine's answer, and it is read off COMPILED formulas, so the
  * caller settles the engine first — `renderMarkdown` settles its workbook argument before
  * dispatching here.
  */
-export declare function renderNames(names: INamedCollection, options?: RenderNamesOptions): string;
+export declare function renderNames(names: INamedCollection, options?: RenderNamesOptions): Promise<string>;
 //# sourceMappingURL=renderNames.d.ts.map

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

@@ -0,0 +1,81 @@
+import { ICellRange, ICell, IProtectedRange, IProtection, ISheet, ISheetProtection, IWorkbookProtection } from '@sheetxl/sdk';
+import { MarkdownBuilder } from './MarkdownBuilder';
+type AnyProtection = IProtection<any, any, any>;
+/**
+ * `locked · password` / `paused` — or `null` when the object is not protected.
+ *
+ * @remarks
+ * `null` is what every embedding report tests: an unprotected sheet says nothing about protection,
+ * at any altitude. Paused is reported because the document is still a protected one — it saves
+ * protected and `resume()` restores it — even though nothing is refused meanwhile. The password is
+ * only ever a word here; its hash and salt are never printed.
+ */
+export declare const describeLock: (protection: AnyProtection) => string | null;
+/**
+ * `structure locked · password` — the workbook report's `Protection:` line, or `null` when the
+ * workbook is not protected.
+ */
+export declare const describeWorkbookProtection: (protection: IWorkbookProtection) => string | null;
+/**
+ * A protected sheet's line on the workbook report — where it can still be written, and how much.
+ *
+ * @returns `null` when the sheet is not protected.
+ */
+export declare function summarizeSheetProtection(sheet: ISheet): {
+    extent: string;
+    detail: string;
+} | null;
+/**
+ * Appends a sheet report's `Protection` section — nothing at all when the sheet is not protected.
+ *
+ * @remarks
+ * Protection is a **precondition on writing**, the same reason a data validation is reported: a
+ * cell that will refuse the next write looks exactly like one that will accept it. So the section
+ * answers the writer's three questions in order — is it enforced, which operations survive, and
+ * where a value can still go.
+ *
+ * The editable regions are the `unlock` partition, which is why that feature has no section of its
+ * own: on an unprotected sheet an unlocked cell refuses nothing and says nothing, and on a
+ * protected one it is this section's body.
+ */
+export declare function appendSheetProtection(md: MarkdownBuilder, sheet: ISheet): void;
+/**
+ * A range report's `Protection:` line — how much of the range a write reaches — or `null` when the
+ * sheet is not locked.
+ *
+ * @remarks
+ * Locked only, not paused: this line is read immediately before a write, and a paused sheet
+ * refuses none.
+ */
+export declare function describeRangeProtection(range: ICellRange): string | null;
+/** A cell report's `Editable:` fact, or `null` when the sheet is not locked. */
+export declare function describeCellProtection(cell: ICell): string | null;
+/**
+ * The lookup that answers a write refused by protection, or `null` for any other failure.
+ *
+ * @remarks
+ * The refusal itself is written for a person at a dialog ("unprotect the sheet"); a script needs
+ * to know what is still allowed and where. Tested by `name`, since the error routinely crosses a
+ * bundle boundary on its way to the host that reports it.
+ */
+export declare function protectionPointerFor(error: unknown): string | null;
+/**
+ * Renders a sheet's or a workbook's protection — what `getProtection()` answers with.
+ *
+ * @remarks
+ * The object knows its options and not its owner, so this report carries no name and no cells: the
+ * editable regions are the sheet report's `Protection` section, and
+ * `sheet.getRegions("unlock")` on their own. An unprotected object still renders — the caller asked
+ * — as the one line that says so, plus the options it keeps for its next lock.
+ */
+export declare function renderProtection(protection: ISheetProtection | IWorkbookProtection): string;
+/**
+ * Renders one unlocked range — a member of what `sheet.getProtectedRanges()` holds.
+ *
+ * @remarks
+ * Named for what it does rather than for its type: an `IProtectedRange` RELAXES protection, and a
+ * report titled "Protected Range" would tell a writer the opposite of the truth.
+ */
+export declare function renderProtectedRange(item: IProtectedRange): string;
+export {};
+//# sourceMappingURL=renderProtection.d.ts.map

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

@@ -49,6 +49,7 @@ export interface RenderRegionsOptions extends ProfileRegionOptions {
 export declare function appendRegionList(md: MarkdownBuilder, regions: readonly ICellRegion[], options?: RenderRegionsOptions & {
     payload?: RegionPayload;
     profile?: boolean;
+    series?: boolean;
 }): void;
 /**
  * Renders a partition — the unit `getRegions` returns, so an agent addresses structure instead

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

@@ -6,18 +6,17 @@ import { AppendFeatureOptions } from './appendSections';
 export interface RenderSheetOptions extends AppendFeatureOptions {
 }
 /**
- * Renders a markdown report of a sheet: counts, one section per feature partition, and the
- * sheet-level objects (named ranges, hidden headers, tables).
+ * Renders a markdown report of a sheet: counts, one section per feature partition, the sheet-level
+ * objects (named ranges, hidden headers, tables, pivot tables) and the floating layer by type.
  *
  * @remarks
  * **No `Values` section** — that one belongs to {@link renderCellRange}, where the caller named
  * bounds, and it is the only output in these reports that scales with the number of cells.
  *
  * Everything here is bounded by the sheet's structure instead: one section per feature
- * partition, and a profile per contentful block that reports computed shape (types, bounds,
- * aggregates, distinct counts) plus the text that names a block — a 1×1 prints its value, a
- * table its header labels. Blocks × series, both capped, so this report cannot grow with the
- * data. Altitude governs content: this one says where things are and what each block is; the
+ * partition, and one line per contentful block — its shape, its header, and the text that names
+ * it (a 1×1 prints its value). Per-column profiles summarize values, so they are the range
+ * report's. Altitude governs content: this one says where things are and what each block is; the
  * range report reads one.
  *
  * This is the whole-sheet form of the same stats a cell range reports — which is exactly why
@@ -25,5 +24,5 @@ export interface RenderSheetOptions extends AppendFeatureOptions {
  * then asked for, so the two calls compose into the whole read: this one to find the blocks,
  * that one to read one.
  */
-export declare function renderSheet(sheet: ISheet, options?: RenderSheetOptions): string;
+export declare function renderSheet(sheet: ISheet, options?: RenderSheetOptions): Promise<string>;
 //# sourceMappingURL=renderSheet.d.ts.map

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

@@ -1,10 +1,18 @@
 import { ITable } from '@sheetxl/sdk';
 import { MarkdownBuilder } from './MarkdownBuilder';
 /**
- * Appends one table's details — shared by the sheet report's Tables section and the standalone
- * table report, so the two can never describe a table differently.
+ * `## Tables (981 cells · 1 table)` over one `B3:J111  109×9  tblNOI` row per table, its facts
+ * indented beneath it.
+ *
+ * @remarks
+ * **The one section a table has.** A table is both a feature partition and a sheet object, and
+ * printing it as each said the same thing twice under two headings a letter apart. The row is the
+ * partition's — address, size, payload, the form every region listing uses — and the heading
+ * carries its two counts, so nothing the partition said is lost.
+ *
+ * @param cells The cells of `tables` inside the report's scope.
  */
-export declare function appendTableDetails(md: MarkdownBuilder, table: ITable): void;
+export declare function appendTables(md: MarkdownBuilder, tables: readonly ITable[], cells: number): void;
 /**
  * Renders a table report.
  */

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

@@ -1,43 +1,50 @@
 import { IWorkbook } from '@sheetxl/sdk';
-import { AppendFeatureOptions, AppendNamesOptions } from './appendSections';
+import { AppendNamesOptions } from './appendSections';
+import { RenderModulesOptions } from './renderModules';
 /**
  * Options for {@link renderWorkbook}.
  */
-export interface RenderWorkbookOptions extends AppendFeatureOptions, Pick<AppendNamesOptions, 'maxNames'> {
-    /**
-     * Cap on sheets expanded into per-sheet sections below the roster; the rest stay roster-only
-     * and the report says how to render one in full.
-     *
-     * @defaultValue 8
-     */
-    maxSheets?: number;
+export interface RenderWorkbookOptions extends Pick<AppendNamesOptions, 'maxNames'>, Pick<RenderModulesOptions, 'maxModules'> {
 }
 /**
- * Renders a markdown summary of a workbook: identity, the sheet roster, what is broken, and each
- * sheet's structure.
+ * Renders a markdown summary of a workbook: identity, a summary per sheet, what is broken, names
+ * and code.
  *
  * @remarks
  * **The workbook report's job is routing** — *which sheet do I go to, and is anything broken?*
- * Every line earns its place against that, which is why the roster is a table of routing facts
- * (used range, cell/formula/error counts) rather than a list of names, and why errors get a
- * section at this altitude: a broken book must not read clean.
- *
- * **Below the roster, each sheet's own sections render inline** — the same `Type`/partition/
- * object sections a sheet report carries, one heading level down, through the same functions so
- * the two can never disagree. One shape at every size; scale is absorbed by caps, not by a mode
- * switch: on a small book the first call answers structure outright, on a large one every capped
- * list states its overflow and the recovery (`maxSheets` sheets expanded, {@link
- * MAX_REGIONS_PER_SHEET} regions per feature and {@link MAX_PROFILED_PER_SHEET} profiled —
- * tighter than a sheet report's own defaults, because here they share the budget with the whole
- * book). Like the sheet report, the expansion carries no `Values` section — that one is
- * {@link renderCellRange}'s. A contentful profile is computed shape, bounded by blocks × series
- * rather than by cells.
+ * Every line earns its place against that, and a broken book must not read clean.
+ *
+ * **One short summary per sheet, one line per layer.** Content, formulas and styles each have
+ * their own extent, so a single `Used` column could only report the widest of them — a column
+ * style running to XFC made a 33-row model read as sixteen thousand columns. Each layer line
+ * carries its extent and its counts: blocks against cells is the fragmentation signal, formula
+ * regions and distinct formulas say how many ideas the model has, and distinct fonts and formats
+ * say whether the styling is a convention. A layer that is empty has no line. The structure
+ * behind each line is the sheet report's, and the `content` line carries that sheet's call
+ * (`wb.getSheet("Sales") lists the blocks`): a reader routes by copying an address off the roster,
+ * so the call to the fuller report sits on the line the address is read from. **Twins** — sheets
+ * whose formula partitions are identical, where the audit is the diff between them — are named on
+ * the sheet.
+ *
+ * Every sheet is summarized: an agent asked about a sixty-sheet book needs sixty summaries, and
+ * there is no cheaper call that gives them. Labels and extents align across sheets, so reading
+ * down still compares them.
  *
  * Two kinds of broken, kept apart deliberately: an **error** is a successfully calculated error
  * VALUE (`#DIV/0!` from `=1/0` — the `Error` kind), a **calc failure** is the engine failing to
  * evaluate at all (mostly circular references — `CalcError`). A book with zero of one and three
  * of the other is still badly broken, so each gets its own section and neither hides the other.
  *
+ * **Tables, pivot tables and the floating layer each get a line, by type** — `tables`, `charts`,
+ * `shapes` — the same names their sections carry on the sheet's report, so a line here is the
+ * heading to look for there.
+ *
+ * **What the author wrote on a sheet is quoted under it.** Text on a shape is a note to the reader
+ * — what a block means, which cell to change — and this is the report every reader runs first, so
+ * the `shapes` line says how many carry text and the first few follow it, located and
+ * unparaphrased. Under the sheet rather than in a section of the book's: a note is about the sheet
+ * it sits on, and that is where a reader deciding whether to open the sheet will see it.
+ *
  * Sheet ids are a session concept, not a document concept, and are not stable across runs — they
  * do not appear here. Hidden sheets are marked inline where they exist rather than summarized in
  * an always-zero count line: a hidden sheet with data is a classic miss, and the mark is what
@@ -46,5 +53,5 @@ export interface RenderWorkbookOptions extends AppendFeatureOptions, Pick<Append
  * Pure rendering — the agent-priming preamble the pre-migration SDK report carried
  * (`PROMPT_STRING`) belongs to the host that primes the agent, not to the report.
  */
-export declare function renderWorkbook(workbook: IWorkbook, options?: RenderWorkbookOptions): string;
+export declare function renderWorkbook(workbook: IWorkbook, options?: RenderWorkbookOptions): Promise<string>;
 //# sourceMappingURL=renderWorkbook.d.ts.map