uidex 0.2.4 → 0.4.0

package/dist/scan/index.d.ts

@@ -0,0 +1,378 @@
+declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
+type EntityKind = (typeof ENTITY_KINDS)[number];
+type Scope = string;
+interface Location {
+    file: string;
+    line?: number;
+    column?: number;
+}
+interface EntityRef {
+    kind: EntityKind;
+    id: string;
+}
+interface Metadata {
+    name?: string;
+    description?: string;
+    acceptance?: string[];
+    notes?: string;
+    composes?: EntityRef[];
+    flows?: readonly string[];
+    features?: string[];
+    widgets?: string[];
+}
+interface EntityWithMetaBase {
+    id: string;
+    loc?: Location;
+    scopes?: Scope[];
+    meta?: Metadata;
+}
+interface Route {
+    kind: "route";
+    path: string;
+    page: string;
+}
+interface FlowStep {
+    entityId: string;
+    action?: string;
+}
+interface Flow {
+    kind: "flow";
+    id: string;
+    loc: Location;
+    touches: string[];
+    steps: FlowStep[];
+}
+interface Page extends EntityWithMetaBase {
+    kind: "page";
+}
+interface Feature extends EntityWithMetaBase {
+    kind: "feature";
+}
+interface Widget extends EntityWithMetaBase {
+    kind: "widget";
+}
+interface Region extends EntityWithMetaBase {
+    kind: "region";
+}
+interface Element extends EntityWithMetaBase {
+    kind: "element";
+}
+interface Primitive extends EntityWithMetaBase {
+    kind: "primitive";
+}
+type Entity = Route | Page | Feature | Widget | Region | Element | Primitive | Flow;
+type EntityByKind<K extends EntityKind> = Extract<Entity, {
+    kind: K;
+}>;
+
+interface Registry {
+    add(entity: Entity): void;
+    get<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[];
+    touchedBy(flowId: string): Entity[];
+}
+
+interface SourceConfig {
+    rootDir: string;
+    include?: string[];
+    exclude?: string[];
+    prefix?: string;
+}
+interface ConventionsConfig {
+    primitives?: string[] | false;
+    features?: string | false;
+    pages?: "auto" | false;
+    flows?: string[] | false;
+    regions?: "landmarks" | false;
+}
+interface AuditConfig {
+    scopeLeak?: boolean;
+    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;
+}
+interface DiscoveredConfig {
+    configPath: string;
+    configDir: string;
+    config: UidexConfig;
+}
+interface ScannedFile {
+    sourcePath: string;
+    relativePath: string;
+    displayPath: string;
+    content: string;
+}
+type AnnotationKind = "element" | "region" | "widget" | "primitive" | "page-doc" | "feature-doc" | "widget-doc" | "not-flow" | "orphan-acceptance";
+type DomAttrKind = "element" | "region" | "widget" | "primitive";
+interface AnnotationAncestor {
+    kind: DomAttrKind;
+    id: string;
+}
+interface Annotation {
+    kind: AnnotationKind;
+    id: string;
+    file: string;
+    line: number;
+    description?: string;
+    acceptance?: string[];
+    /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
+    ancestors?: AnnotationAncestor[];
+}
+type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "flow";
+interface MetadataExport {
+    source: "ts-export";
+    kind: MetadataExportKind;
+    id: string | false;
+    name?: string;
+    acceptance?: string[];
+    description?: string;
+    features?: string[];
+    widgets?: string[];
+    notFlow?: boolean;
+    loc: Location;
+}
+interface ExtractedFile {
+    file: ScannedFile;
+    annotations: Annotation[];
+    metadata?: MetadataExport[];
+    diagnostics?: Diagnostic[];
+}
+interface DetectedRoute {
+    id: string;
+    path: string;
+    file: string;
+}
+type DiagnosticSeverity = "error" | "warning" | "info";
+interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    file?: string;
+    line?: number;
+    entity?: {
+        kind: EntityKind;
+        id: string;
+    };
+    hint?: string;
+}
+interface AuditSummary {
+    diagnostics: Diagnostic[];
+    summary: {
+        errors: number;
+        warnings: number;
+    };
+}
+interface GitContext {
+    branch: string | null;
+    commit: string | null;
+    pr: string | null;
+}
+
+declare const CONFIG_FILENAME = ".uidex.json";
+interface DiscoverOptions {
+    cwd?: string;
+    maxDepth?: number;
+}
+declare function discover(options?: DiscoverOptions): DiscoveredConfig[];
+
+/**
+ * Translate a glob to a RegExp. Supports `**`, `*`, `?`, and `{a,b,c}` alternation.
+ * The produced pattern matches the full relative path with forward slashes.
+ */
+declare function globToRegExp(glob: string): RegExp;
+interface WalkOptions {
+    cwd: string;
+    globalExcludes?: string[];
+    /**
+     * When true, do not auto-exclude `*.spec.{ts,tsx}` and `*.test.{ts,tsx}`.
+     * Used by flow-file walking, where spec files are the targets.
+     */
+    includeTests?: boolean;
+}
+declare function walk(sources: SourceConfig[], options: WalkOptions): ScannedFile[];
+
+declare function extract(files: ScannedFile[]): ExtractedFile[];
+
+interface UidexExportExtractResult {
+    exports: MetadataExport[];
+    diagnostics: Diagnostic[];
+}
+declare function extractUidexExports(file: ScannedFile): UidexExportExtractResult;
+
+interface ResolveContext {
+    config: UidexConfig;
+    extracted: ExtractedFile[];
+    flowFiles?: ExtractedFile[];
+}
+interface ResolveOutput {
+    registry: Registry;
+    entities: Entity[];
+    routes: DetectedRoute[];
+    diagnostics: Diagnostic[];
+}
+/**
+ * Resolve annotations + conventions into a typed Registry.
+ * Precedence: configuration > `export const uidex` > DOM attribute > convention.
+ */
+declare function resolve(ctx: ResolveContext): ResolveOutput;
+
+interface AuditOptions {
+    registry: Registry;
+    extracted: ExtractedFile[];
+    files: ScannedFile[];
+    config: UidexConfig;
+    check?: boolean;
+    lint?: boolean;
+    resolveDiagnostics?: Diagnostic[];
+    /** Freshly-emitted gen-file bytes, required for --check. */
+    generated?: string;
+    /** On-disk contents of the gen file at scan time; `null` if the file does not exist. */
+    existingOnDisk?: string | null;
+    /** Relative path of the configured `output` file; used in diagnostics. */
+    outputPath?: string;
+}
+declare function audit(opts: AuditOptions): AuditSummary;
+
+interface EmitOptions {
+    registry: Registry;
+    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;
+
+/**
+ * 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`
+ */
+declare function detectRoutes(files: ScannedFile[]): DetectedRoute[];
+declare function pathToId(routePath: string): string;
+
+interface GitResolveOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}
+declare function resolveGitContext(opts?: GitResolveOptions): GitContext;
+
+interface ScaffoldOptions {
+    registry: Registry;
+    widgetId: string;
+    outDir: string;
+    force?: boolean;
+    fixtureImport?: string;
+}
+interface ScaffoldResult {
+    outputPath: string;
+    written: boolean;
+    skipped: boolean;
+    reason?: string;
+}
+declare function scaffoldWidgetSpec(opts: ScaffoldOptions): ScaffoldResult;
+
+interface RunScanOptions {
+    cwd?: string;
+    check?: boolean;
+    lint?: boolean;
+    configs?: DiscoveredConfig[];
+}
+interface ScanResult {
+    config: UidexConfig;
+    configDir: string;
+    registry: Registry;
+    gitContext: GitContext;
+    audit?: AuditSummary;
+    generated: string;
+    outputPath: string;
+}
+declare function runScan(opts?: RunScanOptions): ScanResult[];
+declare function writeScanResult(result: ScanResult): void;
+
+interface CliResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+interface CliOptions {
+    argv: string[];
+    cwd?: string;
+}
+declare function run(opts: CliOptions): Promise<CliResult>;
+
+declare const DEFAULT_TYPE_MODE: TypeMode;
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+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">>;
+
+/**
+ * Authoring-surface shape types for `export const uidex = { ... }` declarations.
+ *
+ * The gen-file emitter specialises each shape with the project's emitted id
+ * unions (or `string` in loose mode), producing a project-specific `Uidex`
+ * namespace that lives alongside the generated registry. Authors write:
+ *
+ *     export const uidex = { page: "checkout", features: ["billing"] }
+ *       as const satisfies Uidex.Page
+ *
+ * and `tsc` validates the ids at the literal site.
+ *
+ * The generic parameters default to `string` so these shapes remain usable in
+ * contexts that have not yet regenerated the gen file (e.g. loose mode, or
+ * bootstrapping before the first scan).
+ */
+declare namespace Uidex {
+    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[];
+        description?: string;
+    }
+    interface Feature<FeatureIds extends string = string> {
+        feature: FeatureIds | false;
+        name?: string;
+        acceptance?: readonly string[];
+        description?: string;
+    }
+    interface Primitive<PrimitiveIds extends string = string> {
+        primitive: PrimitiveIds;
+        name?: string;
+        description?: string;
+    }
+    interface Widget<WidgetIds extends string = string> {
+        widget: WidgetIds;
+        name?: string;
+        acceptance?: readonly string[];
+        description?: string;
+    }
+    interface Flow<FlowIds extends string = string> {
+        flow: FlowIds;
+        name?: string;
+        description?: string;
+    }
+    interface NotFlow {
+        notFlow: true;
+    }
+}
+
+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 };