@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/legibility/index.d.ts

@@ -1,529 +1,3 @@
-/**
- * The vocabulary of the legibility gate: what a finding is, what a suppression
- * is, and what a product configures.
- *
- * Kept in its own module so the checks, the report formatter and the bin all
- * agree on one shape, and so a consumer can import the types without pulling in
- * `node:fs`.
- */
-/** The checks this gate runs. Each is individually suppressible, by name. */
-type LegibilityCheckId = 
-/** Words on screen that belong to the codebase, not to the reader. */
-'engineering-vocabulary'
-/** An empty/zero state whose subtree offers no next action. */
- | 'dead-end-empty-state'
-/** A success state set without inspecting the response that would deny it. */
- | 'unchecked-success'
-/** A `catch` that neither surfaces the failure nor rethrows it. */
- | 'silent-failure'
-/** A route no navigation entry and no in-source link can reach. */
- | 'unreachable-capability'
-/** A suppression comment that names a check but gives no reason. */
- | 'suppression-without-reason';
-declare const LEGIBILITY_CHECKS: readonly LegibilityCheckId[];
-/** One defect, at one place, with the fix named. */
-interface LegibilityFinding {
-    readonly check: LegibilityCheckId;
-    /** Path as reported — relative to the working directory when it is inside it. */
-    readonly file: string;
-    /** 1-based. */
-    readonly line: number;
-    /** 1-based. */
-    readonly column: number;
-    /** What is wrong, in one sentence a reviewer can act on. */
-    readonly message: string;
-    /** What to do about it. Every finding carries one; a finding without a fix is a complaint. */
-    readonly remedy: string;
-    /** The offending source, trimmed to one readable line. */
-    readonly evidence: string;
-}
-/** A suppression that was honoured, with the reason its author wrote. */
-interface LegibilitySuppression {
-    readonly check: LegibilityCheckId;
-    readonly reason: string;
-    readonly file: string;
-    readonly line: number;
-}
-interface LegibilityReport {
-    readonly ok: boolean;
-    readonly findings: readonly LegibilityFinding[];
-    /** Honoured suppressions — printed, never silent. */
-    readonly suppressed: readonly LegibilitySuppression[];
-    readonly filesScanned: number;
-    readonly checksRun: readonly LegibilityCheckId[];
-}
-/** A banned term plus the sentence that replaces it. */
-interface BannedTerm {
-    /** Matched case-insensitively at word boundaries against visible copy. */
-    readonly term: string;
-    /** What to write instead — printed with the finding. */
-    readonly instead: string;
-}
-interface VocabularyOptions {
-    /** Replaces the default list outright. */
-    readonly terms?: readonly BannedTerm[];
-    /** Added to the default list — the common case for a product's own jargon. */
-    readonly extraTerms?: readonly BannedTerm[];
-    /** Removed from the default list, for a word that is genuinely the reader's. */
-    readonly allowTerms?: readonly string[];
-    /**
-     * Additional JSX attributes / object keys whose string value is user-visible
-     * copy (the defaults cover `title`, `label`, `placeholder`, `empty*`, …).
-     */
-    readonly extraCopyKeys?: readonly string[];
-    /**
-     * Additional call names whose first string argument is user-visible copy
-     * (defaults cover `toast*`, `alert`, `setError`, `new Error`).
-     */
-    readonly extraCopyCalls?: readonly string[];
-    /**
-     * Also read strings filling an object key named like copy
-     * (`description: '…'`). OFF by default: measured as the tier that reports
-     * system prompts, MCP tool descriptions and document templates — text no
-     * reader ever sees. Turn it on when your data modules really do hold UI copy.
-     */
-    readonly includeObjectCopy?: boolean;
-}
-interface EmptyStateOptions {
-    /** Extra tags that count as an action (defaults: button, a, input, form, *Button, *Link, …). */
-    readonly extraActionTags?: readonly string[];
-    /** Extra props that count as an action (defaults: onClick, onSubmit, href, to, action, …). */
-    readonly extraActionProps?: readonly string[];
-    /** Extra regexes (as source strings) that identify empty-state copy. */
-    readonly extraEmptyPatterns?: readonly string[];
-    /**
-     * Also report a zero-state that sits directly under a heading. OFF by
-     * default: measured as the largest false-positive class — a titled section
-     * with nothing in it labels a screen the reader is already oriented on, and a
-     * detail page carrying four of them buries the one screen that is entirely
-     * empty.
-     */
-    readonly reportSectionZeroStates?: boolean;
-}
-interface SuccessOptions {
-    /**
-     * Callees that resolve on a failed request instead of throwing. `fetch` is the
-     * default and the reason this check exists; add your own thin wrapper here.
-     */
-    readonly httpCalls?: readonly string[];
-    /** Extra identifiers that mean "the user has been told it worked". */
-    readonly extraSuccessSignals?: readonly string[];
-    /**
-     * Calls that inspect a response and throw on a bad status
-     * (`assertOk(res)`). Their presence in the same function counts as checking.
-     */
-    readonly okGuards?: readonly string[];
-}
-interface SilentFailureOptions {
-    /** Extra identifiers that count as surfacing a failure to the user. */
-    readonly extraErrorSinks?: readonly string[];
-    /**
-     * Path substrings whose modules cannot reach a browser, and whose handlers
-     * are therefore not this check's business. Defaults to react-router's
-     * server-only conventions (`/.server/`, `/routes/api.`); pass `[]` to read
-     * every module, at the measured cost of a large false-positive class
-     * (best-effort telemetry, audit writes and cache fallbacks).
-     */
-    readonly readerlessPaths?: readonly string[];
-}
-interface ReachabilityOptions {
-    /**
-     * A react-router `routes.ts` (the `@react-router/dev/routes` shape:
-     * `route()` / `index()` / `layout()` / `prefix()`).
-     */
-    readonly routeConfigFile?: string;
-    /** Route paths supplied directly, for a product on another router. */
-    readonly routePaths?: readonly string[];
-    /** Files that define navigation. Their path literals are the nav entries. */
-    readonly navFiles?: readonly string[];
-    /** Route paths (or prefixes ending in `/*`) that need no door — defaults to `api/*`. */
-    readonly ignore?: readonly string[];
-    /**
-     * Treat a route whose module is not a `.tsx` file as a resource endpoint
-     * rather than a screen. Default true — react-router resource routes are `.ts`.
-     */
-    readonly ignoreNonTsxRoutes?: boolean;
-}
-/** What a product writes in `legibility.config.mjs`. */
-interface LegibilityConfig {
-    /** Source directories to scan, recursively. At least one. */
-    readonly srcDirs: readonly string[];
-    /** Turn a check off wholesale. Prefer a per-line suppression with a reason. */
-    readonly checks?: Partial<Record<LegibilityCheckId, boolean>>;
-    readonly vocabulary?: VocabularyOptions;
-    readonly emptyState?: EmptyStateOptions;
-    readonly success?: SuccessOptions;
-    readonly silentFailure?: SilentFailureOptions;
-    readonly reachability?: ReachabilityOptions;
-    /** Path substrings to skip, added to the defaults (tests, fixtures, generated). */
-    readonly ignorePaths?: readonly string[];
-}
-
-/**
- * The report a product reads in its CI log.
- *
- * A gate is only as good as the sentence a developer reads at 6pm with a red
- * build. So every finding prints three things and never fewer: WHERE
- * (`file:line:col`, clickable in every terminal and editor), WHAT is wrong in
- * the reader's terms, and WHAT TO DO about it. A finding without a remedy is a
- * complaint, and complaints get suppressed rather than fixed.
- *
- * Honoured suppressions are counted in the summary and listed on request. A
- * suppression that nobody can see is a disabled check with extra steps.
- */
-
-interface FormatOptions {
-    /** Print every honoured suppression with its reason. */
-    readonly listSuppressions?: boolean;
-    /** Wrap check names in ANSI colour. Off by default — CI logs keep the bytes. */
-    readonly colour?: boolean;
-}
-declare function formatLegibilityReport(report: LegibilityReport, options?: FormatOptions): string;
-/** The machine-readable form, for a product that posts findings somewhere. */
-declare function legibilityReportToJson(report: LegibilityReport): string;
-
-/**
- * A purpose-built TS/TSX scanner: the one place this subpath decides what part
- * of a file is CODE and what part is COPY A HUMAN READS.
- *
- * Every legibility check needs the same distinction, and getting it from
- * per-check regexes is what makes a lint gate imprecise enough to be turned off.
- * `grep -i artifact` over one product's `apps/web/src` returns 11 hits and every
- * single one is an import specifier, a prop name, or a doc comment — zero are on
- * screen. A checker that reports those 11 is deleted within a week, and then it
- * guards nothing.
- *
- * So this module lexes instead: one pass produces (a) classified SEGMENTS —
- * comments, string literals, template chunks, JSX text, JSX attribute values —
- * and (b) a JSX ELEMENT TREE with spans, attributes, and the enclosing
- * expression container. Checks read those, never the raw bytes.
- *
- * It is a lexer, not a type-aware parser, and that boundary is deliberate: this
- * package ships one runtime dependency and adding `typescript` to every
- * consumer's install to lint copy is the wrong trade. What a lexer cannot do —
- * resolve a string through a variable, follow a component's props to its render
- * — is out of scope by construction and documented per check.
- *
- * Node-agnostic: pure string in, data out. The `fs` walking lives in `scan.ts`.
- */
-/** What a stretch of source is, once the lexer has decided. */
-type SegmentKind = 
-/** `//…` or `/*…*​/` — never user-visible; every check skips these. */
-'comment'
-/** A `'…'` / `"…"` literal in code position. Visible only in some contexts. */
- | 'string'
-/** One literal chunk of a template literal (the `${…}` holes are code). */
- | 'template'
-/** Text between JSX tags. The highest-confidence user-visible signal there is. */
- | 'jsx-text'
-/** A `name="…"` attribute value on a JSX element. */
- | 'jsx-attribute';
-/** One classified stretch of source. */
-interface SourceSegment {
-    readonly kind: SegmentKind;
-    /** Offset of the first character of the segment's VALUE (inside the quotes). */
-    readonly start: number;
-    /** Offset just past the segment's value. */
-    readonly end: number;
-    /** The value text, quotes stripped, escapes left as written. */
-    readonly value: string;
-    /** For `jsx-attribute`: the attribute name. For `jsx-text`: absent. */
-    readonly attribute?: string;
-    /** For `jsx-attribute` / `jsx-text`: the owning element's tag name. */
-    readonly tag?: string;
-}
-/** One attribute on a JSX element. */
-interface JsxAttribute {
-    readonly name: string;
-    readonly start: number;
-    /** The literal value when written `name="…"`; null when `name={…}` or bare. */
-    readonly value: string | null;
-    /** True when written `name={…}` — the value is code, not copy. */
-    readonly expression: boolean;
-}
-/** One JSX element, with the span every subtree question needs. */
-interface JsxElement {
-    /** Tag as written (`div`, `Button`, `Card.Header`); `''` for a fragment. */
-    readonly tag: string;
-    readonly attributes: JsxAttribute[];
-    readonly children: JsxElement[];
-    parent: JsxElement | null;
-    /** Offset of the opening `<`. */
-    readonly start: number;
-    /** Offset just past the opening tag's `>`. */
-    openEnd: number;
-    /** Offset just past the element's end (`/>` or `</tag>`). */
-    end: number;
-    /**
-     * Offset of the `{` of the nearest enclosing JSX expression container, or
-     * null at the top of a return/assignment. This is what scopes an empty state
-     * to its own conditional branch instead of to the whole page.
-     */
-    readonly containerStart: number | null;
-}
-/** Everything one pass over a file produces. */
-interface ScannedSource {
-    readonly text: string;
-    readonly segments: readonly SourceSegment[];
-    /** Every element, in document (open-tag) order. */
-    readonly elements: readonly JsxElement[];
-    /**
-     * `text` with every comment, string body and template body replaced by
-     * spaces, offsets preserved. Structural regexes (catch bodies, fetch calls)
-     * run over this so a `catch` inside a string can never be a finding.
-     */
-    readonly masked: string;
-}
-/** 1-based line/column for a byte offset. */
-interface SourcePosition {
-    readonly line: number;
-    readonly column: number;
-}
-/**
- * Lex one TS/TSX source.
- *
- * The loop keeps a frame stack. A code frame pops back to its JSX parent when
- * an unmatched `}` closes the expression container that opened it; a JSX tag
- * frame becomes a children frame at `>` and pops at `/>`.
- */
-declare function scanSource(text: string): ScannedSource;
-
-/**
- * Filesystem side of the gate: walk a product's source, lex each file once, and
- * hand every check the same `ScannedFile`.
- *
- * Test files are excluded by default and that exclusion is load-bearing, not
- * tidiness: a test fixture deliberately contains the copy and the shapes the
- * checks hunt for ("No results", a silent catch, the word `payload`), so
- * scanning tests would make the gate loudest exactly where nothing ships.
- */
-
-/** One file, lexed once, with its line index ready. */
-interface ScannedFile {
-    /** Absolute path as walked. */
-    readonly path: string;
-    /** Path as reported in findings — relative to cwd when it is inside it. */
-    readonly display: string;
-    readonly text: string;
-    readonly scan: ScannedSource;
-    readonly lineStarts: readonly number[];
-    positionAt(offset: number): SourcePosition;
-}
-/** Read and lex one file. Returns null when it cannot be read. */
-declare function scanFile(path: string): ScannedFile | null;
-/** Lex an in-memory source — the shape every check test uses. */
-declare function buildScannedFile(path: string, text: string): ScannedFile;
-/** Lex every scannable file under `srcDirs`. */
-declare function scanSources(srcDirs: readonly string[], ignore?: readonly string[]): ScannedFile[];
-
-/**
- * Check 1 — engineering vocabulary on screen.
- *
- * The defect: a word from the codebase reaches the reader. Shipped instances
- * include "materialized" inside a user-facing error, a column of `sourceKind`,
- * and a chip reading `undefined`. Nobody decided to say those words; they leaked
- * because the label and the field name were the same string.
- *
- * ── Precision over recall, deliberately ──────────────────────────────────────
- *
- * A vocabulary gate lives or dies on false positives: one bad report and the
- * check is disabled, after which it guards nothing. `grep -i artifact` over one
- * product's `apps/web/src` returns 11 hits, all of them imports, prop names or
- * doc comments — a checker that reports those is deleted in a week.
- *
- * So this check only reads positions the lexer PROVES are copy, in two tiers
- * that are ON by default:
- *
- *  1. JSX text — `<p>No artifact yet</p>`. Unambiguous.
- *  2. A JSX attribute value, when the attribute is in {@link COPY_KEYS}. An
- *     allowlist, so `className`, `data-*`, `aria-*`, `id`, `href` and every
- *     other internal attribute are excluded by construction rather than by a
- *     denylist that goes stale.
- *  3. The first argument of a call in {@link COPY_CALLS} — `toast.error('…')`,
- *     `new Error('…')`, `setError('…')`. This is the tier that catches the
- *     flagship defect: "materialization" reached a reader from a `new Error`
- *     in a server module, not from a component.
- *
- * And ONE tier that is off by default, `includeObjectCopy`:
- *
- *  4. A string or template filling an object key named in {@link COPY_KEYS}
- *     (`emptyTitle: '…'`, `description: '…'`).
- *
- * Tier 4 is off because it was MEASURED as the false-positive tier. Over two
- * production verticals it produced findings on a system prompt (`prompt:` in an
- * agent profile), an MCP tool description the model reads, and the body of a
- * legal document template where "Records" is a term of the drafted document —
- * none of them on any screen. A key named `description` is model-facing about
- * as often as it is reader-facing, and a checker that cannot tell them apart
- * must not be the one that fails the build. Products whose data modules really
- * do hold UI copy turn it on.
- *
- * Everything else — a bare string in code, an import specifier, a comment, an
- * identifier, a test file — is not read at all. The cost is real recall: copy
- * assembled through a variable (`const msg = base + suffix`) is invisible here,
- * and no lexer can see it. That is the trade this check makes on purpose.
- */
-
-/**
- * The default list. Every entry has shipped to a real screen in this fleet or
- * its verticals, and every one carries the sentence that replaces it — a gate
- * that only says "don't" leaves the author to guess.
- */
-declare const DEFAULT_BANNED_TERMS: readonly BannedTerm[];
-/**
- * Attributes and object keys whose string value is copy. An allowlist: an
- * attribute that is not here is never read, which is how `aria-label`,
- * `className`, `data-testid` and `href` stay out without being enumerated.
- */
-declare const COPY_KEYS: readonly string[];
-/** Calls whose first string argument reaches the reader. */
-declare const COPY_CALLS: readonly string[];
-
-/**
- * Check 4 — a failure the reader never learns about.
- *
- * The shape: a `catch` that clears a loading flag, or returns a fallback, and
- * tells nobody. The request failed; the screen renders the empty state. The
- * reader is shown "No documents yet" for a network error, believes the answer,
- * and acts on it. That is worse than an error message, because it is a
- * confident wrong answer rather than a visible problem.
- *
- * ── What passes ──────────────────────────────────────────────────────────────
- *
- * The handler surfaces the failure (an error/notice state setter, a toast, an
- * injected `onError`), or rethrows / rejects so a boundary above can. Anything
- * else — an empty body, `setLoading(false)`, `return []`, a lone
- * `console.error` — is a finding. `console.error` is deliberately NOT a sink:
- * it writes to a console the reader does not have.
- *
- * ── Precision ────────────────────────────────────────────────────────────────
- *
- * Only handlers around I/O are read. A `try { JSON.parse(raw) } catch { return
- * {} }` is a legitimate fallback over a value already in hand, and reporting it
- * is exactly the noise that gets a gate switched off — so a `try` block with no
- * `await`, no request call and no `.then` is skipped entirely. A `.catch(…)`
- * handler is always on a promise, so it needs no such test.
- *
- * Three narrowings were MEASURED against two production verticals, where the
- * unnarrowed check reported 52 handlers of which 14 were real (27%) — a rate
- * that gets a check deleted, not fixed:
- *
- *  1. Only modules that can reach a browser are read ({@link READERLESS_PATHS}).
- *     31 of the 52 sat in `.server/` service modules and resource routes, where
- *     the failure IS reported — to the operator's log — and the question of what
- *     the reader is told belongs to the caller that renders. This is the single
- *     largest noise class and it is a react-router CONVENTION, not a guess:
- *     `.server` modules are compiled out of the client bundle.
- *  2. A handler that RESTORES the prior value has surfaced the failure: the
- *     control the reader just moved visibly snaps back.
- *  3. A handler that RETURNS words — `return 'unknown'`, `new Response('Invalid
- *     JSON', …)` — hands a distinguishable outcome to a caller that renders it.
- *     Words inside a `console` call do not count, for the reason above.
- *
- * The cost is stated rather than hidden: narrowing 1 gives up the real
- * one-hop defect (a service returning `[]` on a network error, which a screen
- * then renders as "nothing here"). That is a caller-side finding this check
- * cannot see from the callee, and a product that wants it back passes
- * `readerlessPaths: []`.
- */
-
-/**
- * Paths whose modules cannot render. `.server` is react-router's server-only
- * convention (compiled out of the client bundle) and `routes/api.` its resource
- * -route naming; a `catch` in either reports to an operator, not to a reader.
- */
-declare const READERLESS_PATHS: readonly string[];
-
-/**
- * Check 5 — a capability with no door.
- *
- * Two deterministic engines shipped in this fleet with no way to reach them: a
- * contract redline that cites statutes, and a court-deadline calculator with 59
- * golden tests. Both correct, both routed, neither in the navigation and
- * neither linked from any screen. The only way to open them was to type the URL.
- * No test failed, because every test was about the engine.
- *
- * This check joins two things a product already has — its route table and its
- * navigation definition — and reports the routes that neither the navigation
- * nor any link in the source reaches.
- *
- * ── Matching, and why it is by STATIC SEGMENTS ───────────────────────────────
- *
- * Links are written against a base that is computed at runtime:
- *
- *     route('contracts/redline', …)   under   route(':workspaceId', …) under route('app', …)
- *     <Link to={`${base}/contracts/redline`}>            base = `/app/${workspaceId}`
- *
- * Comparing strings finds nothing. So both sides are reduced to their STATIC
- * segments — parameters and `${…}` holes drop out — and a link reaches a route
- * when the link's segments are a suffix of the route's:
- *
- *     route  app/:workspaceId/contracts/redline  →  [app, contracts, redline]
- *     link   `${base}/contracts/redline`         →  [contracts, redline]  ✓ suffix
- *     link   `${base}/contracts`                 →  [contracts]           ✗ (matches the parent, not this)
- *
- * The suffix rule is what makes the check usable without resolving `base`, and
- * the cost is a known blind spot: a detail route (`reviews/:id`) has the same
- * static segments as its list route, so a link to the list marks the detail
- * reachable. That is a missed defect, never a false alarm — the deliberate
- * direction for a gate that only survives if its reports are all real.
- *
- * ── Reachable FROM THE NAVIGATION, not merely linked ─────────────────────────
- *
- * A link is only a door if the screen holding it can itself be opened. The
- * shipped defect is an ISLAND: a contract list, a contract detail page and a
- * statute-citing redline engine, each linking the other two, and no navigation
- * entry pointing at any of them. Every route in it has an inbound link, so a
- * check that asks "does a link exist?" reports nothing at all — which is what
- * happened, and the redline shipped unreachable.
- *
- * So doors are resolved transitively from the navigation:
- *
- *   - a nav file's path literals are roots;
- *   - so is a link in a file that is NOT a route module (a shared component, a
- *     header, an index route) — it could be rendered anywhere, and assuming it
- *     is always available is the direction that removes findings rather than
- *     inventing them;
- *   - a link inside a ROUTE module counts only once that route is itself
- *     reachable, and the pass repeats to a fixpoint.
- *
- * An island therefore reports every route in it, which is right: one nav entry
- * clears them all, and naming only the entry route would hide how much shipped
- * behind it.
- *
- * ── What is not a screen ─────────────────────────────────────────────────────
- *
- * `index()` and `layout()` add no path of their own. A route whose module is
- * not `.tsx` is a resource endpoint (the react-router convention) and is
- * skipped by default, as is anything under `ignore` (default `api/*`).
- */
-
-/** One route as declared, with its composed path. */
-interface RouteEntry {
-    /** Full path from the root of the route table, no leading slash. */
-    readonly path: string;
-    /** The route module, when the declaration names one. */
-    readonly module: string | null;
-    /** Offset of the path literal in the route config, for file:line. */
-    readonly offset: number;
-    /**
-     * True when the declaration nests children. Such a route renders an Outlet
-     * shell; the destination is its index child, whose path is the same string.
-     * Asking a layout for its own door reports every product's `app` wrapper.
-     */
-    readonly isLayout: boolean;
-}
-/**
- * Parse a `@react-router/dev/routes` config into composed route paths.
- *
- * Nesting is read from offset containment rather than from a grammar: a call
- * whose parentheses sit inside another call's is that call's child, which is
- * true of `route(p, m, [ route(…) ])` and needs no array bookkeeping.
- */
-declare function parseRouteConfig(file: ScannedFile): RouteEntry[];
-/** The comparable segments of a path: statics only, params and holes dropped. */
-declare function staticSegments(path: string): string[];
-
 /**
  * `@tangle-network/agent-app/legibility` — the understandability gate a product
  * runs over its OWN source, in its OWN CI.
@@ -559,7 +33,15 @@ declare function staticSegments(path: string): string[];
  *
  * or, in CI, the bin: `agent-app-legibility-check --src src --routes src/routes.ts --nav src/components/sidebar.tsx`.
  */
-
+import { type LegibilityConfig, type LegibilityReport } from './types';
+export { LEGIBILITY_CHECKS } from './types';
+export type { BannedTerm, EmptyStateOptions, LegibilityCheckId, LegibilityConfig, LegibilityFinding, LegibilityReport, LegibilitySuppression, ReachabilityOptions, SilentFailureOptions, SuccessOptions, VocabularyOptions, } from './types';
+export { formatLegibilityReport, legibilityReportToJson, type FormatOptions } from './report';
+export { DEFAULT_BANNED_TERMS, COPY_KEYS, COPY_CALLS } from './checks/vocabulary';
+export { READERLESS_PATHS } from './checks/silent-failure';
+export { parseRouteConfig, staticSegments, type RouteEntry } from './checks/reachability';
+export { scanSources, scanFile, buildScannedFile, type ScannedFile } from './scan';
+export { scanSource, type JsxAttribute, type JsxElement, type ScannedSource, type SegmentKind, type SourceSegment, } from './source';
 /**
  * Run the gate over a product's source.
  *
@@ -567,6 +49,4 @@ declare function staticSegments(path: string): string[];
  * The bin decides what to do with the report; a product embedding this in its
  * own tooling decides something else.
  */
-declare function checkLegibility(config: LegibilityConfig): LegibilityReport;
-
-export { type BannedTerm, COPY_CALLS, COPY_KEYS, DEFAULT_BANNED_TERMS, type EmptyStateOptions, type FormatOptions, type JsxAttribute, type JsxElement, LEGIBILITY_CHECKS, type LegibilityCheckId, type LegibilityConfig, type LegibilityFinding, type LegibilityReport, type LegibilitySuppression, READERLESS_PATHS, type ReachabilityOptions, type RouteEntry, type ScannedFile, type ScannedSource, type SegmentKind, type SilentFailureOptions, type SourceSegment, type SuccessOptions, type VocabularyOptions, buildScannedFile, checkLegibility, formatLegibilityReport, legibilityReportToJson, parseRouteConfig, scanFile, scanSource, scanSources, staticSegments };
+export declare function checkLegibility(config: LegibilityConfig): LegibilityReport;

package/dist/legibility/report.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The report a product reads in its CI log.
+ *
+ * A gate is only as good as the sentence a developer reads at 6pm with a red
+ * build. So every finding prints three things and never fewer: WHERE
+ * (`file:line:col`, clickable in every terminal and editor), WHAT is wrong in
+ * the reader's terms, and WHAT TO DO about it. A finding without a remedy is a
+ * complaint, and complaints get suppressed rather than fixed.
+ *
+ * Honoured suppressions are counted in the summary and listed on request. A
+ * suppression that nobody can see is a disabled check with extra steps.
+ */
+import { type LegibilityReport } from './types';
+export interface FormatOptions {
+    /** Print every honoured suppression with its reason. */
+    readonly listSuppressions?: boolean;
+    /** Wrap check names in ANSI colour. Off by default — CI logs keep the bytes. */
+    readonly colour?: boolean;
+}
+export declare function formatLegibilityReport(report: LegibilityReport, options?: FormatOptions): string;
+/** The machine-readable form, for a product that posts findings somewhere. */
+export declare function legibilityReportToJson(report: LegibilityReport): string;

package/dist/legibility/scan.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Filesystem side of the gate: walk a product's source, lex each file once, and
+ * hand every check the same `ScannedFile`.
+ *
+ * Test files are excluded by default and that exclusion is load-bearing, not
+ * tidiness: a test fixture deliberately contains the copy and the shapes the
+ * checks hunt for ("No results", a silent catch, the word `payload`), so
+ * scanning tests would make the gate loudest exactly where nothing ships.
+ */
+import { type ScannedSource, type SourcePosition } from './source';
+/** One file, lexed once, with its line index ready. */
+export interface ScannedFile {
+    /** Absolute path as walked. */
+    readonly path: string;
+    /** Path as reported in findings — relative to cwd when it is inside it. */
+    readonly display: string;
+    readonly text: string;
+    readonly scan: ScannedSource;
+    readonly lineStarts: readonly number[];
+    positionAt(offset: number): SourcePosition;
+}
+/** Read and lex one file. Returns null when it cannot be read. */
+export declare function scanFile(path: string): ScannedFile | null;
+/** Lex an in-memory source — the shape every check test uses. */
+export declare function buildScannedFile(path: string, text: string): ScannedFile;
+/** Lex every scannable file under `srcDirs`. */
+export declare function scanSources(srcDirs: readonly string[], ignore?: readonly string[]): ScannedFile[];
+/** One readable line of evidence: collapsed whitespace, clipped. */
+export declare function evidenceOf(text: string, start: number, end: number, max?: number): string;