uidex 0.7.0 → 0.9.0

package/dist/scan/index.d.ts

@@ -12,6 +12,32 @@ interface EntityRef {
     kind: EntityKind;
     id: string;
 }
+/**
+ * The four kinds every captured route is expected to render — the state-matrix
+ * axis. A capture that only shoots the happy path leaves most of the value on
+ * the table, so a missing core kind must be captured, waived (the page CANNOT
+ * render it), or acknowledged in the MISSING_KINDS baseline.
+ */
+declare const CORE_STATE_KINDS: readonly ["loading", "empty", "populated", "error"];
+type CoreStateKind = (typeof CORE_STATE_KINDS)[number];
+/** `variant` is any state outside the matrix (a dialog, wizard step, multi-currency…). */
+type StateKind = CoreStateKind | "variant";
+/**
+ * A declared render state of an entity — the "story"-like unit: a named
+ * condition the page/feature/widget can render in (loading / empty / error /
+ * multi-currency / …). Enumerated on the entity (not derived from syntax), it
+ * is the contract the visual-states capture must satisfy and the anchor for
+ * per-state acceptance criteria. Fixtures + capture mechanics stay in the spec;
+ * the registry holds only the name (+ optional kind / per-state acceptance).
+ */
+interface StateDecl {
+    name: string;
+    /** Canonical kind for the state-matrix axis (defaults to `variant`). */
+    kind?: StateKind;
+    /** Acceptance criteria that only this state can evidence. */
+    acceptance?: string[];
+    description?: string;
+}
 interface Metadata {
     name?: string;
     description?: string;
@@ -21,6 +47,21 @@ interface Metadata {
     flows?: readonly string[];
     features?: string[];
     widgets?: string[];
+    /** Declared render states (see StateDecl); the capture-completeness gate. */
+    states?: StateDecl[];
+    /**
+     * `false` opts this page/feature/widget out of visual-states capture forever
+     * (a redirect, a static notice, an internal target). The page-coverage gate
+     * treats an opted-out route as accounted-for. Reason belongs in `description`.
+     */
+    capture?: boolean;
+    /**
+     * Per-core-kind waivers: a core kind this page's route legitimately CANNOT
+     * render (a create form has no `empty`), mapped to a substantive reason. The
+     * state-matrix gate treats a waived kind as accounted-for. A waiver is a
+     * permanent design statement — unlike MISSING_KINDS backlog, which is debt.
+     */
+    waivers?: Partial<Record<CoreStateKind, string>>;
 }
 interface EntityWithMetaBase {
     id: string;
@@ -66,6 +107,7 @@ type Entity = Route | Page | Feature | Widget | Region | Element | Primitive | F
 type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
+type MetaEntityKind = Exclude<EntityKind, "route" | "flow">;
 
 interface ReportRecord {
     id: string;
@@ -111,7 +153,18 @@ interface SourceConfig {
 interface ConventionsConfig {
     primitives?: string[] | false;
     features?: string | false;
-    pages?: "auto" | false;
+    /**
+     * How Page entities are derived from route files.
+     *   - `"auto"` (default): infer the route root from the `app`/`pages`/
+     *     `routes` directory-name heuristic.
+     *   - `{ routesDir }`: the route root is exactly this dir (relative to the
+     *     config dir), detected with the TanStack / React Router `routes/`-style
+     *     convention. Use for a custom TanStack `routesDirectory`.
+     *   - `false`: do not derive pages from routes.
+     */
+    pages?: "auto" | false | {
+        routesDir: string;
+    };
     flows?: string[] | false;
     regions?: "landmarks" | false;
 }
@@ -119,6 +172,12 @@ interface AuditConfig {
     scopeLeak?: boolean;
     coverage?: boolean;
     acceptance?: boolean;
+    /** State-capture completeness gate (default on when a manifest is present). */
+    states?: boolean;
+    /** Page-capture coverage gate (default on when a manifest is present). */
+    pageCoverage?: boolean;
+    /** State-matrix (core-kind) gate (default on when a manifest is present). */
+    stateMatrix?: boolean;
 }
 interface UidexConfig {
     $schema?: string;
@@ -128,6 +187,18 @@ interface UidexConfig {
     flows?: string[];
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
+    /**
+     * Path (relative to the config dir) of the captured-states manifest the
+     * Playwright states reporter writes. The completeness gate reads it when
+     * present. Defaults to `uidex-states.json`.
+     */
+    statesManifest?: string;
+    /**
+     * Path (relative to the config dir) of the page-coverage baseline — the
+     * tool-managed, shrink-only backlog written by `uidex scan --update-baseline`.
+     * Defaults to `uidex-coverage-baseline.json`.
+     */
+    coverageBaseline?: string;
 }
 interface DiscoveredConfig {
     configPath: string;
@@ -186,6 +257,26 @@ interface MetadataExport {
     featureSpans?: Span[];
     /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
     widgetSpans?: Span[];
+    /** Declared render states (page/feature/widget); see ParsedState. */
+    states?: ParsedState[];
+    /** `capture: false` opts the entity out of the page-coverage gate. */
+    capture?: boolean;
+    /** Per-core-kind waivers: kind → reason the route cannot render it. */
+    waivers?: Record<string, string>;
+}
+/**
+ * A parsed `states` entry from `export const uidex`. The authored form is a
+ * string (bare name) or an object `{ name, acceptance?, description? }`; both
+ * normalize to this. `nameSpan` powers a future `uidex rename state`.
+ */
+interface ParsedState {
+    name: string;
+    /** Canonical kind: loading | empty | populated | error | variant. */
+    kind?: string;
+    acceptance?: string[];
+    description?: string;
+    /** Span of the state's name string literal. */
+    nameSpan?: Span;
 }
 /** A data-uidex* attribute whose value the scanner could not resolve. */
 interface DynamicAttrFact {
@@ -383,6 +474,83 @@ interface ResolveOutput {
  */
 declare function resolve(ctx: ResolveContext): ResolveOutput;
 
+/**
+ * State-capture completeness — the deterministic replacement for a bespoke
+ * `check-states.mjs`. Cross-checks the states DECLARED on registry entities
+ * (`export const uidex = { states: [...] }`) against the states a capture run
+ * actually produced (a `uidex-states.json` manifest written by the Playwright
+ * states reporter):
+ *
+ *   - `missing-state-capture` — a declared state no run captured. The gap the
+ *     acceptance-grounded analysis surfaces (a promised behavior with no pixel
+ *     evidence) becomes a mechanical audit failure.
+ *   - `orphan-state-capture` — a run captured a state the entity never declared,
+ *     so the contact sheet shows a state the registry doesn't know about.
+ *
+ * Pure: same (registry, manifest) → same diagnostics. Only runs when a manifest
+ * is present, so a plain `uidex scan` (no capture run) never fails on it.
+ */
+/** One `entity/state` a capture run recorded. */
+interface CapturedState {
+    /** Registry entity id the capture rendered (e.g. "products"). */
+    entity: string;
+    /** Entity kind, when the capture recorded it (page/feature/widget). */
+    kind?: MetaEntityKind;
+    /** The declared state name captured (e.g. "new-filled"). */
+    state: string;
+    /** Canonical matrix kind (loading/empty/populated/error/variant). */
+    stateKind?: string;
+    /** URL pathname the capture ran against (page-coverage gate matches it to a route). */
+    url?: string;
+    /** Explicit route pattern the capture covers, when supplied. */
+    route?: string;
+}
+interface CapturedStatesManifest {
+    captured: CapturedState[];
+}
+declare function checkStateCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
+
+/**
+ * Page-capture coverage — the coarse gate above the per-state gate. Every
+ * derived route must be accounted for: captured (a run drove it), opted out
+ * (`export const uidex = { page, capture: false }`), or acknowledged backlog (a
+ * tool-managed, shrink-only baseline). A route in none of those is a *new*
+ * uncaptured page and fails hard — the ratchet that keeps debt from growing.
+ *
+ * uidex derives the route set (route groups stripped, dynamic segments kept), so
+ * unlike a hand-rolled `src/app/**` walk there is no page list to enumerate or
+ * keep from rotting: a route exists in the registry or it doesn't. And captures
+ * observe the URL they ran against, so which route a capture covers is matched,
+ * never hand-declared.
+ */
+/** The committed, tool-managed backlog. Shrinks as pages/kinds get captured. */
+interface PageCoverageBaseline {
+    /** Route patterns acknowledged as uncaptured (e.g. "/[scope]/collections"). */
+    uncapturedPages: string[];
+    /** route → core kinds acknowledged as not-yet-captured (the matrix backlog). */
+    missingKinds?: Record<string, string[]>;
+}
+/**
+ * Turn a Next-style route pattern into an anchored matcher.
+ *   `/[scope]/products/[productId]/edit` → matches `/acme/products/p1/edit`
+ *   `/[...slug]` (catch-all) → matches one or more segments
+ * Returns the literal-segment count as a specificity score, so the most literal
+ * matching pattern wins when several match (e.g. `/x/new` beats `/x/[id]`).
+ */
+declare function compileRoute(pattern: string): {
+    test: (url: string) => boolean;
+    specificity: number;
+};
+/** The route pattern (from the given set) that most-specifically matches a URL. */
+declare function matchUrlToRoute(url: string, routePaths: string[]): string | null;
+declare function checkPageCoverage(registry: Registry, manifest: CapturedStatesManifest, baseline?: PageCoverageBaseline): Diagnostic[];
+/**
+ * Compute the shrink-only baseline for `--update-baseline`: every route with no
+ * capture and no opt-out. Seeds on first run and prunes on later runs; growth
+ * only ever happens through this explicit command, visible in the file's diff.
+ */
+declare function computePageBaseline(registry: Registry, manifest: CapturedStatesManifest): PageCoverageBaseline;
+
 interface AuditOptions {
     registry: Registry;
     extracted: ExtractedFile[];
@@ -393,12 +561,28 @@ interface AuditOptions {
     check?: boolean;
     lint?: boolean;
     resolveDiagnostics?: Diagnostic[];
-    /** Freshly-emitted gen-file bytes, required for --check. */
+    /** Freshly-emitted DATA-file bytes (the entity array), required for --check. */
     generated?: string;
-    /** On-disk contents of the gen file at scan time; `null` if the file does not exist. */
+    /** On-disk contents of the data file at scan time; `null` if it does not exist. */
     existingOnDisk?: string | null;
-    /** Relative path of the configured `output` file; used in diagnostics. */
+    /** Relative path of the data file; used in diagnostics. */
     outputPath?: string;
+    /** Freshly-emitted TYPES-file bytes; enables the types-file --check compare. */
+    typesGenerated?: string;
+    /** On-disk contents of the types file at scan time; `null` if it does not exist. */
+    typesOnDisk?: string | null;
+    /** Relative path of the configured `output` (types) file; used in diagnostics. */
+    typesOutputPath?: string;
+    /** Freshly-emitted LOCS-file bytes; enables the locs-file --check compare. */
+    locsGenerated?: string;
+    /** On-disk contents of the locs file at scan time; `null` if it does not exist. */
+    locsOnDisk?: string | null;
+    /** Relative path of the `.locs` file; used in diagnostics. */
+    locsOutputPath?: string;
+    /** Captured-states manifest for the completeness gate; absent → gate skipped. */
+    capturedStates?: CapturedStatesManifest;
+    /** Page-coverage baseline (the shrink-only backlog); absent → empty baseline. */
+    pageBaseline?: PageCoverageBaseline;
 }
 declare function audit(opts: AuditOptions): AuditSummary;
 
@@ -408,16 +592,56 @@ interface EmitOptions {
     /** The import source for `createUidex` in the generated preconfigured export. */
     uidexImport?: string;
 }
-declare function emit(opts: EmitOptions): string;
+/**
+ * The scanner emits THREE artifacts, split by consumer:
+ *
+ * - `types` — the id unions + the `Uidex` authoring-shape namespace. Pure types,
+ *   no runtime, no `@ts-nocheck`. This is the file the ~dozens of
+ *   `import type { Uidex } from "@/uidex.gen"` sites resolve, so it must stay
+ *   small: an `import type` still forces tsc/tsserver to fully parse the target
+ *   module, so keeping the runtime entity data out of it is what keeps the editor
+ *   and type-checker responsive across every consumer file.
+ * - `data` — the AUTHORED registry (route/page/feature/widget/primitive/flow) +
+ *   `gitContext` + `loadRegistry` + the preconfigured `uidex` instance. Runtime,
+ *   `@ts-nocheck`. Loaded eagerly by the devtools on mount.
+ * - `locs` — the thin element/region `{ id, loc }` entities, emitted as positional
+ *   tuples (see `emitLocsModule`). Loaded lazily by the devtools (idle / first
+ *   inspect) via `loadLocs`, so ~90% of the entity count stays out of the initial
+ *   devtools chunk.
+ */
+interface EmitResult {
+    types: string;
+    /** Authored-metadata registry (pages/features/widgets/flows/…). */
+    data: string;
+    /** Deferred `id → loc` module for the thin element/region entities. */
+    locs: string;
+}
+declare function emit(opts: EmitOptions): EmitResult;
 
 /**
  * Detect framework-aware routes:
  *   - Next.js App Router:    `**\/app/**\/page.tsx` -> `/segments`
  *   - Next.js Pages Router:  `**\/pages/**\/*.tsx`  -> `/segments` (excludes _app, _document, api/)
- *   - Vite + React Router / TanStack Router:
- *                            `**\/routes/**\/*.tsx` -> `/segments`
+ *   - Vite + TanStack Router / React Router: `**\/routes/**\/*.tsx` -> `/segments`.
+ *     Honors TanStack conventions: pathless layouts (`_layout`) and route
+ *     groups (`(group)`) drop from the path, the folder route file
+ *     (`route.tsx`) collapses like `index`, `-`-prefixed and `api/` files are
+ *     excluded, and flat dot-notation filenames (`a.b.$c.tsx`) split into
+ *     nested segments. Dynamic segments are normalized to the canonical
+ *     `[param]` form used everywhere else in the pipeline: `$id` -> `[id]`,
+ *     the splat `$` -> `[...splat]`, and `[.]`-escaped literals are unwrapped.
  */
-declare function detectRoutes(files: ScannedFile[]): DetectedRoute[];
+interface DetectRoutesOptions {
+    /**
+     * Explicit routes root, as it appears in `displayPath` (relative to the
+     * config dir). When set, only files under this dir are routes and the
+     * TanStack / React Router `routes/`-style convention is applied — overriding
+     * the `app`/`pages`/`routes` directory-name heuristic. Use for a custom
+     * TanStack `routesDirectory`.
+     */
+    routesDir?: string;
+}
+declare function detectRoutes(files: ScannedFile[], options?: DetectRoutesOptions): DetectedRoute[];
 declare function pathToId(routePath: string): string;
 
 interface GitResolveOptions {
@@ -462,6 +686,20 @@ interface RunScanOptions {
     check?: boolean;
     lint?: boolean;
     configs?: DiscoveredConfig[];
+    /** Captured-states manifest for the completeness gate; overrides on-disk load. */
+    capturedStates?: CapturedStatesManifest;
+    /** Page-coverage baseline; overrides on-disk load. */
+    pageBaseline?: PageCoverageBaseline;
+}
+/** Load the page-coverage baseline from disk, if present + well-formed. */
+declare function loadPageBaseline(configDir: string, config: UidexConfig): PageCoverageBaseline | undefined;
+/** One generated artifact: its bytes plus where it lands (abs + repo-relative). */
+interface ScanArtifact {
+    generated: string;
+    /** Absolute path on disk. */
+    outputPath: string;
+    /** Path relative to the config dir, for diagnostics. */
+    outputRel: string;
 }
 interface ScanResult {
     config: UidexConfig;
@@ -469,11 +707,50 @@ interface ScanResult {
     registry: Registry;
     gitContext: GitContext;
     audit?: AuditSummary;
-    generated: string;
-    outputPath: string;
+    /** Pure-types artifact (`config.output`, e.g. `uidex.gen.ts`). */
+    types: ScanArtifact;
+    /** Authored-registry artifact (the sibling `.data` module). */
+    data: ScanArtifact;
+    /** Deferred element/region source-location artifact (the sibling `.locs` module). */
+    locs: ScanArtifact;
+    /** The captured-states manifest in effect this run, if any (for --update-baseline). */
+    capturedStates?: CapturedStatesManifest;
 }
 declare function runScan(opts?: RunScanOptions): ScanResult[];
-declare function writeScanResult(result: ScanResult): void;
+/**
+ * Write all three generated artifacts (types + data + locs), each only if
+ * changed. Splitting them means a change confined to one (e.g. adding an element
+ * only touches `.locs`) never rewrites the others, so watchers recompile only what
+ * actually moved. Returns `true` if any file was written.
+ */
+declare function writeScanResult(result: ScanResult): boolean;
+/** Absolute path of the page-coverage baseline for a scan result. */
+declare function pageBaselinePath(result: ScanResult): string;
+
+/**
+ * State-matrix coverage — the second completeness axis. A capture that only ever
+ * shoots the happy path leaves most of the harness's value on the table, so
+ * every *captured* route must render each of the four core kinds
+ * (loading / empty / populated / error), or account for the gap:
+ *
+ *   - a **waiver** (`export const uidex = { page, waivers: { empty: "…" } }`) —
+ *     the route CANNOT render that kind (a create form has no empty state);
+ *   - the **MISSING_KINDS baseline** — the route CAN render it and nobody has
+ *     captured it yet (a per-(route, kind) shrink-only backlog).
+ *
+ * Anything else is a `core-kind` error. Only *captured* routes are in scope: a
+ * route with no capture at all is a page-coverage concern, not a matrix hole.
+ */
+/** route → core kinds acknowledged as not-yet-captured (the finer ratchet). */
+interface StateMatrixBaseline {
+    missingKinds: Record<string, string[]>;
+}
+declare function checkStateMatrix(registry: Registry, manifest: CapturedStatesManifest, baseline?: StateMatrixBaseline): Diagnostic[];
+/**
+ * Compute the shrink-only MISSING_KINDS baseline for `--update-baseline`: every
+ * (captured route, core kind) that is neither captured nor waived.
+ */
+declare function computeMissingKinds(registry: Registry, manifest: CapturedStatesManifest): Record<string, string[]>;
 
 /**
  * Applies the machine-generated fixes attached to diagnostics.
@@ -563,12 +840,26 @@ declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conven
  * bootstrapping before the first scan).
  */
 declare namespace Uidex {
+    type CoreStateKind = "loading" | "empty" | "populated" | "error";
+    type StateKind = CoreStateKind | "variant";
+    /** A declared render state, as authored in `states: [{ name, ... }]`. */
+    interface State {
+        name: string;
+        kind?: StateKind;
+        acceptance?: readonly string[];
+        description?: string;
+    }
+    /** Per-core-kind waivers: a kind this route cannot render → reason. */
+    type Waivers = Partial<Record<CoreStateKind, string>>;
     interface Page<PageIds extends string = string, FeatureIds extends string = string, WidgetIds extends string = string> {
         page: PageIds | false;
         name?: string;
         features?: readonly FeatureIds[];
         widgets?: readonly WidgetIds[];
         acceptance?: readonly string[];
+        states?: readonly (string | State)[];
+        capture?: boolean;
+        waivers?: Waivers;
         description?: string;
     }
     interface Feature<FeatureIds extends string = string> {
@@ -576,6 +867,7 @@ declare namespace Uidex {
         name?: string;
         features?: readonly FeatureIds[];
         acceptance?: readonly string[];
+        states?: readonly (string | State)[];
         description?: string;
     }
     interface Primitive<PrimitiveIds extends string = string> {
@@ -587,6 +879,7 @@ declare namespace Uidex {
         widget: WidgetIds;
         name?: string;
         acceptance?: readonly string[];
+        states?: readonly (string | State)[];
         description?: string;
     }
     interface Flow<FlowIds extends string = string> {
@@ -599,4 +892,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MetadataExport, type MetadataExportKind, type RenameKind, type RenameOptions, type RenameResult, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, Uidex, type UidexConfig, applyFixes, audit, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, parseConfig, pathToId, renameEntity, resolve, resolveGitContext, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+export { type Annotation, type AnnotationKind, type AppliedFix, type ApplyFixesResult, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CapturedState, type CapturedStatesManifest, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MetadataExport, type MetadataExportKind, type PageCoverageBaseline, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateMatrixBaseline, Uidex, type UidexConfig, applyFixes, audit, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMissingKinds, computePageBaseline, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, loadPageBaseline, matchUrlToRoute, pageBaselinePath, parseConfig, pathToId, renameEntity, resolve, resolveGitContext, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };