@sheetxl/query 0.7.23-beta.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sheetxl/query",
+  "description": "SheetXL - Workbook read surface and renderers (grep, reports) — capabilities declared once, adapted by any host surface",
+  "version": "0.7.23-beta.1",
+  "license": "SEE LICENSE IN <LICENSE>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "browser": "./browser/esm/index.mjs",
+      "node": "./node/esm/index.mjs",
+      "import": "./browser/esm/index.mjs",
+      "require": "./browser/cjs/index.cjs"
+    }
+  },
+  "types": "./types/index.d.ts",
+  "module": "./browser/esm/index.mjs",
+  "main": "./browser/cjs/index.cjs",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20 <21 || >=22"
+  },
+  "engineStrict": true,
+  "homepage": "https://sheetxl.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheetxl/sheetxl.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sheetxl/sheetxl/issues"
+  },
+  "keywords": [
+    "sheetxl",
+    "spreadsheet",
+    "javascript",
+    "typescript",
+    "excel",
+    "xlsx",
+    "agent",
+    "ai",
+    "mcp",
+    "grep",
+    "query"
+  ],
+  "dependencies": {
+    "@sheetxl/primitives": "^0.7.23-beta.1",
+    "@sheetxl/sdk": "^0.7.23-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/index'
+export {}

package/types/src/Tool.d.ts

@@ -0,0 +1,108 @@
+import { IWorkbook } from '@sheetxl/sdk';
+/**
+ * The read surface is defined once, here, and adapted mechanically by each host surface —
+ * no surface hand-writes a second copy of a capability.
+ *
+ * @remarks
+ * All text on a descriptor is **agent-facing and English**. It is read by a model, not by a
+ * person, so it is deliberately not routed through `t()`. Localized chrome (help headings,
+ * error framing) belongs to the surface that wraps this.
+ */
+export declare namespace Tool {
+    /**
+     * The value kinds a parameter may take.
+     *
+     * @remarks
+     * Deliberately small. Every kind maps cleanly onto both a command-line option and a JSON
+     * Schema property; anything that does not is a sign the parameter wants to be its own tool.
+     */
+    type ParamType = 'string' | 'number' | 'boolean' | 'enum' | 'enum[]';
+    /**
+     * One argument of a tool, in the canonical (camelCase) form.
+     *
+     * @remarks
+     * Surfaces rename mechanically and never by hand: a flag surface kebab-cases (`ignoreCase`
+     * → `--ignore-case`), a schema surface passes the name through. A surface that needs a
+     * *different* name is declaring a divergence, and there is nowhere to put one.
+     */
+    interface Param {
+        /** Canonical camelCase name. */
+        readonly name: string;
+        readonly type: ParamType;
+        /** One line, agent-facing, English. */
+        readonly description: string;
+        readonly required?: boolean;
+        /**
+         * Applied by the tool, not by the adapter.
+         *
+         * @remarks
+         * Adapters must not inject defaults — if two surfaces default differently the capability has
+         * silently diverged, which is the whole failure this package exists to prevent.
+         */
+        readonly defaultValue?: unknown;
+        /** Allowed values for `enum` / `enum[]`. */
+        readonly values?: readonly string[];
+        /**
+         * The flag's value may be omitted (`--context` vs `--context table`).
+         *
+         * @remarks
+         * The bare form reaches the tool as `true`, and the tool — never the adapter — decides
+         * what `true` means, for the same reason adapters must not inject defaults. On a schema
+         * surface this is the union of `boolean` and the enum.
+         */
+        readonly valueOptional?: boolean;
+        /**
+         * Terminal affordance: register as a positional argument at this index rather than a flag.
+         *
+         * @remarks
+         * Schema surfaces ignore this — their arguments are all named. Positional order is a
+         * terminal convenience, not part of the capability.
+         */
+        readonly positional?: number;
+        /** Terminal affordance: single-character alias (`-i`). */
+        readonly alias?: string;
+    }
+    /**
+     * A read capability, plus its default rendering.
+     *
+     * @remarks
+     * `run` returns typed data and `render` turns it into the agent-facing text form. They are
+     * separate so a consumer that wants the data (a macro's caller, a UI, a test) is never forced
+     * through the string.
+     */
+    interface Descriptor<A = any, R = any> {
+        /** Tool name and subcommand — the same word on every surface. */
+        readonly name: string;
+        /** One or two lines, agent-facing, English. */
+        readonly description: string;
+        /**
+         * The SDK expression this tool wraps, e.g. `sheet.getRange(scope).find(pattern, {...})`.
+         *
+         * @remarks
+         * Rendered into every surface's description as one `SDK: …` line — the graduation path
+         * from tool call to macro. Generated from here so the mapping cannot drift from the tool
+         * it describes; it also makes tool↔SDK name divergence harmless where realigning an
+         * existing SDK method is cheaper than renaming it.
+         */
+        readonly sdk?: string;
+        readonly params: readonly Param[];
+        /**
+         * Execute against a live workbook.
+         *
+         * @remarks
+         * Takes an `IWorkbook`, never a path. A stateful host may hold a workbook with unsaved
+         * edits and no file behind it; a path-shaped entry point would either exclude it or make
+         * it read stale data. Loading is the caller's job.
+         */
+        run(workbook: IWorkbook, args: A): Promise<R>;
+        /**
+         * The default agent-facing rendering of a result.
+         *
+         * @remarks
+         * May be async — report renderers settle calculation before reading. Adapters `await` the
+         * result; a sync renderer (grep) is unaffected.
+         */
+        render(result: R): string | Promise<string>;
+    }
+}
+//# sourceMappingURL=Tool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../../src/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;GAQG;AACH,yBAAiB,IAAI,CAAC;IACpB;;;;;;OAMG;IACH,KAAY,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IAE5E;;;;;;;OAOG;IACH,UAAiB,KAAK;QACpB,gCAAgC;QAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QACzB,uCAAuC;QACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B;;;;;;WAMG;QACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAChC,4CAA4C;QAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACpC;;;;;;;WAOG;QACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;QACjC;;;;;;WAMG;QACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,0DAA0D;QAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB;IAED;;;;;;;OAOG;IACH,UAAiB,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG;QAC1C,iEAAiE;QACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,+CAA+C;QAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B;;;;;;;;WAQG;QACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;QAClC;;;;;;;WAOG;QACH,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC9C;;;;;;WAMG;QACH,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;KAC7C;CACF"}

package/types/src/encode/encodeCell.d.ts

@@ -0,0 +1,149 @@
+import { ICell, Scalar } from '@sheetxl/sdk';
+/**
+ * The agent-facing value encoding.
+ *
+ * @remarks
+ * This is a **presentation contract, not an engine concern** — the SDK is code and has no need
+ * of it. Number formatting (turning `0.04` into `4%`) is legitimately the engine's job because
+ * the grid renders it; the encoding *on top* — the `'` prefix, `TRUE`/`FALSE`, error literals,
+ * blank elision — exists so a model reading a flat listing can infer types without a type
+ * column. That belongs here, above the SDK, beside the renderers that depend on it.
+ *
+ * Every read surface shares this module. `query_values`, `describe` and the markdown migration
+ * encode through it too, which is the property that makes {@link CellEncoding.Display | display}
+ * greppable: whatever text a read printed, grep can find, because one encoder produced both.
+ *
+ * ---
+ *
+ * **Quarantine note.** `ICell.getText()` is the only SDK call this module makes, and it is on its
+ * way out — its contract fuses formatting, localization, csv escaping and this encoding into one
+ * method with no clear answer for large values. It is isolated to this file deliberately: when
+ * the SDK splits pure number formatting away from the encoding, exactly one file changes and no
+ * renderer notices.
+ */
+export declare namespace CellEncoding {
+    /**
+     * How much formatting to apply before encoding.
+     */
+    const Mode: {
+        /**
+         * The cell as displayed — number format applied.
+         *
+         * @remarks
+         * `4%`, `2024-01-01`, `$1,234.57`. What a human reading the grid sees, and what a values
+         * read prints.
+         */
+        readonly Display: "display";
+        /**
+         * The cell as the formula bar shows it — full precision, number formatting stripped.
+         *
+         * @remarks
+         * `1234.5678` where {@link Mode.Display | display} shows `$1,234.57`. Dates stay dates
+         * rather than decaying to serials, so the result is still searchable rather than merely
+         * lossless.
+         */
+        readonly Value: "value";
+    };
+    type Mode = typeof Mode[keyof typeof Mode];
+    /**
+     * A cell's text in the two forms a read surface needs.
+     *
+     * @remarks
+     * They differ only for strings, and only by the `'` prefix — but that one difference is why
+     * anchored patterns work while a rendered result still tells a string from a number.
+     */
+    interface Encoded {
+        /**
+         * Undecorated — what a pattern is tested against.
+         *
+         * @remarks
+         * The prefix is an *output* device, serving type inference by a reader. A pattern is input.
+         * Carrying the prefix into matching would make `^Acme` silently fail and `^42$` match the
+         * number but not the string — inconsistencies an agent has no way to diagnose.
+         */
+        match: string;
+        /**
+         * Encoded — what a result reports.
+         *
+         * @remarks
+         * Strings carry the leading `'`; numbers, booleans and errors do not. That asymmetry *is*
+         * the type inference.
+         */
+        display: string;
+    }
+}
+/**
+ * Encodes a bare number the way a spreadsheet displays one.
+ *
+ * @remarks
+ * **A display contract, not formatting.** Where a cell has a number format, that format decides
+ * the text and this never runs. Where there is none — a raw {@link Scalar}, a computed
+ * aggregate, anything off the value layer — something still has to choose how many digits to
+ * print, and JavaScript's default choice is the wrong one: `String(2398.7999999999997)` spends
+ * 17 digits publishing the binary residue of `0.1 + 0.2`-class arithmetic. The float is
+ * *correct*; the rendering is unusable, because an agent comparing it against an expected
+ * `2398.8` sees a mismatch that is not there.
+ *
+ * Excel caps display at **15 significant digits** for exactly this reason, and the cap is the
+ * whole rule — it is not rounding for readability, it is the point past which the extra digits
+ * describe IEEE-754 rather than the value. Rounding to 15 and re-stringifying lets JavaScript
+ * pick the shortest form that survives the round trip, so `2398.8` prints as `2398.8` and a
+ * genuinely long number keeps every digit it has earned.
+ *
+ * Non-finite values pass through: `NaN` and `Infinity` are not precision questions, and
+ * `toPrecision` would only hand back their own string anyway.
+ *
+ * The exponent is respelled Excel's way for the same reason the digits are capped Excel's way —
+ * see {@link excelExponent}.
+ */
+export declare function encodeNumber(value: number): string;
+/**
+ * Encodes a number that came off a range carrying a number format — an aggregate, a bound, a
+ * value with no cell of its own to ask.
+ *
+ * @remarks
+ * **This is what stops a date column from reporting itself as an ID column.** A profile that
+ * prints `45293 … 46234` for a date series is not merely ugly: it is the wrong *type*, and a
+ * reader acts on it. The same rule fixes currency (`$1.20`) and percent (`42.37%`) for free,
+ * because there is only one rule — a range's own format decides how its numbers print, exactly
+ * as {@link CellEncoding.Mode.Display} decides it for a cell.
+ *
+ * `General` (or no format) falls through to {@link encodeNumber}, which is the correct answer
+ * for a derived value: a mean carries no format of its own, and Excel's 15-digit display cap is
+ * the only thing standing between the reader and the float's binary residue.
+ *
+ * It goes through the SDK's own {@link NumberFormat.getEngine | format engine} rather than a
+ * format library directly, and that is not incidental: a range's format is frequently a **named**
+ * preset (`Short Date`, `[$-F800]`) whose expansion is locale-dependent, and a raw pattern
+ * formatter renders `Short Date` as literal characters — `00ort 1at2024` where the grid shows
+ * `1/1/2024`. The engine is the only thing that knows the workbook's answer.
+ *
+ * The result is trimmed: alignment formats pad with `_)` and a trailing space is a cell-width
+ * device with no meaning inside a sentence. A format the engine cannot render degrades to the
+ * unformatted number — a report must not fail because one column has a broken format string.
+ */
+export declare function encodeFormattedNumber(value: number, numberFormat?: string | null): string;
+/**
+ * Encodes one cell for agent consumption.
+ *
+ * @returns `null` for a blank cell — blanks are elided by every read surface rather than
+ * rendered as empty, so there is nothing to encode.
+ */
+export declare function encodeCell(cell: ICell, mode: CellEncoding.Mode): CellEncoding.Encoded | null;
+/**
+ * Encodes one bare {@link Scalar} — a value with no cell behind it.
+ *
+ * @remarks
+ * The counterpart to {@link encodeCell} for the stateless value layer (`IRange`, `Scalar[][]`),
+ * where there is no cell to ask for text and therefore **no number format to apply**. That is
+ * the whole difference: `0.04` encodes as `0.04` here and as `4%` through a cell that formats
+ * it. There is consequently no `mode` — the two modes differ only by how much formatting they
+ * apply, and here there is none to strip.
+ *
+ * Everything above formatting is identical, because it is the same contract: the `'` prefix on
+ * strings, `TRUE`/`FALSE`, error labels, blank elision.
+ *
+ * @returns `null` for a blank value, matching {@link encodeCell}.
+ */
+export declare function encodeScalar(value: Scalar): CellEncoding.Encoded | null;
+//# sourceMappingURL=encodeCell.d.ts.map

package/types/src/encode/encodeCell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encodeCell.d.ts","sourceRoot":"","sources":["../../../../src/encode/encodeCell.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,KAAK,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yBAAiB,YAAY,CAAC;IAC5B;;OAEG;IACI,MAAM,IAAI;QACf;;;;;;WAMG;;QAEH;;;;;;;WAOG;;KAEK,CAAC;IACX,KAAY,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;IAElD;;;;;;OAMG;IACH,UAAiB,OAAO;QACtB;;;;;;;WAOG;QACH,KAAK,EAAE,MAAM,CAAC;QACd;;;;;;WAMG;QACH,OAAO,EAAE,MAAM,CAAC;KACjB;CACF;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlD;AAyBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASzF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,GAAG,YAAY,CAAC,OAAO,GAAG,IAAI,CAK5F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,OAAO,GAAG,IAAI,CAkBvE"}

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

@@ -0,0 +1,2 @@
+export * from './encodeCell';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/encode/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}

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

@@ -0,0 +1,308 @@
+/**
+ * The cell layers `grep` can match against.
+ *
+ * @remarks
+ * These are *not* `ICell.Content`. That enum also carries `formats`, `tables`, `merges` and
+ * `warnings`, which have no text to match — selection by attribute is the regions read, not grep.
+ *
+ * The rule, which predicts any future member:
+ * **a grep field is a layer whose text was authored by a person or is read by one.**
+ *
+ * `display`, `value` and `raw` are read; `formula`, `hyperlink` and `numberFormat` are authored.
+ * A layer that fails the rule fails it because its payload has no canonical text — a fill's
+ * "red" may be stored as `FF0000`, a theme slot, or an indexed palette entry, so any pattern
+ * against it silently matches less than it claims: a confident wrong answer, which is worse
+ * than a missing feature. Color wants *nearness*, not matching — that is selection by
+ * attribute, and it belongs to the regions read.
+ *
+ * Two layers are deliberately absent for the same reason:
+ * - `note` — `ICell.Content.Notes` is marked NOT IMPLEMENTED.
+ * - `comment` — `IComment.Properties.content` is `any` pending `IRichText.JSON`, so any text
+ *   extractor written against it today would quietly miss the shapes it did not anticipate.
+ *
+ * Both are additive once the SDK shapes settle.
+ */
+export type GrepField = 
+/**
+ * The cell as displayed — number format applied.
+ *
+ * `4%`, `2024-01-01`, `$1,234.57`, `TRUE`, `#N/A`, `hello`.
+ *
+ * Not named `text`: that reads as "cells containing text", and there is no longer an SDK
+ * method of that name to be consistent with. `display` and {@link GrepField | value} name what
+ * they are and pair without explanation.
+ *
+ * Runs through the shared encoder, which is the point: whatever text a values read printed,
+ * grep finds, because one encoder produced both. A second display path would fail on exactly
+ * the strings an agent copied out of the previous tool call.
+ */
+'display'
+/**
+ * The cell as the formula bar shows it — most formatting stripped, **category kept**.
+ *
+ * `1234.5678` where {@link GrepField | display} shows `$1,234.57` — but `40%` stays `40%`
+ * and dates stay dates, because the formula bar keeps minimal formatting for percents,
+ * dates and times (Excel's behavior, faithfully). This is *not* the underlying scalar:
+ * a percent cell storing `0.4` reads `40%` here. The stored scalar is
+ * {@link GrepField | raw}.
+ *
+ * Identical to `display` for every cell whose format only decorates (`General`, plain
+ * text) — the default search dedupes that case per cell rather than reporting both.
+ */
+ | 'value'
+/**
+ * The stored scalar, encoded bare — what the stateless value layer prints.
+ *
+ * `0.4` where {@link GrepField | value} shows `40%`; dates as serial numbers. This is the
+ * layer `IRange` / stats reads print (they have no cell to format through), so it is the
+ * field that makes *those* printed values greppable — the round-trip that `display`
+ * provides for formatted reads. Not a default: serials and unrounded floats are noise
+ * until they are the question.
+ */
+ | 'raw'
+/** Formula text, A1 style (`=SUM(A1:A10)`). Cells without a formula contribute nothing. */
+ | 'formula'
+/** Hyperlink target — the address, not the display text (which is already `display`). */
+ | 'hyperlink'
+/**
+ * The number format code — `0.00%`, `$#,##0.00`, `mm/dd/yyyy`.
+ *
+ * Authored text (it is literally what was typed into Format Cells), canonical, and regex
+ * is its native matcher. `--fields numberFormat "%"` is the well-posed form of "which
+ * cells are percentages" — the rendered `40%` is not. Matches cells with a *direct*
+ * format, including value-less ones (a formatted-but-empty column is a real finding).
+ */
+ | 'numberFormat';
+export declare const GrepField: {
+    readonly Display: "display";
+    readonly Value: "value";
+    readonly Raw: "raw";
+    readonly Formula: "formula";
+    readonly Hyperlink: "hyperlink";
+    readonly NumberFormat: "numberFormat";
+};
+/** Every field, in the order they are searched and reported. */
+export declare const GREP_FIELDS: readonly GrepField[];
+/**
+ * The default field set.
+ *
+ * @remarks
+ * What you can see, what the formula bar shows, and what is structurally behind both.
+ * `value` is a default *because* the search dedupes it: for the majority of cells it is
+ * byte-identical to `display` and is suppressed per cell, so it only surfaces where it
+ * carries new information — `1234.5678` behind `$1,234.57`. A duplicate hit costs an agent
+ * a second look for no new information; a missing layer costs a silent zero-hit miss on
+ * full-precision searches, which is worse.
+ */
+export declare const GREP_FIELDS_DEFAULT: readonly GrepField[];
+/** What a grep result should carry. */
+export type GrepOutput = 
+/** Address, field and the matched text. */
+'content'
+/** Addresses only, one per matched cell. */
+ | 'addresses'
+/** Counts only, reported per sheet — `rg -c`. */
+ | 'count'
+/** Names of sheets with at least one match — `rg -l`. */
+ | 'sheets';
+/**
+ * How {@link GrepArgs.context} resolves the block a match sits in.
+ */
+export type GrepContext = 
+/**
+ * The uniform contentful block containing the match (Excel `CurrentRegion` semantics).
+ * When that block sits inside a table, the table's name is carried too — the name is the
+ * better answer and costs one lookup.
+ */
+'contentful'
+/** The enclosing *table* only. Matches outside any table carry no context. */
+ | 'table';
+/**
+ * Arguments to {@link grep}.
+ *
+ * @remarks
+ * Shaped after ripgrep rather than after anything novel — args, defaults and vocabulary are
+ * already pretrained, and every novel idiom is paid for in error loops.
+ */
+export interface GrepArgs {
+    /**
+     * The pattern to search for — a regular expression, as in every grep.
+     *
+     * @remarks
+     * Full JS `RegExp` semantics (lookaround and backreferences work — more than rg's default
+     * engine). Literal search is {@link GrepArgs.fixedStrings}.
+     */
+    pattern: string;
+    /**
+     * Which cell layers to search.
+     *
+     * @defaultValue {@link GREP_FIELDS_DEFAULT} — `['display', 'value', 'formula']`
+     */
+    fields?: readonly GrepField[];
+    /**
+     * Treat `pattern` as a literal string — `rg -F`.
+     *
+     * @defaultValue false — **the pattern is a regex by default**, because that is what the name
+     * `grep` means everywhere an agent learned it (POSIX grep and rg both default to regex). A
+     * wildcard default was tried and rejected: agents type `\d+` by reflex, wildcards literalize
+     * it, and the result is a silent zero-hit miss. Excel's `?`/`*` wildcards live in the UI find
+     * dialog, where Excel users live.
+     */
+    fixedStrings?: boolean;
+    /**
+     * Case-insensitive matching.
+     *
+     * @defaultValue false — case-sensitive, as `rg` is. Note this inverts the SDK's `matchCase`.
+     */
+    ignoreCase?: boolean;
+    /**
+     * Require the match to fall on word boundaries.
+     *
+     * @remarks
+     * Boundaries are grep's, not `\b`'s: a pattern that starts or ends on a non-word character
+     * (`$1,234`, `4%`, `#N/A` — spreadsheet text is full of them) still matches at text edges,
+     * exactly as `rg -w` treats line edges. Implemented as `(?<!\w)…(?!\w)`, which coincides
+     * with `\b` for word-bounded patterns and stays correct for the rest.
+     */
+    word?: boolean;
+    /**
+     * Invert the match — report cells where **no** requested field matched (`rg -v`).
+     *
+     * @remarks
+     * Scoped to cells grep visits: a cell must have text in at least one requested field to be
+     * reported (an empty cell is not a finding, and "every blank cell" is not an answer).
+     * Reported rows carry the first requested field that has text, as the evidence line.
+     */
+    invert?: boolean;
+    /**
+     * Where to search: a sheet name (globs allowed — `Q*`), a sheet-qualified range
+     * (`Sheet1!A1:D9`), or a bare range applied to **every** sheet.
+     *
+     * @defaultValue every sheet's used range.
+     *
+     * @remarks
+     * Resolution order is fixed and documented rather than sniffed: a `!` splits sheet from
+     * range; otherwise an exact sheet-name match wins; otherwise a glob (`*`/`?`) matches sheet
+     * names; otherwise it is a range on **every sheet**. A bare range cannot resolve against an
+     * "active sheet" — a stateless invocation has none, and inventing one would make the same
+     * command mean different things in different surfaces.
+     *
+     * Naming a hidden sheet (exactly or via a glob-free match) searches it — an explicit name
+     * is an explicit request, the same way `rg` searches a hidden file you name.
+     */
+    scope?: string;
+    /**
+     * Search hidden rows, columns and hidden sheets — `rg --hidden`.
+     *
+     * @defaultValue false — hidden content is **excluded**, the `.gitignore` analogy: the user
+     * has already declared they are not looking at these. Exclusion is structural (hidden rows
+     * are never visited), never silent — the header's scope line reflects what was searched.
+     */
+    hidden?: boolean;
+    /**
+     * Stop after this many matching cells. Truncation is always reported, never silent.
+     *
+     * @defaultValue 200 — a grep result returns into a context window, not a terminal stream,
+     * so unbounded output is a cost the caller did not ask for. `0` removes the cap.
+     *
+     * @remarks
+     * Counts **cells**, not match rows — a cell matching in two fields is one unit of budget.
+     * The search looks one cell past the cap, so a result that ends exactly at `maxCount` is
+     * only reported truncated when a further match actually exists.
+     */
+    maxCount?: number;
+    /**
+     * Annotate each match with the block it sits in, and group the listing by block — the 2-D
+     * answer to `rg -C`.
+     *
+     * @remarks
+     * ±N lines is meaningless in a grid; the question context answers is "what is this thing
+     * part of?", and the honest unit for that is the uniform region containing the match — see
+     * {@link GrepContext}. `true` means `'contentful'`. A numeric value is rejected rather than
+     * reinterpreted: `-C 3` means something else in every other grep, and accepting it while
+     * meaning "enclosing block" would be a silent divergence.
+     */
+    context?: boolean | GrepContext;
+    /**
+     * @defaultValue 'content'
+     */
+    output?: GrepOutput;
+}
+/** The block a match sits in — present when {@link GrepArgs.context} was requested. */
+export interface GrepMatchContext {
+    /** Sheet-qualified address of the enclosing block, e.g. `Sales!A1:D9`. */
+    range: string;
+    /** The enclosing table's name, when the match is inside one. */
+    table?: string;
+}
+/**
+ * One match. **Grep's unit is the cell** — one entry per matched `(cell, field)`, in reading
+ * order.
+ *
+ * @remarks
+ * Deliberately not coalesced into blocks: uniform runs of identical values are *regions* — a
+ * payload feature splits where the value changes, so the regions read already owns that shape,
+ * in 2-D and with the full partition to rank against. Grep answering cell-grain and regions
+ * answering block-grain is the family split (§6.1). {@link GrepArgs.context} does not move
+ * that line: the unit stays the cell; the region is carried as an annotation on it, and the
+ * renderer merely groups by it.
+ */
+export interface GrepMatch {
+    /** Sheet name. */
+    sheet: string;
+    /** A1 cell address within the sheet. */
+    address: string;
+    /**
+     * Which layer matched.
+     *
+     * @remarks
+     * Load-bearing, not decoration. Searching several fields at once, a bare address is unusable —
+     * the agent cannot tell whether `2024` matched a date's display, a formula referencing row
+     * 2024, or a hyperlink. `rg` prints the matching line; this is the analog.
+     */
+    field: GrepField;
+    /** The full text of the matched layer. */
+    text: string;
+    /** The enclosing block, when {@link GrepArgs.context} was requested and one exists. */
+    context?: GrepMatchContext;
+}
+/** Per-sheet match accounting — the unit `rg -c` and `rg -l` report at. */
+export interface GrepSheetMatches {
+    /** Sheet name. */
+    sheet: string;
+    /** Distinct cells that produced at least one match in this sheet. */
+    cells: number;
+}
+/** The result of a {@link grep}. */
+export interface GrepResult {
+    /** Echoed back so a rendering carries its own scope. */
+    pattern: string;
+    fields: readonly GrepField[];
+    /** Resolved human-readable scope, e.g. `Sheet1!A1:D847` or `workbook`. */
+    scope: string;
+    matches: readonly GrepMatch[];
+    /** Distinct cells that produced at least one match. */
+    cellCount: number;
+    /** Per-sheet counts, in search order — only sheets with at least one match appear. */
+    sheets: readonly GrepSheetMatches[];
+    /**
+     * Sheets that were actually entered by the search.
+     *
+     * @remarks
+     * When {@link GrepArgs.maxCount} cuts the search short, sheets never entered are not
+     * counted — "searched" is a claim, and it is only made about work that happened.
+     */
+    sheetsSearched: number;
+    /** Sheets that produced at least one match. */
+    sheetsMatched: number;
+    /**
+     * True when {@link GrepArgs.maxCount} cut the search short — a further matching cell was
+     * actually found past the cap, never inferred from the count alone.
+     *
+     * @remarks
+     * Elision is explicit and never silent, so the renderer must surface this.
+     */
+    truncated: boolean;
+    output: GrepOutput;
+}
+//# sourceMappingURL=GrepTypes.d.ts.map

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

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

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

@@ -0,0 +1,15 @@
+import { IWorkbook } from '@sheetxl/sdk';
+import { GrepArgs, GrepResult } from './GrepTypes';
+/**
+ * Searches a workbook's cell contents by pattern.
+ *
+ * @remarks
+ * Deliberately shaped after ripgrep — args, defaults and vocabulary are pretrained, and every
+ * novel idiom is paid for in error loops.
+ *
+ * Hidden rows, columns and sheets are excluded by default (the `.gitignore` analogy — the user
+ * has already declared they are not looking at these); `hidden` includes them, and naming a
+ * hidden sheet in `scope` searches it.
+ */
+export declare function grep(workbook: IWorkbook, args: GrepArgs): Promise<GrepResult>;
+//# sourceMappingURL=grep.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"grep.d.ts","sourceRoot":"","sources":["../../../../src/grep/grep.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA6C,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzF,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AA+PrB;;;;;;;;;;GAUG;AACH,wBAAsB,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CA+GnF"}