@clossys/writer 0.3.2

package/dist/addressability.d.ts

@@ -0,0 +1,245 @@
+/**
+ * `scanAddressabilitySources` and `checkAddressability` — the
+ * copy-ADDRESSABILITY gate: is user-facing prose resolved from a copy
+ * registry BY ID, or typed directly into a component? A DIFFERENT, STRICTER
+ * question than `copy-gate.ts`'s traceability check. Traceability accepts a
+ * literal that happens to match a registered `CopyEntry.text`'s SHAPE, or
+ * that carries a `copy:<id>` citation comment — both of which still leave
+ * the actual sentence sitting in the component's own source. That is cheap
+ * to verify but NOT cheap to change: marketing renaming a CTA means editing
+ * every component that typed it, not one registry entry. Addressability is
+ * the property that keeps that rename cheap: the component's own source
+ * contains an id, never the sentence. This file does not accept a citation
+ * or a text-shape match as satisfying — see `extractAddressabilityCandidates`
+ * below, which has no `CopyRecord` input at all and therefore nothing to
+ * match against; a literal is either not present as authored prose in a
+ * position this gate can see, or it is a violation.
+ *
+ * Measured across four real sites at the time this gate was written: 2
+ * inline prose strings on one, 4 attribute-borne on another, 0 elsewhere —
+ * so the property currently holds, by luck rather than enforcement. This
+ * file is what turns that measurement into something that stays true.
+ *
+ * NO PARSER LIBRARY, no new dependency — `packages/copy` ships zero runtime
+ * dependencies and this file adds none. It reuses `scan.ts`'s
+ * `extractCopyCandidates` for the genuinely hard part (finding every
+ * string/template literal and JSX text-node BOUNDARY correctly — escaped
+ * quotes, nested interpolation, comments, regex literals, and JSX itself),
+ * and `path-exclusions.ts`'s `validatePathExclusions`/`matchesPathExclusion`
+ * for the file-scope exclusion mechanism, exactly the way `scan.ts` itself
+ * does. This file's own walker (`scanAddressabilitySources`) mirrors
+ * `scan.ts`'s `scanCopySourceTree` and `@example/ui`'s
+ * `style-scan.ts`'s `scanStyleSources` closely (same extensions/skipDirs
+ * defaults, same `SKIP_FILE_RE`, same fail-closed-on-unreadable-directory
+ * contract) — a thin per-file dispatch loop, not a second tokenizer: the
+ * actual literal/JSX-boundary parsing is ENTIRELY delegated to `scan.ts`.
+ *
+ * ============================================================================
+ * THREE POSITIONS, THREE CLASSIFICATIONS
+ * ============================================================================
+ *
+ * 1. MARKUP TEXT NODES (`<span>Hello</span>`'s `Hello`) — `scan.ts`'s own
+ *    `kind: "jsx-text"` candidates. `scan.ts` already dropped
+ *    whitespace-only and no-letters runs before these ever reach this
+ *    file, so every one remaining is real, rendered prose authored
+ *    directly in markup — never resolved through an id, by construction
+ *    (a JSX text node IS the literal text; an id-resolved child would be
+ *    an EXPRESSION child, `{copy(id)}`, which `scan.ts`'s tokenizer treats
+ *    as code, never a text-node candidate at all — see `scan.ts`'s own
+ *    top doc comment, "JSX TEXT NODES"). ALWAYS a violation.
+ *
+ * 2. THE FOUR USER-FACING ATTRIBUTES — `aria-label`, `placeholder`, `alt`,
+ *    `title`. These carry prose a person reads (an accessible name, a
+ *    hint, alt text, a tooltip) and are NOT text nodes; a scanner that
+ *    only understands text nodes reports zero on a real component whose
+ *    ENTIRE user-facing surface is `<input aria-label="..." placeholder=
+ *    "..." />` and calls that a clean pass. `scan.ts` itself already
+ *    excludes `aria-label` from its own candidate list (bundled under
+ *    `"aria-or-data-attribute-value"` together with `aria-hidden`,
+ *    `aria-describedby`, every `data-*` attribute — a deliberate SCOPE
+ *    decision for traceability, see `scan.ts`'s exclusion #4) and leaves
+ *    `placeholder`/`alt`/`title` as ordinary default-included candidates
+ *    (neither aria/data-shaped nor on its structural denylist). This gate
+ *    re-derives each literal's own attribute NAME locally — a string
+ *    literal never spans a line (see `scan.ts`'s `scanStringLiteral`), so
+ *    "the identifier immediately before this literal's own quote, on the
+ *    SAME line" is an exact lookup, not an approximation — specifically to
+ *    recover `aria-label` back into scope while leaving every OTHER
+ *    aria-*, data-* attribute exactly where `scan.ts` already decided it
+ *    belongs: out of copy governance entirely. A literal-valued occurrence
+ *    of one of the four, carrying at least one letter, is ALWAYS a
+ *    violation — there is no citation or registry-text-match escape hatch
+ *    here (see this file's top comment for why) — UNLESS the assignment
+ *    this gate re-derived is itself a DESTRUCTURING-PATTERN DEFAULT or a
+ *    plain (non-destructured) PARAMETER DEFAULT (`{ "aria-label":
+ *    ariaLabel = "Pagination" }`, `{ placeholder = "Search" }`,
+ *    `function f(alt = "...")`), never a JSX attribute at all — see
+ *    `isDestructuringOrParameterDefault`. A default value in a
+ *    destructuring pattern is exactly the property this gate exists to
+ *    protect: the CONSUMER can override it, so the component's own source
+ *    does not lock the sentence in the way a hardcoded JSX attribute
+ *    does. Reporting one as a violation would not just be a false
+ *    positive — it would INVERT the verdict on a construct that is
+ *    already correctly addressable.
+ *
+ * 3. EVERYTHING ELSE THIS GATE CANNOT CONFIDENTLY CLASSIFY — a template
+ *    literal (in ANY position, including one of the four attributes above:
+ *    a template can carry an interpolated copy id, a partial sentence, or
+ *    genuine inline prose, and this gate does not attempt to tell those
+ *    apart), an object/array literal VALUE (`scan.ts` only excludes object
+ *    KEYS, never values — `{ tooltip: "Explain this" }`'s `"Explain
+ *    this"` is a default-included candidate with no attribute name at
+ *    all), or a plain string in a prop that is none of the four (a custom
+ *    `tooltip`, a bare variable assignment, ...) — UNLESS that string is
+ *    itself shaped like a CSS/Tailwind utility class LIST (`"border-t
+ *    border-line-base pt-xs"`, `"grid-cols-1 tablet:grid-cols-2"`), which
+ *    is definitively not prose and is excluded here for the same reason
+ *    `scan.ts` already excludes that shape when it DOES have an attribute
+ *    name to key off (a literal `className="..."` value) — see
+ *    `looksLikeUtilityClassList`. Everything else in this category is
+ *    NEVER silently treated as clean, and NEVER treated as a violation
+ *    either — reported as `unchecked`, the same discipline `scan.ts`'s own
+ *    `UncheckedItem` and `checkCopyTraceability`'s `unchecked` passthrough
+ *    already hold JSX parse ambiguities to. A measurement may round an
+ *    unknown down to "probably fine"; a gate may not — that is the whole
+ *    reason this file exists rather than a grep for `aria-label="`.
+ *
+ * `scan.ts`'s own exclusions for genuinely non-user-facing literals
+ * (`className`, `data-testid`, an import specifier, a `cx(...)` argument, a
+ * developer diagnostic, a decorative no-letters glyph, an enum-shaped
+ * single token, a `type`/`interface` context) apply here for free: a
+ * literal `scan.ts` excludes for one of THOSE reasons never becomes a
+ * `candidates` entry at all, so it never reaches this file's own
+ * classification and is never reported by it, in any of the three
+ * categories above. This is what keeps this gate from flagging `className`,
+ * `data-*`, an import specifier, or a `testId` — see this file's own test
+ * suite for a fixture proving exactly that.
+ *
+ * ============================================================================
+ * THE TERNARY
+ * ============================================================================
+ *
+ * Deliberately DIFFERENT from `copy-gate.ts`/`scan.ts`'s "an `unchecked[]`
+ * list gates a `2` before findings are counted" precedence — see issue #407.
+ * On this gate specifically, partial coverage of a real tree is not a rare
+ * edge case: hundreds of string positions are token data (category 3 above)
+ * this gate cannot classify BY DESIGN, on every real tree it has ever been
+ * run against. Letting "at least one unclassified position" outrank a
+ * confirmed violation therefore does not model "an occasional coverage gap
+ * might be hiding something" — it makes the `"violated"` branch permanently
+ * unreachable outside a fixture, because a real tree always has unclassified
+ * positions somewhere. A gate that can only ever report `"indeterminate"` or
+ * `"satisfied"` in production has one usable state, and a caller that
+ * learns to treat `2` as "coverage is never complete, ignore it" will walk
+ * straight past five named, file-and-line violations without ever seeing
+ * them — see `packages/inspector/src/review-evidence.ts`'s own argument
+ * against the mirror image of this mistake (folding an outage into a
+ * verdict); this is folding a verdict into an outage.
+ *
+ *   - `"violated"` — at least one inline user-facing prose string found
+ *     (category 1 or 2 above), REGARDLESS of how many string positions are
+ *     unclassified. The coverage gap is not hidden: `reasons` and
+ *     `unchecked` are still populated and still printed (`cli.ts`'s
+ *     `printAddressabilityAccounting` reports `unchecked` unconditionally,
+ *     independent of verdict) — a `"violated"` verdict never claims full
+ *     coverage, it claims that what WAS seen included a definite violation,
+ *     which is true regardless of what else was not seen.
+ *   - `"indeterminate"` — zero violations, AND the source tree could not be
+ *     read at all (this file's `scanAddressabilitySources` fails closed,
+ *     throwing, exactly like `scan.ts`'s `scanCopySourceTree`), ZERO
+ *     components were successfully scanned (nothing matched, or every
+ *     matched file failed to parse), a `pathExclusions` entry was
+ *     malformed, or ANY string position could not be confidently classified
+ *     (category 3 above, or a JSX construct `scan.ts` itself could not
+ *     resolve). The honest "found nothing, but did not see everything"
+ *     case — it must never read as a pass.
+ *   - `"satisfied"` — at least one component scanned, every string
+ *     position classified, and no inline user-facing prose found.
+ */
+import type { ParseFailure, SkippedFile } from "./scan.js";
+import { type ExcludedPath, type PathExclusion, type PathExclusionFinding } from "./path-exclusions.js";
+export type { ParseFailure, SkippedFile } from "./scan.js";
+export type { ExcludedPath, PathExclusion, PathExclusionFinding } from "./path-exclusions.js";
+export interface AddressabilityScanOptions {
+    /** 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[];
+    /** Same mechanism `scan.ts`'s `ScanOptions.pathExclusions` uses — see `path-exclusions.ts`. */
+    pathExclusions?: PathExclusion[];
+}
+export type AddressabilityPosition = "markup-text" | "user-facing-attribute";
+export interface AddressabilityViolation {
+    file: string;
+    line: number;
+    position: AddressabilityPosition;
+    /** Set only for `"user-facing-attribute"` — which of the four this literal was the value of. */
+    attribute?: "aria-label" | "placeholder" | "alt" | "title";
+    /** The literal's own raw source text, for a human auditing the finding. */
+    raw: string;
+}
+export interface AddressabilityUncheckedItem {
+    file: string;
+    line: number;
+    /** A short, stable machine-readable name — see this file's top doc comment, category 3, and `extractAddressabilityCandidates`'s own inline comments for every kind this can be. */
+    kind: string;
+    detail: string;
+}
+export interface AddressabilityScanResult {
+    /** Files whose content was successfully tokenized. Required to be > 0 for a satisfied verdict — see this file's top doc comment, "THE TERNARY". */
+    filesScanned: number;
+    violations: AddressabilityViolation[];
+    /** Every string position this gate could not confidently classify — never silently dropped. See this file's top doc comment, category 3. */
+    unchecked: AddressabilityUncheckedItem[];
+    skippedByDesign: SkippedFile[];
+    parseFailures: ParseFailure[];
+    excludedFiles: ExcludedPath[];
+    pathExclusionFindings: PathExclusionFinding[];
+}
+/**
+ * Walks `root` recursively, reads every matching file, and extracts
+ * addressability violations/unchecked positions from each (see
+ * `extractAddressabilityCandidates`). FAILS CLOSED on an unreadable
+ * directory or file — throws a plain `Error`, matching `scan.ts`'s
+ * `scanCopySourceTree` exactly, for the identical reason: a directory this
+ * function could not read might be hiding an unknown amount of inline
+ * prose, and reporting "0 files scanned" for that case would read as a
+ * clean pass when nothing was actually verified.
+ */
+export declare function scanAddressabilitySources(root: string, options?: AddressabilityScanOptions): AddressabilityScanResult;
+interface AddressabilityExtractResult {
+    violations: AddressabilityViolation[];
+    unchecked: AddressabilityUncheckedItem[];
+    parseFailure?: string;
+}
+/**
+ * Pure — no I/O. Classifies every string/template literal and JSX text
+ * node `scan.ts`'s `extractCopyCandidates` finds in `content` into one of
+ * this file's three positions (see top doc comment). Exported so a test
+ * can exercise classification directly against a source-text fixture,
+ * mirroring `extractCopyCandidates` itself.
+ */
+export declare function extractAddressabilityCandidates(content: string, filePath: string): AddressabilityExtractResult;
+export type AddressabilityVerdict = "satisfied" | "violated" | "indeterminate";
+export interface AddressabilityGateResult {
+    verdict: AddressabilityVerdict;
+    violations: AddressabilityViolation[];
+    unchecked: AddressabilityUncheckedItem[];
+    filesScanned: number;
+    /**
+     * Human-readable reasons coverage is incomplete — empty for `"satisfied"`.
+     * Since #407, this can be non-empty for `"violated"` too: a run can find a
+     * definite violation AND have unclassified positions left over in the
+     * same scan. Only `"indeterminate"` requires `reasons.length > 0`; a
+     * `"violated"` verdict does not promise `reasons` is empty, only that at
+     * least one real finding exists regardless of what else `reasons` lists.
+     */
+    reasons: string[];
+}
+/**
+ * Pure — takes an already-computed `AddressabilityScanResult`, decides the
+ * ternary verdict. Mirrors `copy-gate.ts`'s `checkCopyTraceability` split
+ * from `scan.ts`: this function does no I/O and never throws.
+ */
+export declare function checkAddressability(scan: AddressabilityScanResult): AddressabilityGateResult;
+//# sourceMappingURL=addressability.d.ts.map

package/dist/addressability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addressability.d.ts","sourceRoot":"","sources":["../src/addressability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6JG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAE1B,MAAM,sBAAsB,CAAC;AAE9B,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC3D,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAI9F,MAAM,WAAW,yBAAyB;IACxC,sGAAsG;IACtG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+FAA+F;IAC/F,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAQD,MAAM,MAAM,sBAAsB,GAAG,aAAa,GAAG,uBAAuB,CAAC;AAE7E,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,sBAAsB,CAAC;IACjC,gGAAgG;IAChG,SAAS,CAAC,EAAE,YAAY,GAAG,aAAa,GAAG,KAAK,GAAG,OAAO,CAAC;IAC3D,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,mLAAmL;IACnL,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,mJAAmJ;IACnJ,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,4IAA4I;IAC5I,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,eAAe,EAAE,WAAW,EAAE,CAAC;IAC/B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;CAC/C;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,yBAA8B,GAAG,wBAAwB,CAgGzH;AA+ID,UAAU,2BAA2B;IACnC,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,2BAA2B,CA+G9G;AAID,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,UAAU,GAAG,eAAe,CAAC;AAE/E,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,UAAU,EAAE,uBAAuB,EAAE,CAAC;IACtC,SAAS,EAAE,2BAA2B,EAAE,CAAC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,wBAAwB,GAAG,wBAAwB,CAuC5F"}