@clossys/writer 0.3.2

package/dist/scan.d.ts

@@ -0,0 +1,457 @@
+/**
+ * `scanCopySourceTree` and `extractCopyCandidates` — the I/O half AND the
+ * hard-analysis half of this gate, unlike the split `@clossys/
+ * strategy` draws between its own `scan.ts` (dumb directory walk) and
+ * `facts-gate.ts` (the matchers). Here the walk is the easy part; finding
+ * which string literals in a real source file are actually user-facing
+ * copy — as opposed to a class name, an import specifier, an object key, a
+ * `data-*`/`aria-*` attribute, an enum token, or a message meant for a
+ * developer, not a user — is the genuinely hard problem, and it is a
+ * problem about SOURCE TEXT, not about a file tree. So it lives here, next
+ * to the walk that feeds it, and `copy-gate.ts` is left with the simpler
+ * job: compare what this file found against a `CopyRecord` and report.
+ *
+ * NO PARSER LIBRARY — this repository's zero-runtime-dependency default for
+ * every package here, `@example/ui` (which wraps React) being the
+ * one deliberate exception. What follows is a small hand-rolled character
+ * scanner
+ * that finds string/template literal BOUNDARIES correctly (the part that
+ * is genuinely hard to get wrong-free with a regex: escaped quotes, nested
+ * template interpolation, comments, and regex literals all look enough
+ * like strings to confuse a naive `"[^"]*"` pattern), plus a set of
+ * narrow, LOCAL, documented heuristics — never a full grammar — that look
+ * at the raw text immediately around a literal to decide whether it is a
+ * user-facing string. Every one of those heuristics is a real, stated
+ * trade-off, not a black box: see "THE BOUNDARY" below for the full
+ * reasoning, calibrated against real code in this same repository
+ * (`packages/ui/src/blocks/Pagination.tsx`, `packages/ui/src/atoms/
+ * Select.tsx`, `packages/ui/src/atoms/Table.tsx` — see each package's own
+ * test fixtures, lifted near-verbatim from those three files).
+ *
+ * ============================================================================
+ * THE BOUNDARY — what counts as a "copy candidate", and why
+ * ============================================================================
+ *
+ * DEFAULT IS INCLUDE. A bare string or template literal used as a VALUE
+ * (never a key, a specifier, or a type) is a copy candidate unless one of
+ * the exclusions below applies. This is deliberate, not an oversight: this
+ * package's own calibration example — `rangeSummary = "No results"` in
+ * `Pagination.tsx` — is a plain literal assignment with NO special
+ * surrounding syntax at all (no JSX attribute, no call argument, nothing
+ * to allowlist against). A scanner that only fires inside a hand-picked
+ * allowlist of "known copy positions" would silently miss exactly this
+ * case, which is the single most common shape real UI copy actually takes
+ * in this codebase. So the default has to be permissive, and the real work
+ * is in a precise, narrow EXCLUDE list:
+ *
+ *   1. Import/export/require specifiers (`from "x"`, `import("x")`,
+ *      `require("x")`) — a module path is an address, not copy.
+ *   2. Object-literal / destructuring keys (`{ "some-key": value }`) —
+ *      recognized as: the literal is immediately followed by `:`, AND its
+ *      immediately preceding non-whitespace character is `{` or `,` (an
+ *      object-literal position), AND that preceding character is NOT `?`
+ *      (a ternary's `cond ? "a" : "b"` also has a literal immediately
+ *      followed by `:`-shaped text further along, but the literal
+ *      immediately BEFORE a ternary's `:` is preceded by `?`, never `{`/
+ *      `,` — this distinction is exactly what keeps
+ *      `totalItems === 0 ? "No results" : ...` — a real line from
+ *      `Pagination.tsx` — correctly classified as copy, not a key).
+ *   3. Values inside a `type` alias or `interface` body — TypeScript's own
+ *      type language, never a runtime string a user sees.
+ *   4. `aria-*` and `data-*` attribute/prop VALUES, in both JSX
+ *      (`aria-label="Previous page"`) and camelCase-identifier form
+ *      (`` "aria-label": ariaLabel = "Select all rows" ``, the exact shape
+ *      `Table.tsx`'s `TableSelectAllCheckbox` uses). Stated explicitly,
+ *      because it is the one exclusion most worth arguing with: an
+ *      `aria-label` genuinely is read aloud to a screen-reader user, so it
+ *      IS user-facing in the most literal sense. It is excluded anyway,
+ *      for a scope reason, not a "doesn't matter" reason: this repository
+ *      leans heavily on icon-only controls (`Pagination`'s prev/next
+ *      buttons, `Table`'s row-selection checkboxes), each of which carries
+ *      an `aria-label` as its ONLY accessible name. Registering those
+ *      alongside visible copy would roughly double this gate's candidate
+ *      volume on `packages/ui` alone, for a category (accessibility
+ *      labels) that has a different owner, a different review cadence, and
+ *      arguably needs a different check shape (e.g. "every icon-only
+ *      control has SOME aria-label" is a presence check, not a
+ *      traceability-to-copy check). Wiring accessibility labels into this
+ *      gate is real, valid future scope — deliberately not this package's
+ *      v1, the same way the icon-atom migration was deliberately excluded
+ *      from its own PR. A denylisted attribute value is counted and
+ *      reported (see `ExcludedLiteral`), never silently dropped.
+ *   5. A fixed denylist of attribute/prop names that are structural, not
+ *      textual, even though their values are strings: `className`, `class`,
+ *      `id`, `key`, `htmlFor`, `role`, `type`, `rel`, `target`, `method`,
+ *      `encType`, `autoComplete`, `inputMode`, `pattern`, `name`, `slot`,
+ *      `variant`, `size`, `as`, `href`, `src`, `xmlns`, `viewBox`, `fill`,
+ *      `stroke`, `d`, `strokeWidth`, `strokeLinecap`, `strokeLinejoin`,
+ *      `testId`, `data-testid`. `className` is the canonical example this
+ *      package's design brief calls out: a Tailwind utility string is not
+ *      copy at all, in any sense.
+ *   6. The literal-string argument list of a class-name BUILDER call —
+ *      `cx(...)` (this repository's own helper, see
+ *      `packages/ui/src/atoms/internal/cx.ts`), `clsx(...)`,
+ *      `classNames(...)` — even a literal that ISN'T itself passed through
+ *      a `className` prop can still be pure CSS-class text if it's an
+ *      argument to one of these. Detected via a bounded backward paren-
+ *      balance scan to find the nearest enclosing call's identifier — see
+ *      `enclosingCallName`.
+ *   7. The literal-string argument of a call this package treats as a
+ *      developer diagnostic, not user copy: `console.log/warn/error/
+ *      debug/info(...)`, `throw new Error(...)`, `assert(...)`,
+ *      `invariant(...)`. The task brief's own words: "error messages meant
+ *      for developers... look identical to a naive scanner" to real copy;
+ *      this is the targeted fix for that specific confusion.
+ *   8. Literals with no letters after trimming (`"…"`, `"‹"`, `"▾"`, a bare
+ *      number or punctuation glyph) — decorative or symbolic, not
+ *      language-bearing text a translator or copy reviewer would ever act
+ *      on. `Pagination.tsx`'s `‹`/`›` ellipsis glyphs are exactly this
+ *      case.
+ *   9. A single lowercase "token" — no whitespace, matches
+ *      `/^[a-z][a-z0-9-]*$/`, length <= 24 — is excluded under a heuristic
+ *      reason (`enum-or-token-shaped`), NOT the type-context rule above:
+ *      values like `"primary"`, `"ghost"`, `"sm"`, `"ascending"` are
+ *      extremely common as component variant/size/state tokens passed as
+ *      plain prop values (`<Button variant="ghost">`), a position this
+ *      scanner's local-context heuristics cannot always trace back to a
+ *      `type` declaration. Real visible copy in this codebase is, without
+ *      exception in every example this task cites, EITHER multi-word
+ *      ("No results", "Select an option", "Select all rows") OR starts
+ *      with a capital letter ("Page", "Showing") — a bare, all-lowercase
+ *      single word is a real, stated risk of a false NEGATIVE (a
+ *      genuine one-word lowercase copy string, e.g. a placeholder
+ *      literally `"search…"`, would be missed) traded deliberately against
+ *      a much larger volume of false positives from variant tokens. Not
+ *      silent: every such exclusion is counted and reported by reason.
+ *  10. Files matching `*.test.ts(x)`, `*.spec.ts(x)`, or `*.check.ts(x)` —
+ *      test fixtures and compile-time contract assertions are not shipped
+ *      copy. This is a WHOLE-FILE skip, decided in `scanCopySourceTree`,
+ *      not a per-literal exclusion — see `DEFAULT_SKIP_FILE_RE`.
+ *
+ * A DIFFERENT, SIBLING mechanism — `ScanOptions.pathExclusions` — is ALSO a
+ * whole-file skip, but is consumer-CONFIGURED (this list above is fixed,
+ * shipped by this package) and answers a different question: not "is this
+ * file's CONTENT test/build machinery" but "should this file's path be
+ * looked at for copy candidates at all" (the "mention vs. use" case — a
+ * style guide documenting this voice's own banned terms trips its own
+ * rules if scanned like any other file). See `path-exclusions.ts`'s top
+ * doc comment for the full argument for why this is a NEW, separate type
+ * (`PathExclusion`/`ExcludedPath`), not an 11th `ExclusionReason` — the two
+ * mechanisms are not the same feature wearing two names.
+ *
+ * ============================================================================
+ * JSX TEXT NODES (`<span>Hello</span>`) — closing issue #37
+ * ============================================================================
+ *
+ * String/template literals are only half of what a `.tsx`/`.jsx` file can
+ * show a user: `<span>Hello</span>`'s `Hello` is neither, it is a raw JSX
+ * TEXT NODE, and a scanner that only understands literal boundaries is
+ * blind to it — a gate whose entire job is "no untracked user-facing
+ * copy" would report a clean pass over a file that is nothing but
+ * untracked copy. This is exactly what made this scanner's own top-level
+ * risk real once a JSX-heavy consumer (`@example/ui` in this same
+ * repo) existed: see issue #37.
+ *
+ * The fix stays inside "no parser library": a second, JSX-aware pass
+ * inside `tokenize()`, triggered only in a `.tsx`/`.jsx` file (`isJsxFile`
+ * — a `.ts`/`.js` file is NEVER scanned for JSX at all, so this can never
+ * fire on plain TypeScript/JavaScript). It is mutually recursive in the
+ * same style `skipInterpolation`/`skipTemplateFrom` already use for
+ * nested template interpolations:
+ *
+ *   - `tryScanJsxElement` recognizes a `<` as a JSX element start ONLY
+ *     when the last significant token was in "expression start" position
+ *     (the exact same `lastTokenType === "other"` heuristic already used
+ *     for the regex-vs-division call above) AND the next character is a
+ *     valid tag-name start or `>` (a fragment `<>`). This one condition
+ *     is what keeps `Map<string, string>` (preceded by the identifier
+ *     `Map`, a VALUE token) and `a < b` (preceded by the identifier `a`,
+ *     also a VALUE token) from ever being mistaken for JSX — a generic
+ *     type argument and a comparison are structurally "value `<` ...",
+ *     never "other `<` ...". A string containing `>`/`<`
+ *     (`"a > b < c"`) never reaches this logic at all: the EXISTING
+ *     string-literal branch above already consumes the whole literal,
+ *     `<`/`>` included, before this code ever sees those characters. A
+ *     `/.../ ` regex literal is the same story via the EXISTING regex
+ *     branch. Once a `<` is accepted as JSX-element-shaped, this function
+ *     scans the tag name and its attributes (each attribute value —
+ *     quoted string or `{expression}` — skipped correctly, reusing the
+ *     same string-skip and a JSX-aware sibling of `skipInterpolation`)
+ *     through to the tag's own closing `>`/`/>`. Only once that full,
+ *     well-formed head is found is this function COMMITTED to "this is
+ *     real JSX" — a `<` that turns out to be TSX's `<T,>(x: T) => x`
+ *     generic-arrow-function syntax (which also starts as `< identifier`
+ *     in "other" position) fails immediately inside the attribute list,
+ *     before commitment, and is silently treated as not-JSX with no
+ *     `unchecked` noise at all, precisely because that failure happens
+ *     too early to be good evidence either way.
+ *   - `scanJsxChildren` (only reached once committed) walks the raw text
+ *     between the opening tag's `>` and the next `<`, recording each
+ *     non-whitespace-only run as a text-node candidate (collapsed per
+ *     JSX's own whitespace rule — see `collapseJsxWhitespace` — and
+ *     entity-decoded — see `decodeJsxEntities`). A `<` found here can only
+ *     be a nested element (recurses back into `tryScanJsxElement`,
+ *     finding that element's OWN text nodes too — this is how
+ *     `{condition && <Foo>text</Foo>}`-shaped nesting inside an
+ *     expression child, and plain sibling nesting like
+ *     `<p>Hello <strong>there</strong> friend</p>`, both resolve: each
+ *     text run between element boundaries becomes its own candidate,
+ *     never concatenated across the boundary, never dropping the tail) or
+ *     a closing tag (ends this element, returns to whichever caller is
+ *     scanning ITS OWN children/expression one level up). A `{` starts an
+ *     expression child — `{/* a JSX comment *\/}` and `{expression}` are
+ *     both skipped as CODE, not text (see "WHAT THIS STILL DELIBERATELY
+ *     DOES NOT CATCH" below for the one exception), via the JSX-aware
+ *     sibling of `skipInterpolation` mentioned above, which is itself
+ *     mutually recursive with `tryScanJsxElement`: an expression child
+ *     that itself contains nested JSX (`{items.map((i) => <li
+ *     key={i}>{i}</li>)}`) is walked correctly, finding ITS nested text
+ *     nodes too.
+ *   - Purely whitespace text runs (indentation between sibling JSX tags —
+ *     the overwhelming majority of raw text a real, formatted `.tsx` file
+ *     contains) are dropped at the point of collection, not even entering
+ *     the candidate/exclusion pipeline. This is the one deliberate
+ *     departure from "count and report every exclusion, never silently
+ *     drop": that discipline exists so a REAL, AUTHORED literal a
+ *     developer chose to write is never quietly reclassified without a
+ *     trace. Indentation whitespace between tags was never authored
+ *     content in that sense — it is the ABSENCE of a text node, exactly
+ *     as invisible to a real JSX runtime as it is to this scanner, and
+ *     counting it would drown `printScanAccounting`'s exclusion tally in
+ *     noise proportional to a file's formatting, not its copy. A text run
+ *     that IS present but decorative/symbolic (a bare `"—"` as JSX text,
+ *     the direct JSX-text analogue of exclusion #8 above) still goes
+ *     through the same `no-letters` exclusion as a literal would, and is
+ *     still counted. The enum/token-shaped heuristic (exclusion #9) is
+ *     deliberately NOT applied to JSX text: that heuristic's entire
+ *     justification is "a bare lowercase word is usually a component
+ *     variant/size/state PROP VALUE" — a JSX TEXT NODE can never be a
+ *     prop value by construction (children and props are different
+ *     syntactic positions), so the justification does not transfer, and
+ *     applying it anyway would risk silently dropping exactly the short,
+ *     literal words real UI badges/labels use as visible copy (`"new"`,
+ *     `"beta"`, `"live"`).
+ *   - Entity decoding (`decodeJsxEntities`): the common named entities
+ *     (`&amp;`, `&lt;`, `&gt;`, `&quot;`, `&apos;`, `&nbsp;`, plus a
+ *     small set of typographic entities real copy actually uses —
+ *     `&mdash;`, `&ndash;`, `&hellip;`, `&copy;`, `&reg;`, `&trade;`,
+ *     curly quotes) and every numeric entity (`&#8212;`, `&#x2014;`) are
+ *     decoded before matching/reporting. DECODED, not "classified as
+ *     unchecked": unlike a genuinely ambiguous JSX construct (see below),
+ *     a named entity is a closed, enumerable vocabulary — there is no
+ *     parsing risk in getting it right, only a coverage question, so this
+ *     mirrors the file's own existing precedent for escape sequences (see
+ *     "Full escape-sequence decoding" below): decode the common,
+ *     essentially-total-coverage-in-practice set, and for a named entity
+ *     outside that set, leave it verbatim (undecoded, `&whatever;`
+ *     literally in the candidate's text) rather than either guessing or
+ *     inventing a whole HTML entity table — an accepted, narrow
+ *     simplification, not a silent one (documented here, exactly as the
+ *     escape-sequence one is).
+ *
+ * WHAT THIS STILL DELIBERATELY DOES NOT CATCH, and why it is reported via
+ * `ScanResult.unchecked` instead of silently producing nothing:
+ *
+ *   - Malformed/unbalanced JSX this scanner cannot resolve once it has
+ *     already committed to "this is real JSX" — an opening tag with no
+ *     matching closing tag before end of file, an attribute's quoted
+ *     value or `{expression}` that never terminates, an expression child
+ *     whose braces never balance, or JSX nesting deep enough to trip the
+ *     `MAX_JSX_DEPTH` safety bound. Each of these is recorded as one
+ *     `ScanResult.unchecked` entry (`kind` names the specific situation,
+ *     `detail` is a human-readable explanation) rather than silently
+ *     contributing zero candidates for that construct — the same
+ *     "never silently narrow coverage" discipline `ParseFailure` already
+ *     holds string/template literal tokenizing to, extended to the one
+ *     new category (JSX) this version adds. `checkCopyTraceability` and
+ *     `writer-check` (`cli.ts`) both surface a non-empty `unchecked` list —
+ *     see their own doc comments for exactly where it lands in each
+ *     one's contract.
+ *   - A fully general regex-vs-division disambiguation for `/`. This
+ *     scanner uses the same last-significant-token heuristic every
+ *     hand-rolled JS lexer uses (see `isRegexAllowedHere`), which is wrong
+ *     on rare, contrived inputs (e.g. `/` immediately after a `)` that
+ *     closed an `if` condition, when a regex was actually intended). If
+ *     that heuristic ever desyncs the scanner badly enough that quote
+ *     balance goes wrong by end of file, the file is reported as a PARSE
+ *     FAILURE (see `ParseFailure`) and contributes zero candidates —
+ *     never silently mis-scanned.
+ *   - Full escape-sequence decoding (`\u{1F600}`, `\x41`, ...). Only the
+ *     common cases (`\\`, `\'`, `\"`, `` \` ``, `\n`, `\r`, `\t`, `\$`) are
+ *     unescaped for the `normalized`/`raw` text used in reporting and
+ *     matching; anything else has its leading backslash stripped and the
+ *     rest passed through verbatim. Reporting/matching text may therefore
+ *     be very slightly off for a literal using an exotic escape — an
+ *     accepted, narrow simplification, not a silent one (documented here).
+ */
+import { type ExcludedPath, type PathExclusion, type PathExclusionFinding } from "./path-exclusions.js";
+export type { ExcludedPath, PathExclusion, PathExclusionFinding, PathExclusionFindingRule } from "./path-exclusions.js";
+export interface ScanOptions {
+    /** File extensions to read, each including the leading dot. Default: `.ts`, `.tsx`, `.js`, `.jsx`. */
+    extensions?: string[];
+    /** Directory names never descended into. Default: node_modules, .git, dist, build, coverage. */
+    skipDirs?: string[];
+    /**
+     * Files to skip entirely — never tokenized, never contribute a
+     * `CopyCandidate`/`ExcludedLiteral`/`Citation`/`UncheckedItem`. A DIFFERENT
+     * feature from `ExclusionReason` — see `path-exclusions.ts`'s top doc
+     * comment for the full "mention vs. use" case this exists for and exactly
+     * why it is not a tenth `ExclusionReason`. Defaults to `[]` (no
+     * exclusions — identical to every prior release of this package).
+     */
+    pathExclusions?: PathExclusion[];
+}
+export interface CopyCandidate {
+    /** Repo-relative, `/`-joined path this candidate was found in. */
+    file: string;
+    /** 1-indexed line the literal/text node starts on. */
+    line: number;
+    /** `"jsx-text"` is a raw JSX text node (`<span>Hello</span>`'s `Hello`) — see this file's top doc comment, "JSX TEXT NODES". Unlike `"string"`/`"template"`, it has no quote/backtick delimiters at all. */
+    kind: "string" | "template" | "jsx-text";
+    /**
+     * Original source text, trimmed for display. For `"string"`/`"template"`,
+     * includes the literal's own quotes/backticks. For `"jsx-text"`, there
+     * are no delimiters to include — this is the JSX-whitespace-collapsed,
+     * entity-decoded text itself (see `collapseJsxWhitespace`/
+     * `decodeJsxEntities`).
+     */
+    raw: string;
+    /**
+     * The literal's STATIC text with every interpolation (`${...}`)
+     * collapsed to `PLACEHOLDER_SENTINEL` — identical to `raw`'s unescaped
+     * content for a plain string (zero interpolations). This is what
+     * `copy-gate.ts` compares against a `CopyEntry.text` normalized the same
+     * way (its own `{name}` placeholders collapsed to the same sentinel) —
+     * comparing SHAPE, never a specific placeholder name, since this
+     * scanner has no way to know what name a `CopyEntry` author chose for
+     * an interpolation this source expression computes some other way.
+     */
+    normalized: string;
+    /** Number of `${...}` interpolations found (0 for a plain string). */
+    placeholderCount: number;
+    /**
+     * Every `copy:<id>` citation found on this candidate's own source line
+     * (see `CITATION_RE`) — `copy-gate.ts`'s escape hatch, mirroring
+     * `@example/strategy`'s `fact:<key>`. Whether any of these ids
+     * actually exist in a real `CopyRecord` is `copy-gate.ts`'s question to
+     * ask, not this scanner's — this scanner only reports what text is
+     * literally present on the line.
+     */
+    citedIds: string[];
+    /** Whether a `copy-gate:ignore` marker (see `IGNORE_MARKER_RE`) is present on this candidate's own source line. */
+    hasIgnoreMarker: boolean;
+}
+/**
+ * One `copy:<id>` citation found anywhere in a file, independent of
+ * whether any candidate happens to share its line — mirrors
+ * `@example/strategy`'s `facts-gate.ts` Pass 1, which checks every
+ * line for a `fact:<key>` citation regardless of whether that line also
+ * carries a claim, so a citation to a rotted/misspelled id is caught even
+ * when it sits on a line with no traceable literal at all (e.g. a stray
+ * citation left behind after the copy it once annotated was deleted).
+ */
+export interface Citation {
+    file: string;
+    line: number;
+    id: string;
+}
+export type ExclusionReason = "import-or-require-specifier" | "object-or-destructuring-key" | "type-or-interface-context" | "aria-or-data-attribute-value" | "denylisted-attribute-or-prop-value" | "classname-builder-argument" | "developer-diagnostic-argument" | "no-letters" | "enum-or-token-shaped";
+export interface ExcludedLiteral {
+    file: string;
+    line: number;
+    /** The literal's raw source text (quotes included), for a human auditing the exclusion list. */
+    raw: string;
+    reason: ExclusionReason;
+}
+export interface ParseFailure {
+    file: string;
+    /** Human-readable detail — an unterminated string/template/comment/regex, or the scanner ran off the end of the file in an inconsistent state. */
+    detail: string;
+}
+export interface SkippedFile {
+    file: string;
+    reason: "test-or-check-file";
+}
+/**
+ * One construct this scanner recognized as JSX-shaped but could not
+ * reliably classify — an unclosed element, an unterminated attribute
+ * value or expression, a nested expression child whose braces never
+ * balanced, or JSX nesting deep enough to trip the depth safety bound.
+ * See this file's top doc comment, "WHAT THIS STILL DELIBERATELY DOES
+ * NOT CATCH". NEVER how a genuine blind spot gets to stay invisible: a
+ * consumer that only checks `candidates`/`excluded` and ignores this
+ * field would be exactly the failure mode issue #37 was about — a scan
+ * that narrowed its own coverage and reported the narrowed result as a
+ * pass. `checkCopyTraceability` (`copy-gate.ts`) and `writer-check`
+ * (`cli.ts`) both refuse to let a non-empty list here go unreported.
+ */
+export interface UncheckedItem {
+    file: string;
+    line: number;
+    /** A short, stable machine-readable name for the situation, e.g. `"unclosed-jsx-element"`, `"malformed-jsx-expression"`, `"malformed-jsx-tag"`, `"unrecognized-jsx-child"`, `"jsx-depth-exceeded"`. */
+    kind: string;
+    /** Human-readable explanation, for a report or a human auditing the list. */
+    detail: string;
+}
+export interface ScanResult {
+    /** Files whose content was successfully tokenized (whether or not it produced any candidates). This is the number `cli.ts` requires to be > 0 for a clean pass — see copy-gate.ts / cli.ts's exit-code discipline. */
+    filesScanned: number;
+    candidates: CopyCandidate[];
+    /** Every literal this scanner found and deliberately excluded, with why — never silently dropped. See exclusions #1-#9 above. */
+    excluded: ExcludedLiteral[];
+    /** Every `copy:<id>` citation found anywhere in a scanned file — see `Citation`'s own doc comment for why this is file-wide, not just per-candidate. */
+    citations: Citation[];
+    /** Files matched by extension/walk but never tokenized at all — test/check/declaration files, by design (exclusion #10). Counted, never silent. */
+    skippedByDesign: SkippedFile[];
+    /** Files that were read but could not be reliably tokenized (unbalanced quote/comment/regex state at EOF) — contribute zero candidates. Counted, never silently treated as "0 findings". */
+    parseFailures: ParseFailure[];
+    /** Constructs the scanner recognized as JSX-shaped but could not classify — see `UncheckedItem`. Empty is the ordinary, expected outcome for a well-formed file; it is never emptied to make a report look cleaner than it is. */
+    unchecked: UncheckedItem[];
+    /** Files matched by extension/walk but skipped entirely because a caller-supplied `ScanOptions.pathExclusions` entry matched their path — see `path-exclusions.ts`. Counted, never silent, and DIFFERENT from `skippedByDesign` (this package's own built-in test/check-file skip) and from `excluded` (a per-LITERAL classification inside a file that WAS scanned). */
+    excludedFiles: ExcludedPath[];
+    /** Problems with `ScanOptions.pathExclusions` itself, not with any scanned file's content — a malformed entry (`"error"`, never applied) or an entry that matched zero files this run (`"warning"`, stale but still applied as configured). See `path-exclusions.ts`'s top doc comment for the fail-closed contract. Empty is the ordinary outcome when `pathExclusions` is omitted or every entry is well-formed and matched something. */
+    pathExclusionFindings: PathExclusionFinding[];
+}
+/**
+ * Walks `root` recursively, reads every matching file, and extracts copy
+ * candidates from each (see `extractCopyCandidates`). FAILS CLOSED on an
+ * unreadable directory or file — throws a plain `Error`, matching
+ * `@example/strategy`'s `scanStrategyDirectory` and this
+ * repository's own `scripts/check-contamination-classes.mjs` walker: a
+ * directory this function could not read might be hiding an unknown,
+ * unbounded amount of unregistered copy, and reporting "0 files scanned"
+ * for that case would read as a clean pass when nothing was actually
+ * verified. `cli.ts` is what turns this thrown error into exit code 2.
+ */
+export declare function scanCopySourceTree(root: string, options?: ScanOptions): ScanResult;
+/**
+ * Collapses every interpolation in a template literal's static text to one
+ * comparable shape. `\uE000` is the first code point of the Unicode
+ * Private Use Area — reserved by the standard for exactly this kind of
+ * private, non-textual sentinel use, and something no legitimate JS/TS
+ * source file authoring real UI copy will ever contain, so it can be
+ * dropped in without risk of colliding with genuine copy text (unlike,
+ * say, a literal space or `{}`, which real copy could plausibly contain).
+ * Exported so `copy-gate.ts` normalizes `CopyEntry.text`'s `{name}`
+ * placeholders to this exact same sentinel before comparing shapes.
+ */
+export declare const PLACEHOLDER_SENTINEL = "\uE000";
+interface ExtractResult {
+    candidates: CopyCandidate[];
+    excluded: ExcludedLiteral[];
+    citations: Citation[];
+    /** See `ScanResult.unchecked` — this is the per-file slice `scanCopySourceTree` aggregates into it. */
+    unchecked: UncheckedItem[];
+    parseFailure?: string;
+}
+/**
+ * Pure — no I/O. Tokenizes `content` and classifies every string/template
+ * literal AND (in a `.tsx`/`.jsx` file) every JSX text node found as
+ * either a copy candidate or an excluded literal (with a stated reason),
+ * per "THE BOUNDARY" in this file's top doc comment. Exported so a test
+ * (or a future consumer wanting extraction without a real directory
+ * walk) can exercise the classification logic directly against a
+ * source-text fixture.
+ */
+export declare function extractCopyCandidates(content: string, filePath: string): ExtractResult;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

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