uidex 0.10.0 → 0.11.1

package/dist/scan/index.d.cts

@@ -34,19 +34,39 @@ 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[];
+    /**
+     * Acceptance criteria that only this state can evidence. Normalized into the
+     * same `{ id, rev, text }` regime as entity-level `acceptance` (one
+     * criterion-id namespace per entity), so per-state criteria are claimable by
+     * `uidexCovers` and visible to every acceptance gate.
+     */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
 }
+/**
+ * A normalized acceptance criterion. Authored either as a bare string (sugar:
+ * `id` is a deterministic kebab slug of the text, `rev` is 1) or as an object
+ * `{ id, rev?, text }`; parse-time normalization means everything downstream —
+ * audit, scaffold, the devtools — always sees this object shape. `rev` is the
+ * pin flows cover against (`uidexCovers("entity", "id@rev")`): bumping it when
+ * the criterion's meaning changes is what makes outdated-coverage detectable.
+ */
+interface AcceptanceCriterion {
+    id: string;
+    rev: number;
+    text: string;
+}
 interface Metadata {
     name?: string;
     description?: string;
-    acceptance?: string[];
+    acceptance?: AcceptanceCriterion[];
     notes?: string;
     composes?: EntityRef[];
     flows?: readonly string[];
     features?: string[];
     widgets?: string[];
+    /** Page ids a feature declares it must be mounted on (feature kind only). */
+    surfaces?: string[];
     /** Declared render states (see StateDecl); the capture-completeness gate. */
     states?: StateDecl[];
     /**
@@ -84,12 +104,25 @@ interface FlowStep {
     entityId: string;
     action?: string;
 }
+/**
+ * A per-criterion coverage claim a flow makes via
+ * `uidexCovers("<entityId>", "<criterionId>@<rev>")`. The rev is REQUIRED at
+ * the claim site — a rev-less claim could never go stale, which would defeat
+ * the outdated-detection the pin exists for.
+ */
+interface FlowCover {
+    entity: string;
+    criterion: string;
+    rev: number;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
     steps: FlowStep[];
+    /** Acceptance-criterion coverage claims made inside this flow's describe. */
+    covers?: FlowCover[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -178,6 +211,14 @@ interface AuditConfig {
     scopeLeak?: boolean;
     coverage?: boolean;
     acceptance?: boolean;
+    /** Feature `surfaces` mount verification (default on; only fires when a feature declares `surfaces`). */
+    surfaces?: boolean;
+    /**
+     * Require every feature to declare at least one acceptance criterion
+     * (default ON — a bare `uidex.feature.ts` is a warning, escalatable to
+     * error via `severity` or disabled with `requireAcceptance: false`).
+     */
+    requireAcceptance?: 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). */
@@ -194,12 +235,22 @@ interface AuditConfig {
      */
     severity?: Record<string, DiagnosticSeverity | "off">;
 }
+/** Declared module-resolution hints for the import-graph checks. */
+interface ResolveConfig {
+    /**
+     * Specifier-prefix → config-dir-relative path-prefix aliases
+     * (e.g. `{ "@/": "src/" }`). Longest matching prefix wins. When declared,
+     * these replace the scanner's zero-config `@/` / `~/` → `src/` fallback.
+     */
+    aliases: Record<string, string>;
+}
 interface UidexConfig {
     $schema?: string;
     sources: SourceConfig[];
     exclude?: string[];
     output: string;
     flows?: string[];
+    resolve?: ResolveConfig;
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
     /**
@@ -263,7 +314,8 @@ interface MetadataExport {
     kind: MetadataExportKind;
     id: string | false;
     name?: string;
-    acceptance?: string[];
+    /** Entity-level criteria, normalized at parse time (string sugar → object). */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
     features?: string[];
     widgets?: string[];
@@ -288,17 +340,14 @@ interface MetadataExport {
     featureSpans?: Span[];
     /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
     widgetSpans?: Span[];
+    /** Declared surface page ids (feature kind only). */
+    surfaces?: string[];
+    /** Spans of the string-literal items in `surfaces`, parallel to `surfaces`. */
+    surfaceSpans?: Span[];
     /** Declared render states (page/feature/widget); see ParsedState. */
     states?: ParsedState[];
     /** Scope (`"*"` | core kind) → typed acknowledgment. See `acknowledge.ts`. */
     acknowledge?: Record<string, ParsedAcknowledgment>;
-    /**
-     * REMOVED fields, parsed only so the `acknowledge` codemod can rewrite them.
-     * No gate reads these — an unmigrated declaration is an error with a fix
-     * attached, never a silently different meaning.
-     */
-    legacyCapture?: boolean;
-    legacyWaivers?: Record<string, string>;
 }
 /** A parsed `acknowledge` entry from `export const uidex`. */
 interface ParsedAcknowledgment {
@@ -314,7 +363,8 @@ interface ParsedState {
     name: string;
     /** Canonical kind: loading | empty | populated | error | variant. */
     kind?: string;
-    acceptance?: string[];
+    /** Per-state criteria, normalized like entity-level `acceptance`. */
+    acceptance?: AcceptanceCriterion[];
     description?: string;
     /** Span of the state's name string literal. */
     nameSpan?: Span;
@@ -331,16 +381,23 @@ interface LandmarkFact {
     tag: string;
     line: number;
 }
-/** A static import binding (import / export-from), for the scope-leak check. */
+/** An import binding (import / export-from / dynamic `import()`). */
 interface ImportFact {
     specifier: string;
     line: number;
-    /** span of the whole import/export statement */
+    /** span of the whole import/export statement (or the import() expression) */
     span: Span;
     /** `import type` or an export-from with type-only kind */
     isTypeOnly: boolean;
     /** imported local binding names (default + named + namespace) */
     names: string[];
+    /**
+     * A dynamic `import("literal")` expression. Dynamic facts are real runtime
+     * edges (React.lazy is a mount edge) so the surfaces reach-check uses them,
+     * but the scope-leak check skips them — it is about static module
+     * dependency structure, which a dynamic import doesn't declare.
+     */
+    dynamic?: true;
 }
 /** An interactive host element (`button`, `a`, …) with no data-uidex* attribute. */
 interface InteractiveElementFact {
@@ -367,6 +424,18 @@ interface FlowCallFact {
 interface DynamicFlowCallFact {
     line: number;
 }
+/**
+ * A parsed `uidexCovers("<entityId>", "<criterionId>@<rev>")` claim inside a
+ * tagged flow describe. The rev is REQUIRED at the claim site (parse
+ * diagnostic `covers-missing-rev` otherwise) — rev-pinning is what makes
+ * outdated-coverage detection possible.
+ */
+interface FlowCoverFact {
+    entity: string;
+    criterion: string;
+    rev: number;
+    line: number;
+}
 /** A tagged `test.describe(..., { tag: "@uidex:flow" }, ...)` occurrence. */
 interface FlowFact {
     title: string;
@@ -374,6 +443,8 @@ interface FlowFact {
     calls: FlowCallFact[];
     /** uidex() calls inside this describe whose ids could not be resolved */
     dynamicCalls?: DynamicFlowCallFact[];
+    /** uidexCovers() acceptance-coverage claims inside this describe */
+    covers?: FlowCoverFact[];
 }
 interface ExtractedFile {
     file: ScannedFile;
@@ -381,6 +452,8 @@ interface ExtractedFile {
     metadata?: MetadataExport[];
     diagnostics?: Diagnostic[];
     flows?: FlowFact[];
+    /** true when the file contains any JSX element or fragment */
+    hasJsx?: boolean;
     dynamicAttrs?: DynamicAttrFact[];
     unannotatedInteractive?: InteractiveElementFact[];
     landmarks?: LandmarkFact[];
@@ -589,11 +662,6 @@ interface CoverageBaseline {
     /** route pattern → scope → acknowledgment (always `type: "backlog"`). */
     acknowledge: Record<string, AcknowledgeMap>;
 }
-/** The pre-`acknowledge` baseline shape, recognized only to migrate it. */
-interface LegacyCoverageBaseline {
-    uncapturedPages?: string[];
-    missingKinds?: Record<string, string[]>;
-}
 /**
  * The acknowledgments in force for one ROUTE: the baseline's entry for the route
  * layered UNDER the page's own `acknowledge`. Source wins — a human statement
@@ -614,10 +682,6 @@ declare function entityAcknowledge(meta: Metadata | undefined, capturedElsewhere
  * re-appears as an unacknowledged gap the gate reports.
  */
 declare function parseCoverageBaseline(raw: unknown): CoverageBaseline | null;
-/** Whether a parsed baseline JSON is the pre-`acknowledge` shape. */
-declare function isLegacyBaseline(raw: unknown): raw is LegacyCoverageBaseline;
-/** Convert the pre-`acknowledge` baseline shape to v2. Pure; no I/O. */
-declare function migrateBaseline(legacy: LegacyCoverageBaseline): CoverageBaseline;
 /** Serialize a baseline with stable key order, so its diff is reviewable. */
 declare function serializeCoverageBaseline(baseline: CoverageBaseline): string;
 
@@ -757,8 +821,6 @@ interface AuditOptions {
     capturedStates?: CapturedStatesManifest;
     /** Coverage baseline (the shrink-only `acknowledge` backlog). */
     coverageBaseline?: CoverageBaseline;
-    /** Migration diagnostic when the baseline on disk is the removed shape. */
-    baselineDiagnostic?: Diagnostic;
     /** The resolved workspace; enables `captured-elsewhere`. */
     workspace?: Workspace;
 }
@@ -871,17 +933,8 @@ interface RunScanOptions {
     /** Workspace override; skips auto-detection (used by tests). */
     workspace?: Workspace;
 }
-interface LoadedBaseline {
-    baseline?: CoverageBaseline;
-    /** Present when the file on disk is the pre-`acknowledge` shape. */
-    legacy?: Diagnostic;
-}
-/**
- * Load the coverage baseline from disk. A file in the REMOVED shape does not
- * silently read as "no baseline" — that would turn every acknowledged-backlog
- * route into a hard error — it comes back as a migration diagnostic with a fix.
- */
-declare function loadCoverageBaseline(configDir: string, config: UidexConfig): LoadedBaseline;
+/** Load the coverage baseline from disk, if present + well-formed. */
+declare function loadCoverageBaseline(configDir: string, config: UidexConfig): CoverageBaseline | undefined;
 /** One generated artifact: its bytes plus where it lands (abs + repo-relative). */
 interface ScanArtifact {
     generated: string;
@@ -963,24 +1016,6 @@ declare function computeMatrixBacklog(registry: Registry, manifest: CapturedStat
 
 declare function checkComponentCoverage(registry: Registry, manifest: CapturedStatesManifest): Diagnostic[];
 
-/**
- * Migration diagnostics for one file's `export const uidex` blocks. Emitted as
- * errors: the fields are gone, so the declaration means nothing until rewritten.
- */
-declare function migrateLegacyFields(ef: ExtractedFile): Diagnostic[];
-/**
- * Migration diagnostic for a pre-`acknowledge` coverage baseline. The whole file
- * is replaced, which is safe because the baseline is a generated artifact: the
- * same content `--update-baseline` would produce, just without needing a capture
- * run to regenerate it.
- */
-declare function migrateLegacyBaseline(opts: {
-    path: string;
-    raw: string;
-    parsed: unknown;
-    displayPath: string;
-}): Diagnostic | undefined;
-
 /**
  * Fold a PARTIAL capture manifest into the committed one.
  *
@@ -1013,10 +1048,12 @@ declare class ConfigError extends Error {
  * validates against, so a typo'd key fails loudly instead of silently leaving
  * the gate it was meant to govern at its default severity.
  *
- * Keep in sync when adding a diagnostic; `severity-codes.test.ts` asserts this
- * set matches the codes actually emitted by the source.
+ * Keep in sync when adding a diagnostic; `tests/scan/severity-codes.test.ts`
+ * asserts this set matches the codes actually emitted by the source — a code
+ * missing here cannot be softened/disabled by any repo (validateConfig
+ * rejects unknown `audit.severity` keys).
  */
-declare const DIAGNOSTIC_CODES: readonly ["acceptance-uncovered", "acknowledged-elsewhere", "competing-uidex-export", "component-state-uncaptured", "core-kind", "duplicate-id", "dynamic-attr", "dynamic-flow-reference", "gen-missing", "gen-stale", "legacy-acknowledge-field", "legacy-coverage-baseline", "matrix-backlog", "missing-element-annotation", "missing-state-capture", "orphan-state-capture", "page-backlog", "page-captured", "page-no-capture", "parse-error", "placeholder-reason", "prefer-well-known-file", "rename", "scope-leak", "spread-attr", "stale-acknowledgment", "stale-page-baseline", "uidex-export-ambiguous-kind", "uidex-export-duplicate-field", "uidex-export-duplicate-state", "uidex-export-empty-name", "uidex-export-invalid-field", "uidex-export-invalid-literal", "uidex-export-missing-kind", "uidex-export-satisfies-mismatch", "uidex-export-unknown-field", "unknown-reference", "widget-id-mismatch", "widget-missing-acceptance", "widget-missing-dom"];
+declare const DIAGNOSTIC_CODES: readonly ["acceptance-ambiguous", "acceptance-duplicate-id", "acceptance-orphaned", "acceptance-outdated", "acceptance-uncovered", "acknowledged-elsewhere", "competing-uidex-export", "component-state-uncaptured", "core-kind", "covers-missing-rev", "duplicate-id", "dynamic-attr", "dynamic-flow-reference", "feature-missing-acceptance", "feature-surface-uncaptured", "feature-surface-unreferenced", "gen-missing", "gen-stale", "matrix-backlog", "missing-element-annotation", "missing-state-capture", "orphan-state-capture", "page-backlog", "page-captured", "page-no-capture", "parse-error", "placeholder-reason", "prefer-well-known-file", "rename", "scope-leak", "spread-attr", "stale-acknowledgment", "stale-page-baseline", "uidex-export-ambiguous-kind", "uidex-export-duplicate-field", "uidex-export-duplicate-state", "uidex-export-empty-name", "uidex-export-invalid-field", "uidex-export-invalid-literal", "uidex-export-missing-kind", "uidex-export-satisfies-mismatch", "uidex-export-unknown-field", "unknown-reference", "widget-id-mismatch", "widget-missing-acceptance", "widget-missing-dom"];
 declare function validateConfig(raw: unknown): UidexConfig;
 declare function parseConfig(json: string): UidexConfig;
 declare const DEFAULT_CONVENTIONS: Required<Pick<NonNullable<UidexConfig["conventions"]>, "primitives" | "features" | "pages" | "flows" | "regions">>;
@@ -1104,11 +1141,25 @@ declare function run(opts: CliOptions): Promise<CliResult>;
 declare namespace Uidex {
     type CoreStateKind = "loading" | "empty" | "populated" | "error";
     type StateKind = CoreStateKind | "variant";
+    /**
+     * An acceptance criterion as authored. A bare string is sugar: its `id`
+     * becomes a deterministic kebab slug of the text and `rev` defaults to 1.
+     * The object form pins an explicit `id` (stable across copy edits) and an
+     * optional `rev` (bump it when the criterion's meaning changes so flow
+     * coverage pinned to the old rev surfaces as outdated).
+     */
+    interface AcceptanceCriterion {
+        id: string;
+        rev?: number;
+        text: string;
+    }
+    type Acceptance = readonly (string | AcceptanceCriterion)[];
     /** A declared render state, as authored in `states: [{ name, ... }]`. */
     interface State {
         name: string;
         kind?: StateKind;
-        acceptance?: readonly string[];
+        /** Per-state criteria; same authoring sugar as entity-level `acceptance`. */
+        acceptance?: Acceptance;
         description?: string;
     }
     /** Scope of an acknowledgment: one core kind, or the whole entity. */
@@ -1134,16 +1185,28 @@ declare namespace Uidex {
         name?: string;
         features?: readonly FeatureIds[];
         widgets?: readonly WidgetIds[];
-        acceptance?: readonly string[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
         acknowledge?: Acknowledge;
         description?: string;
     }
-    interface Feature<FeatureIds extends string = string> {
+    interface Feature<FeatureIds extends string = string, PageIds extends string = string> {
         feature: FeatureIds | false;
         name?: string;
         features?: readonly FeatureIds[];
-        acceptance?: readonly string[];
+        /**
+         * Pages this feature MUST be mounted on. Each id is verified by the audit
+         * in two halves: the page must exist and its import closure must reference
+         * a component file in the feature's directory (the static
+         * `feature-surface-unreferenced` tripwire), and — when a captured-states
+         * manifest is present — a capture must have rendered the feature on the
+         * page's route (`feature-surface-uncaptured`, the runtime evidence). This
+         * is how a cross-cutting feature (a gate editor, a share panel) states
+         * "every one of these editors owes me a mount" and a forgotten mount fails
+         * the scan instead of shipping.
+         */
+        surfaces?: readonly PageIds[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
         acknowledge?: ComponentAcknowledge;
         description?: string;
@@ -1156,11 +1219,16 @@ declare namespace Uidex {
     interface Widget<WidgetIds extends string = string> {
         widget: WidgetIds;
         name?: string;
-        acceptance?: readonly string[];
+        acceptance?: Acceptance;
         states?: readonly (string | State)[];
         acknowledge?: ComponentAcknowledge;
         description?: string;
     }
+    interface Region<RegionIds extends string = string> {
+        region: RegionIds | false;
+        name?: string;
+        description?: string;
+    }
     interface Flow<FlowIds extends string = string> {
         flow: FlowIds;
         name?: string;
@@ -1171,4 +1239,4 @@ declare namespace Uidex {
     }
 }
 
-export { ACK_ALL, ACK_SCOPES, type AcknowledgeMap, type AcknowledgeOrigin, type AcknowledgeType, type Acknowledgment, 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, type CoverageBaseline, DEFAULT_CONVENTIONS, DIAGNOSTIC_CODES, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MergeResult, type MetadataExport, type MetadataExportKind, type ParsedAcknowledgment, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type ResolvedAcknowledgment, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateCoverageOptions, Uidex, type UidexConfig, type Workspace, type WorkspaceApp, applyFixes, audit, capturedElsewhere, checkComponentCoverage, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMatrixBacklog, computePageBacklog, coverageBaselinePath, detectRoutes, discover, emit, entityAcknowledge, extract, extractUidexExports, findWorkspaceRoot, globToRegExp, isLegacyBaseline, loadCoverageBaseline, matchUrlToRoute, mergeStates, migrateBaseline, migrateLegacyBaseline, migrateLegacyFields, parseConfig, parseCoverageBaseline, pathToId, renameEntity, resolve, resolveGitContext, resolveWorkspace, routeAcknowledge, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, serializeCoverageBaseline, validateConfig, walk, writeScanResult };
+export { ACK_ALL, ACK_SCOPES, type AcknowledgeMap, type AcknowledgeOrigin, type AcknowledgeType, type Acknowledgment, 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, type CoverageBaseline, DEFAULT_CONVENTIONS, DIAGNOSTIC_CODES, type DetectedRoute, type Diagnostic, type DiagnosticFix, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type FixEdit, type GitContext, type ImportFact, type LandmarkFact, type MergeResult, type MetadataExport, type MetadataExportKind, type ParsedAcknowledgment, type ParsedState, type RenameKind, type RenameOptions, type RenameResult, type ResolvedAcknowledgment, type RunScanOptions, type ScaffoldKind, type ScaffoldOptions, type ScaffoldResult, type ScaffoldSpecOptions, type ScanResult, type ScannedFile, type SourceConfig, type Span, type StateCoverageOptions, Uidex, type UidexConfig, type Workspace, type WorkspaceApp, applyFixes, audit, capturedElsewhere, checkComponentCoverage, checkPageCoverage, checkStateCoverage, checkStateMatrix, compileRoute, computeMatrixBacklog, computePageBacklog, coverageBaselinePath, detectRoutes, discover, emit, entityAcknowledge, extract, extractUidexExports, findWorkspaceRoot, globToRegExp, loadCoverageBaseline, matchUrlToRoute, mergeStates, parseConfig, parseCoverageBaseline, pathToId, renameEntity, resolve, resolveGitContext, resolveWorkspace, routeAcknowledge, run as runCli, runScan, scaffoldSpec, scaffoldWidgetSpec, serializeCoverageBaseline, validateConfig, walk, writeScanResult };