uidex 0.5.2 → 0.7.0

package/dist/scan/index.d.cts

@@ -1,3 +1,5 @@
+import { Program } from 'oxc-parser';
+
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
 type EntityKind = (typeof ENTITY_KINDS)[number];
 type Scope = string;
@@ -88,6 +90,7 @@ interface ReportRecord {
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
+    matchPattern<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
     list<K extends EntityKind>(kind: K): ReadonlyArray<EntityByKind<K>>;
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
@@ -95,7 +98,7 @@ interface Registry {
     setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
     getReports(kind: EntityKind, id: string): readonly ReportRecord[];
     listReportKeys(): readonly string[];
-    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    closeReport?: (reportId: string, status?: string) => void | Promise<void>;
     onReportsChange(cb: () => void): () => void;
 }
 
@@ -117,14 +120,12 @@ interface AuditConfig {
     coverage?: boolean;
     acceptance?: boolean;
 }
-type TypeMode = "strict" | "loose";
 interface UidexConfig {
     $schema?: string;
     sources: SourceConfig[];
     exclude?: string[];
     output: string;
     flows?: string[];
-    typeMode?: TypeMode;
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
 }
@@ -139,7 +140,12 @@ interface ScannedFile {
     displayPath: string;
     content: string;
 }
-type AnnotationKind = "element" | "region" | "widget" | "primitive" | "page-doc" | "feature-doc" | "widget-doc" | "not-flow" | "orphan-acceptance";
+/** Byte-offset range into a ScannedFile's content (UTF-16 code units, like oxc spans). */
+interface Span {
+    start: number;
+    end: number;
+}
+type AnnotationKind = "element" | "region" | "widget" | "primitive";
 type DomAttrKind = "element" | "region" | "widget" | "primitive";
 interface AnnotationAncestor {
     kind: DomAttrKind;
@@ -150,10 +156,10 @@ interface Annotation {
     id: string;
     file: string;
     line: number;
-    description?: string;
-    acceptance?: string[];
-    /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
+    /** JSX ancestor chain, outermost to innermost. */
     ancestors?: AnnotationAncestor[];
+    /** The span of the attribute's value literal. */
+    span?: Span;
 }
 type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "region" | "flow";
 interface MetadataExport {
@@ -167,12 +173,86 @@ interface MetadataExport {
     widgets?: string[];
     notFlow?: boolean;
     loc: Location;
+    /** Span of the whole `export const uidex = ...` statement (incl. trailing `;`). */
+    span?: Span;
+    /** Span of the id string literal (the discriminator field's value). */
+    idSpan?: Span;
+    /**
+     * Removal-ready spans of top-level fields (key through value, extended over
+     * one adjacent comma) keyed by field name. Used by `--fix` codemods.
+     */
+    fieldSpans?: Record<string, Span>;
+    /** Spans of the string-literal items in `features`, parallel to `features`. */
+    featureSpans?: Span[];
+    /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
+    widgetSpans?: Span[];
+}
+/** A data-uidex* attribute whose value the scanner could not resolve. */
+interface DynamicAttrFact {
+    kind: DomAttrKind;
+    attrName: string;
+    line: number;
+}
+/** An HTML5 landmark element (`<header>`, `<nav>`, …, or `role="region"`). */
+interface LandmarkFact {
+    /** the host tag, or "region" for role="region" */
+    tag: string;
+    line: number;
+}
+/** A static import binding (import / export-from), for the scope-leak check. */
+interface ImportFact {
+    specifier: string;
+    line: number;
+    /** span of the whole import/export statement */
+    span: Span;
+    /** `import type` or an export-from with type-only kind */
+    isTypeOnly: boolean;
+    /** imported local binding names (default + named + namespace) */
+    names: string[];
+}
+/** An interactive host element (`button`, `a`, …) with no data-uidex* attribute. */
+interface InteractiveElementFact {
+    tag: string;
+    line: number;
+    /** the element carries a `{...props}` spread that may deliver the annotation */
+    hasSpread: boolean;
+    /** offset just after the tag name; where `--fix` inserts the generated attribute */
+    nameEnd: number;
+    /**
+     * Best static label for deriving an id (aria-label, visible text, title,
+     * name, placeholder). Absent when nothing usable is statically available.
+     */
+    nameHint?: string;
+}
+interface FlowCallFact {
+    id: string;
+    action?: string;
+    line: number;
+    /** span of the id string literal argument */
+    span?: Span;
+}
+/** A `uidex(expr)` call whose argument is not a static string literal. */
+interface DynamicFlowCallFact {
+    line: number;
+}
+/** A tagged `test.describe(..., { tag: "@uidex:flow" }, ...)` occurrence. */
+interface FlowFact {
+    title: string;
+    line: number;
+    calls: FlowCallFact[];
+    /** uidex() calls inside this describe whose ids could not be resolved */
+    dynamicCalls?: DynamicFlowCallFact[];
 }
 interface ExtractedFile {
     file: ScannedFile;
     annotations: Annotation[];
     metadata?: MetadataExport[];
     diagnostics?: Diagnostic[];
+    flows?: FlowFact[];
+    dynamicAttrs?: DynamicAttrFact[];
+    unannotatedInteractive?: InteractiveElementFact[];
+    landmarks?: LandmarkFact[];
+    imports?: ImportFact[];
 }
 interface DetectedRoute {
     id: string;
@@ -180,6 +260,30 @@ interface DetectedRoute {
     file: string;
 }
 type DiagnosticSeverity = "error" | "warning" | "info";
+/** A single text replacement; offsets index the file's content at scan time. */
+interface FixEdit {
+    /** absolute path of the file to edit */
+    path: string;
+    start: number;
+    end: number;
+    replacement: string;
+}
+/**
+ * A machine-applicable fix attached to a diagnostic. Applied by
+ * `uidex scan --fix`; edits are computed against the exact content the
+ * scanner read, so they must be applied before any other modification.
+ */
+interface DiagnosticFix {
+    description: string;
+    edits?: FixEdit[];
+    /** files to create (absolute path → content); skipped if the file exists */
+    createFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** absolute paths of files to delete */
+    deleteFiles?: string[];
+}
 interface Diagnostic {
     code: string;
     severity: DiagnosticSeverity;
@@ -191,6 +295,7 @@ interface Diagnostic {
         id: string;
     };
     hint?: string;
+    fix?: DiagnosticFix;
 }
 interface AuditSummary {
     diagnostics: Diagnostic[];
@@ -230,11 +335,36 @@ declare function walk(sources: SourceConfig[], options: WalkOptions): ScannedFil
 
 declare function extract(files: ScannedFile[]): ExtractedFile[];
 
+/**
+ * Shared parse layer for the scanner. Each file is parsed exactly once in
+ * the extract phase; the resulting AST never leaves it (ExtractedFile must
+ * stay JSON-serializable for the bundler-plugin watchers).
+ *
+ * oxc spans are UTF-16 code-unit offsets, i.e. they index directly into the
+ * JS source string (verified against oxc-parser@0.135.0).
+ */
+interface ParsedComment {
+    type: "Line" | "Block";
+    value: string;
+    start: number;
+    end: number;
+}
+interface ParsedSource {
+    /** null when parsing failed catastrophically — callers degrade to empty facts */
+    program: Program | null;
+    /** true when oxc reported recoverable errors (program is still usable) */
+    hasErrors: boolean;
+    /** all comments in source order; empty when parsing failed */
+    comments: ParsedComment[];
+    /** offset → 1-based line */
+    lineAt(offset: number): number;
+}
+
 interface UidexExportExtractResult {
     exports: MetadataExport[];
     diagnostics: Diagnostic[];
 }
-declare function extractUidexExports(file: ScannedFile): UidexExportExtractResult;
+declare function extractUidexExports(file: ScannedFile, parsed?: ParsedSource): UidexExportExtractResult;
 
 interface ResolveContext {
     config: UidexConfig;
@@ -257,6 +387,8 @@ interface AuditOptions {
     registry: Registry;
     extracted: ExtractedFile[];
     files: ScannedFile[];
+    /** Extract output for flow spec files; enables per-call reference checks. */
+    flowExtracted?: ExtractedFile[];
     config: UidexConfig;
     check?: boolean;
     lint?: boolean;
@@ -275,8 +407,6 @@ interface EmitOptions {
     gitContext?: GitContext;
     /** The import source for `createUidex` in the generated preconfigured export. */
     uidexImport?: string;
-    /** Controls id-union emission: "strict" emits literal unions, "loose" emits `string`. */
-    typeMode?: TypeMode;
 }
 declare function emit(opts: EmitOptions): string;
 
@@ -296,6 +426,15 @@ interface GitResolveOptions {
 }
 declare function resolveGitContext(opts?: GitResolveOptions): GitContext;
 
+type ScaffoldKind = "widget" | "page" | "feature";
+interface ScaffoldSpecOptions {
+    registry: Registry;
+    kind: ScaffoldKind;
+    id: string;
+    outDir: string;
+    force?: boolean;
+    fixtureImport?: string;
+}
 interface ScaffoldOptions {
     registry: Registry;
     widgetId: string;
@@ -310,6 +449,13 @@ interface ScaffoldResult {
     reason?: string;
 }
 declare function scaffoldWidgetSpec(opts: ScaffoldOptions): ScaffoldResult;
+/**
+ * Emits a tagged Playwright stub from an entity's declared acceptance
+ * criteria — one `test()` per criterion. Widgets keep the historical
+ * `widget-<id>.spec.ts` name; pages and features emit `flow-<id>.spec.ts`
+ * per the one-tagged-describe-per-flow-spec convention.
+ */
+declare function scaffoldSpec(opts: ScaffoldSpecOptions): ScaffoldResult;
 
 interface RunScanOptions {
     cwd?: string;
@@ -329,6 +475,59 @@ interface ScanResult {
 declare function runScan(opts?: RunScanOptions): ScanResult[];
 declare function writeScanResult(result: ScanResult): void;
 
+/**
+ * Applies the machine-generated fixes attached to diagnostics.
+ *
+ * Edits are offset-based against the content the scanner read, so this must
+ * run before anything else touches the files. Within a file, edits apply
+ * last-to-first; an edit overlapping one already applied is skipped. Identical
+ * edits are deduped — two fixes in one file emitting the same edit collapse to
+ * one application.
+ */
+interface AppliedFix {
+    code: string;
+    description: string;
+    file?: string;
+}
+interface ApplyFixesResult {
+    applied: AppliedFix[];
+    /** fixes skipped because of overlapping edits or existing target files */
+    skipped: Array<AppliedFix & {
+        reason: string;
+    }>;
+}
+declare function applyFixes(diagnostics: Diagnostic[]): ApplyFixesResult;
+
+/**
+ * Cross-file id rename. The registry knows every reference surface for an
+ * id — the DOM attribute, `uidex("…")` calls in flow specs, the widget
+ * export's discriminator, and `widgets:` arrays — so the rename rewrites all
+ * of them in one pass and regenerates the gen file. Occurrences the scanner
+ * can't edit mechanically (const indirection, ternaries, patterns) are
+ * reported for manual follow-up instead of being guessed at.
+ */
+type RenameKind = "element" | "widget" | "region";
+interface RenameOptions {
+    cwd: string;
+    kind: RenameKind;
+    oldId: string;
+    newId: string;
+    /** allow renaming onto an id that already exists */
+    force?: boolean;
+}
+interface RenameResult {
+    /** number of source edits applied */
+    edits: number;
+    /** occurrences that need a human (no static literal to rewrite) */
+    manual: Array<{
+        file: string;
+        line: number;
+        reason: string;
+    }>;
+    errors: string[];
+}
+declare function renameEntity(opts: RenameOptions): RenameResult;
+
 interface CliResult {
     exitCode: number;
     stdout: string;
@@ -340,7 +539,6 @@ interface CliOptions {
 }
 declare function run(opts: CliOptions): Promise<CliResult>;
 
-declare const DEFAULT_TYPE_MODE: TypeMode;
 declare class ConfigError extends Error {
     constructor(message: string);
 }
@@ -401,4 +599,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, DEFAULT_TYPE_MODE, type DetectedRoute, type Diagnostic, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type GitContext, type MetadataExport, type MetadataExportKind, type RunScanOptions, type ScaffoldOptions, type ScaffoldResult, type ScanResult, type ScannedFile, type SourceConfig, type TypeMode, Uidex, type UidexConfig, audit, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, parseConfig, pathToId, resolve, resolveGitContext, run as runCli, runScan, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+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 };

package/dist/scan/index.d.ts

@@ -1,3 +1,5 @@
+import { Program } from 'oxc-parser';
+
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
 type EntityKind = (typeof ENTITY_KINDS)[number];
 type Scope = string;
@@ -88,6 +90,7 @@ interface ReportRecord {
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
+    matchPattern<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
     list<K extends EntityKind>(kind: K): ReadonlyArray<EntityByKind<K>>;
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
@@ -95,7 +98,7 @@ interface Registry {
     setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
     getReports(kind: EntityKind, id: string): readonly ReportRecord[];
     listReportKeys(): readonly string[];
-    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    closeReport?: (reportId: string, status?: string) => void | Promise<void>;
     onReportsChange(cb: () => void): () => void;
 }
 
@@ -117,14 +120,12 @@ interface AuditConfig {
     coverage?: boolean;
     acceptance?: boolean;
 }
-type TypeMode = "strict" | "loose";
 interface UidexConfig {
     $schema?: string;
     sources: SourceConfig[];
     exclude?: string[];
     output: string;
     flows?: string[];
-    typeMode?: TypeMode;
     audit?: AuditConfig;
     conventions?: ConventionsConfig;
 }
@@ -139,7 +140,12 @@ interface ScannedFile {
     displayPath: string;
     content: string;
 }
-type AnnotationKind = "element" | "region" | "widget" | "primitive" | "page-doc" | "feature-doc" | "widget-doc" | "not-flow" | "orphan-acceptance";
+/** Byte-offset range into a ScannedFile's content (UTF-16 code units, like oxc spans). */
+interface Span {
+    start: number;
+    end: number;
+}
+type AnnotationKind = "element" | "region" | "widget" | "primitive";
 type DomAttrKind = "element" | "region" | "widget" | "primitive";
 interface AnnotationAncestor {
     kind: DomAttrKind;
@@ -150,10 +156,10 @@ interface Annotation {
     id: string;
     file: string;
     line: number;
-    description?: string;
-    acceptance?: string[];
-    /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
+    /** JSX ancestor chain, outermost to innermost. */
     ancestors?: AnnotationAncestor[];
+    /** The span of the attribute's value literal. */
+    span?: Span;
 }
 type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "region" | "flow";
 interface MetadataExport {
@@ -167,12 +173,86 @@ interface MetadataExport {
     widgets?: string[];
     notFlow?: boolean;
     loc: Location;
+    /** Span of the whole `export const uidex = ...` statement (incl. trailing `;`). */
+    span?: Span;
+    /** Span of the id string literal (the discriminator field's value). */
+    idSpan?: Span;
+    /**
+     * Removal-ready spans of top-level fields (key through value, extended over
+     * one adjacent comma) keyed by field name. Used by `--fix` codemods.
+     */
+    fieldSpans?: Record<string, Span>;
+    /** Spans of the string-literal items in `features`, parallel to `features`. */
+    featureSpans?: Span[];
+    /** Spans of the string-literal items in `widgets`, parallel to `widgets`. */
+    widgetSpans?: Span[];
+}
+/** A data-uidex* attribute whose value the scanner could not resolve. */
+interface DynamicAttrFact {
+    kind: DomAttrKind;
+    attrName: string;
+    line: number;
+}
+/** An HTML5 landmark element (`<header>`, `<nav>`, …, or `role="region"`). */
+interface LandmarkFact {
+    /** the host tag, or "region" for role="region" */
+    tag: string;
+    line: number;
+}
+/** A static import binding (import / export-from), for the scope-leak check. */
+interface ImportFact {
+    specifier: string;
+    line: number;
+    /** span of the whole import/export statement */
+    span: Span;
+    /** `import type` or an export-from with type-only kind */
+    isTypeOnly: boolean;
+    /** imported local binding names (default + named + namespace) */
+    names: string[];
+}
+/** An interactive host element (`button`, `a`, …) with no data-uidex* attribute. */
+interface InteractiveElementFact {
+    tag: string;
+    line: number;
+    /** the element carries a `{...props}` spread that may deliver the annotation */
+    hasSpread: boolean;
+    /** offset just after the tag name; where `--fix` inserts the generated attribute */
+    nameEnd: number;
+    /**
+     * Best static label for deriving an id (aria-label, visible text, title,
+     * name, placeholder). Absent when nothing usable is statically available.
+     */
+    nameHint?: string;
+}
+interface FlowCallFact {
+    id: string;
+    action?: string;
+    line: number;
+    /** span of the id string literal argument */
+    span?: Span;
+}
+/** A `uidex(expr)` call whose argument is not a static string literal. */
+interface DynamicFlowCallFact {
+    line: number;
+}
+/** A tagged `test.describe(..., { tag: "@uidex:flow" }, ...)` occurrence. */
+interface FlowFact {
+    title: string;
+    line: number;
+    calls: FlowCallFact[];
+    /** uidex() calls inside this describe whose ids could not be resolved */
+    dynamicCalls?: DynamicFlowCallFact[];
 }
 interface ExtractedFile {
     file: ScannedFile;
     annotations: Annotation[];
     metadata?: MetadataExport[];
     diagnostics?: Diagnostic[];
+    flows?: FlowFact[];
+    dynamicAttrs?: DynamicAttrFact[];
+    unannotatedInteractive?: InteractiveElementFact[];
+    landmarks?: LandmarkFact[];
+    imports?: ImportFact[];
 }
 interface DetectedRoute {
     id: string;
@@ -180,6 +260,30 @@ interface DetectedRoute {
     file: string;
 }
 type DiagnosticSeverity = "error" | "warning" | "info";
+/** A single text replacement; offsets index the file's content at scan time. */
+interface FixEdit {
+    /** absolute path of the file to edit */
+    path: string;
+    start: number;
+    end: number;
+    replacement: string;
+}
+/**
+ * A machine-applicable fix attached to a diagnostic. Applied by
+ * `uidex scan --fix`; edits are computed against the exact content the
+ * scanner read, so they must be applied before any other modification.
+ */
+interface DiagnosticFix {
+    description: string;
+    edits?: FixEdit[];
+    /** files to create (absolute path → content); skipped if the file exists */
+    createFiles?: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** absolute paths of files to delete */
+    deleteFiles?: string[];
+}
 interface Diagnostic {
     code: string;
     severity: DiagnosticSeverity;
@@ -191,6 +295,7 @@ interface Diagnostic {
         id: string;
     };
     hint?: string;
+    fix?: DiagnosticFix;
 }
 interface AuditSummary {
     diagnostics: Diagnostic[];
@@ -230,11 +335,36 @@ declare function walk(sources: SourceConfig[], options: WalkOptions): ScannedFil
 
 declare function extract(files: ScannedFile[]): ExtractedFile[];
 
+/**
+ * Shared parse layer for the scanner. Each file is parsed exactly once in
+ * the extract phase; the resulting AST never leaves it (ExtractedFile must
+ * stay JSON-serializable for the bundler-plugin watchers).
+ *
+ * oxc spans are UTF-16 code-unit offsets, i.e. they index directly into the
+ * JS source string (verified against oxc-parser@0.135.0).
+ */
+interface ParsedComment {
+    type: "Line" | "Block";
+    value: string;
+    start: number;
+    end: number;
+}
+interface ParsedSource {
+    /** null when parsing failed catastrophically — callers degrade to empty facts */
+    program: Program | null;
+    /** true when oxc reported recoverable errors (program is still usable) */
+    hasErrors: boolean;
+    /** all comments in source order; empty when parsing failed */
+    comments: ParsedComment[];
+    /** offset → 1-based line */
+    lineAt(offset: number): number;
+}
+
 interface UidexExportExtractResult {
     exports: MetadataExport[];
     diagnostics: Diagnostic[];
 }
-declare function extractUidexExports(file: ScannedFile): UidexExportExtractResult;
+declare function extractUidexExports(file: ScannedFile, parsed?: ParsedSource): UidexExportExtractResult;
 
 interface ResolveContext {
     config: UidexConfig;
@@ -257,6 +387,8 @@ interface AuditOptions {
     registry: Registry;
     extracted: ExtractedFile[];
     files: ScannedFile[];
+    /** Extract output for flow spec files; enables per-call reference checks. */
+    flowExtracted?: ExtractedFile[];
     config: UidexConfig;
     check?: boolean;
     lint?: boolean;
@@ -275,8 +407,6 @@ interface EmitOptions {
     gitContext?: GitContext;
     /** The import source for `createUidex` in the generated preconfigured export. */
     uidexImport?: string;
-    /** Controls id-union emission: "strict" emits literal unions, "loose" emits `string`. */
-    typeMode?: TypeMode;
 }
 declare function emit(opts: EmitOptions): string;
 
@@ -296,6 +426,15 @@ interface GitResolveOptions {
 }
 declare function resolveGitContext(opts?: GitResolveOptions): GitContext;
 
+type ScaffoldKind = "widget" | "page" | "feature";
+interface ScaffoldSpecOptions {
+    registry: Registry;
+    kind: ScaffoldKind;
+    id: string;
+    outDir: string;
+    force?: boolean;
+    fixtureImport?: string;
+}
 interface ScaffoldOptions {
     registry: Registry;
     widgetId: string;
@@ -310,6 +449,13 @@ interface ScaffoldResult {
     reason?: string;
 }
 declare function scaffoldWidgetSpec(opts: ScaffoldOptions): ScaffoldResult;
+/**
+ * Emits a tagged Playwright stub from an entity's declared acceptance
+ * criteria — one `test()` per criterion. Widgets keep the historical
+ * `widget-<id>.spec.ts` name; pages and features emit `flow-<id>.spec.ts`
+ * per the one-tagged-describe-per-flow-spec convention.
+ */
+declare function scaffoldSpec(opts: ScaffoldSpecOptions): ScaffoldResult;
 
 interface RunScanOptions {
     cwd?: string;
@@ -329,6 +475,59 @@ interface ScanResult {
 declare function runScan(opts?: RunScanOptions): ScanResult[];
 declare function writeScanResult(result: ScanResult): void;
 
+/**
+ * Applies the machine-generated fixes attached to diagnostics.
+ *
+ * Edits are offset-based against the content the scanner read, so this must
+ * run before anything else touches the files. Within a file, edits apply
+ * last-to-first; an edit overlapping one already applied is skipped. Identical
+ * edits are deduped — two fixes in one file emitting the same edit collapse to
+ * one application.
+ */
+interface AppliedFix {
+    code: string;
+    description: string;
+    file?: string;
+}
+interface ApplyFixesResult {
+    applied: AppliedFix[];
+    /** fixes skipped because of overlapping edits or existing target files */
+    skipped: Array<AppliedFix & {
+        reason: string;
+    }>;
+}
+declare function applyFixes(diagnostics: Diagnostic[]): ApplyFixesResult;
+
+/**
+ * Cross-file id rename. The registry knows every reference surface for an
+ * id — the DOM attribute, `uidex("…")` calls in flow specs, the widget
+ * export's discriminator, and `widgets:` arrays — so the rename rewrites all
+ * of them in one pass and regenerates the gen file. Occurrences the scanner
+ * can't edit mechanically (const indirection, ternaries, patterns) are
+ * reported for manual follow-up instead of being guessed at.
+ */
+type RenameKind = "element" | "widget" | "region";
+interface RenameOptions {
+    cwd: string;
+    kind: RenameKind;
+    oldId: string;
+    newId: string;
+    /** allow renaming onto an id that already exists */
+    force?: boolean;
+}
+interface RenameResult {
+    /** number of source edits applied */
+    edits: number;
+    /** occurrences that need a human (no static literal to rewrite) */
+    manual: Array<{
+        file: string;
+        line: number;
+        reason: string;
+    }>;
+    errors: string[];
+}
+declare function renameEntity(opts: RenameOptions): RenameResult;
+
 interface CliResult {
     exitCode: number;
     stdout: string;
@@ -340,7 +539,6 @@ interface CliOptions {
 }
 declare function run(opts: CliOptions): Promise<CliResult>;
 
-declare const DEFAULT_TYPE_MODE: TypeMode;
 declare class ConfigError extends Error {
     constructor(message: string);
 }
@@ -401,4 +599,4 @@ declare namespace Uidex {
     }
 }
 
-export { type Annotation, type AnnotationKind, type AuditConfig, type AuditSummary, CONFIG_FILENAME, type CliOptions, type CliResult, ConfigError, type ConventionsConfig, DEFAULT_CONVENTIONS, DEFAULT_TYPE_MODE, type DetectedRoute, type Diagnostic, type DiagnosticSeverity, type DiscoveredConfig, type ExtractedFile, type GitContext, type MetadataExport, type MetadataExportKind, type RunScanOptions, type ScaffoldOptions, type ScaffoldResult, type ScanResult, type ScannedFile, type SourceConfig, type TypeMode, Uidex, type UidexConfig, audit, detectRoutes, discover, emit, extract, extractUidexExports, globToRegExp, parseConfig, pathToId, resolve, resolveGitContext, run as runCli, runScan, scaffoldWidgetSpec, validateConfig, walk, writeScanResult };
+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 };