uidex 0.4.0 → 0.5.1

package/dist/scan/index.d.cts

@@ -65,6 +65,26 @@ type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -72,6 +92,11 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    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>;
+    onReportsChange(cb: () => void): () => void;
 }
 
 interface SourceConfig {
@@ -130,7 +155,7 @@ interface Annotation {
     /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
     ancestors?: AnnotationAncestor[];
 }
-type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "flow";
+type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "region" | "flow";
 interface MetadataExport {
     source: "ts-export";
     kind: MetadataExportKind;
@@ -351,6 +376,7 @@ declare namespace Uidex {
     interface Feature<FeatureIds extends string = string> {
         feature: FeatureIds | false;
         name?: string;
+        features?: readonly FeatureIds[];
         acceptance?: readonly string[];
         description?: string;
     }

package/dist/scan/index.d.ts

@@ -65,6 +65,26 @@ type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -72,6 +92,11 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    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>;
+    onReportsChange(cb: () => void): () => void;
 }
 
 interface SourceConfig {
@@ -130,7 +155,7 @@ interface Annotation {
     /** JSX ancestor chain, outermost to innermost. Only populated for DOM-attribute kinds. */
     ancestors?: AnnotationAncestor[];
 }
-type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "flow";
+type MetadataExportKind = "page" | "feature" | "primitive" | "widget" | "region" | "flow";
 interface MetadataExport {
     source: "ts-export";
     kind: MetadataExportKind;
@@ -351,6 +376,7 @@ declare namespace Uidex {
     interface Feature<FeatureIds extends string = string> {
         feature: FeatureIds | false;
         name?: string;
+        features?: readonly FeatureIds[];
         acceptance?: readonly string[];
         description?: string;
     }

package/dist/scan/index.js

@@ -1,8 +1,8 @@
-// src/scan/discover.ts
+// src/scanner/scan/discover.ts
 import * as fs from "fs";
 import * as path from "path";
 
-// src/scan/config.ts
+// src/scanner/scan/config.ts
 var DEFAULT_TYPE_MODE = "strict";
 var WELL_KNOWN_FILES = {
   page: "uidex.page.ts",
@@ -166,7 +166,7 @@ var DEFAULT_CONVENTIONS = {
   regions: "landmarks"
 };
 
-// src/scan/discover.ts
+// src/scanner/scan/discover.ts
 var CONFIG_FILENAME = ".uidex.json";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -225,7 +225,7 @@ function discover(options = {}) {
   return results.sort((a, b) => a.configPath.localeCompare(b.configPath));
 }
 
-// src/scan/walk.ts
+// src/scanner/scan/walk.ts
 import * as fs2 from "fs";
 import * as path2 from "path";
 var DEFAULT_INCLUDES = ["**/*.{ts,tsx,js,jsx,mjs,cjs}"];
@@ -350,12 +350,13 @@ function* walkDir(root, dir) {
   }
 }
 
-// src/scan/extract-uidex-export.ts
+// src/scanner/scan/extract-uidex-export.ts
 var KIND_DISCRIMINATORS = [
   "page",
   "feature",
   "primitive",
   "widget",
+  "region",
   "flow",
   "notFlow"
 ];
@@ -368,15 +369,23 @@ var ALLOWED_FIELDS = {
     "acceptance",
     "description"
   ]),
-  feature: /* @__PURE__ */ new Set(["feature", "name", "acceptance", "description"]),
+  feature: /* @__PURE__ */ new Set([
+    "feature",
+    "name",
+    "features",
+    "acceptance",
+    "description"
+  ]),
   primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
   widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "description"]),
+  region: /* @__PURE__ */ new Set(["region", "name", "description"]),
   flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
 };
 var FALSEABLE = /* @__PURE__ */ new Set([
   "page",
   "feature",
-  "primitive"
+  "primitive",
+  "region"
 ]);
 var ExtractError = class extends Error {
   code;
@@ -1104,7 +1113,7 @@ function buildMetadata(value, file, headerPos, diagnostics) {
       line: pos.line
     });
   }
-  const features = kind === "page" ? readStringArrayField(byKey, "features") : void 0;
+  const features = kind === "page" || kind === "feature" ? readStringArrayField(byKey, "features") : void 0;
   const widgets = kind === "page" ? readStringArrayField(byKey, "widgets") : void 0;
   const notFlow = kind === "flow" && discriminator === "notFlow" ? true : void 0;
   const metadata = {
@@ -1199,7 +1208,7 @@ function posAt(content, offset) {
   return { offset, line, column: offset - lineStart + 1 };
 }
 
-// src/scan/jsx-ancestry.ts
+// src/scanner/scan/jsx-ancestry.ts
 var DATA_ATTR_RE = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
 function parseDataAttrs(tagSource) {
   if (!tagSource.includes("data-uidex")) return [];
@@ -1388,7 +1397,7 @@ function findTagEnd(content, start) {
   return -1;
 }
 
-// src/scan/extract.ts
+// src/scanner/scan/extract.ts
 var JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
 function lineAt(content, index) {
   let line = 1;
@@ -1491,10 +1500,10 @@ function extractOne(file) {
   return annotations;
 }
 
-// src/scan/resolve.ts
+// src/scanner/scan/resolve.ts
 import * as path3 from "path";
 
-// src/entities/types.ts
+// src/shared/entities/types.ts
 var ENTITY_KINDS = [
   "route",
   "page",
@@ -1527,7 +1536,7 @@ function assertEntityKind(kind) {
   if (!KIND_SET.has(kind)) throw new UnknownEntityKindError(kind);
 }
 
-// src/entities/registry.ts
+// src/shared/entities/registry.ts
 function emptyStore() {
   return {
     route: /* @__PURE__ */ new Map(),
@@ -1609,10 +1618,33 @@ function createRegistry() {
       return ids.has(entity.id);
     });
   };
-  return { add, get, list, query, byScope, touchedBy };
+  const reports = /* @__PURE__ */ new Map();
+  const reportsCbs = /* @__PURE__ */ new Set();
+  const setReports = (kind, id, records) => {
+    reports.set(`${kind}:${id}`, records);
+    for (const cb of reportsCbs) cb();
+  };
+  const getReports = (kind, id) => reports.get(`${kind}:${id}`) ?? [];
+  const listReportKeys = () => Array.from(reports.keys());
+  const onReportsChange = (cb) => {
+    reportsCbs.add(cb);
+    return () => reportsCbs.delete(cb);
+  };
+  return {
+    add,
+    get,
+    list,
+    query,
+    byScope,
+    touchedBy,
+    setReports,
+    getReports,
+    listReportKeys,
+    onReportsChange
+  };
 }
 
-// src/scan/routes.ts
+// src/scanner/scan/routes.ts
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var PAGES_ROUTER_BASENAME = /\.(tsx|ts|jsx|js|mjs|cjs)$/;
 var ROUTE_BASENAME = /^route\.(tsx|ts|jsx|js|mjs|cjs)$/;
@@ -1678,7 +1710,7 @@ function pathToId(routePath) {
   return routePath.replace(/^\/+/, "").replace(/\[\.{3}([^\]]+)\]/g, "$1").replace(/\[([^\]]+)\]/g, "$1").replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 
-// src/scan/resolve.ts
+// src/scanner/scan/resolve.ts
 var DOM_ATTR_KINDS = /* @__PURE__ */ new Set([
   "element",
   "region",
@@ -1985,6 +2017,21 @@ function resolve2(ctx) {
     };
     registry.add(region);
   }
+  for (const ef of ctx.extracted) {
+    const exp = exportFor(ef.file.displayPath, "region");
+    if (!exp) continue;
+    if (exp.id === false) continue;
+    if (typeof exp.id === "string" && !registry.get("region", exp.id)) {
+      const meta = buildMetaFromExport(exp);
+      const region = {
+        kind: "region",
+        id: exp.id,
+        loc: { file: ef.file.displayPath, line: exp.loc.line },
+        ...meta ? { meta } : {}
+      };
+      registry.add(region);
+    }
+  }
   const primitiveConventions = conventions.primitives;
   for (const ef of ctx.extracted) {
     const file = ef.file.displayPath;
@@ -2163,7 +2210,7 @@ function dedupe(arr) {
   return Array.from(new Set(arr));
 }
 
-// src/scan/audit.ts
+// src/scanner/scan/audit.ts
 import * as path4 from "path";
 var MARKER_FILENAMES = ["UIDEX_PAGE.md", "UIDEX_FEATURE.md"];
 function audit(opts) {
@@ -2293,17 +2340,38 @@ function audit(opts) {
     }
   }
   if (lint) {
+    const dynamicAttrRe = /\bdata-uidex(?:-(region|widget|primitive))?\s*=\s*\{/g;
     for (const f of files) {
-      const lines = f.content.split("\n");
-      const candidateRe = /<(button|a|input|select|textarea)(?=[\s/>])([^>]*)>/g;
       let m;
-      while ((m = candidateRe.exec(f.content)) !== null) {
-        const attrs = m[2];
-        if (attrs && attrs.includes("data-uidex")) continue;
-        const idx = m.index;
+      dynamicAttrRe.lastIndex = 0;
+      while ((m = dynamicAttrRe.exec(f.content)) !== null) {
+        const kind = m[1] ?? "element";
         let line = 1;
-        for (let i = 0; i < idx; i++) if (f.content[i] === "\n") line++;
-        void lines;
+        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
+        const attrName = m[1] ? `data-uidex-${m[1]}` : "data-uidex";
+        diagnostics.push({
+          code: "dynamic-attr",
+          severity: "warning",
+          message: `\`${attrName}={\u2026}\` uses a dynamic expression; the scanner cannot resolve the ${kind} id statically`,
+          file: f.displayPath,
+          line,
+          hint: dynamicAttrHint(kind)
+        });
+      }
+    }
+  }
+  if (lint) {
+    for (const f of files) {
+      const tagRe = /<(button|a|input|select|textarea)(?=[\s/>])/g;
+      let m;
+      while ((m = tagRe.exec(f.content)) !== null) {
+        const afterTag = m.index + m[0].length;
+        const closeIdx = findJsxOpeningEnd(f.content, afterTag);
+        if (closeIdx === -1) continue;
+        const attrs = f.content.slice(afterTag, closeIdx);
+        if (attrs.includes("data-uidex")) continue;
+        let line = 1;
+        for (let i = 0; i < m.index; i++) if (f.content[i] === "\n") line++;
         diagnostics.push({
           code: "missing-element-annotation",
           severity: "info",
@@ -2318,6 +2386,15 @@ function audit(opts) {
     const primitives = registry.list("primitive");
     const byName = /* @__PURE__ */ new Map();
     for (const p2 of primitives) byName.set(p2.id, p2);
+    const declaredFeatures = /* @__PURE__ */ new Map();
+    for (const ef of extracted) {
+      if (!ef.metadata) continue;
+      for (const m of ef.metadata) {
+        if (m.features && m.features.length > 0) {
+          declaredFeatures.set(ef.file.displayPath, new Set(m.features));
+        }
+      }
+    }
     for (const f of files) {
       const importRe = /import\s+(?:[^'"]+)\s+from\s+['"]([^'"]+)['"]/g;
       let m;
@@ -2332,14 +2409,19 @@ function audit(opts) {
         if (!scope) continue;
         const [kind, id] = scope.split(":");
         const importerSegments = f.displayPath.split("/");
-        if (!importerSegments.includes(id) || !importerSegments.includes(kind + "s")) {
-          diagnostics.push({
-            code: "scope-leak",
-            severity: "warning",
-            message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${f.displayPath}`,
-            file: f.displayPath
-          });
+        if (importerSegments.includes(id) && importerSegments.includes(kind + "s")) {
+          continue;
+        }
+        if (kind === "feature" && importerSegments.includes(id)) continue;
+        if (kind === "feature" && declaredFeatures.get(f.displayPath)?.has(id)) {
+          continue;
         }
+        diagnostics.push({
+          code: "scope-leak",
+          severity: "warning",
+          message: `Primitive "${primitive.id}" is scoped to ${scope} but is imported from ${f.displayPath}`,
+          file: f.displayPath
+        });
       }
     }
   }
@@ -2499,6 +2581,63 @@ function extractEntitiesArray(source) {
   }
   return null;
 }
+function findJsxOpeningEnd(src, start) {
+  let i = start;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === ">" || ch === "/" && src[i + 1] === ">") return i;
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipString2(src, i);
+    } else if (ch === "{") {
+      i = skipBraces(src, i);
+    } else {
+      i++;
+    }
+  }
+  return -1;
+}
+function skipString2(src, start) {
+  const quote = src[start];
+  let i = start + 1;
+  while (i < src.length) {
+    if (src[i] === "\\" && quote !== "`") {
+      i += 2;
+      continue;
+    }
+    if (quote === "`" && src[i] === "$" && src[i + 1] === "{") {
+      i = skipBraces(src, i + 1);
+      continue;
+    }
+    if (src[i] === quote) return i + 1;
+    i++;
+  }
+  return i;
+}
+function skipBraces(src, start) {
+  let depth = 1;
+  let i = start + 1;
+  while (i < src.length && depth > 0) {
+    const ch = src[i];
+    if (ch === "{") {
+      depth++;
+      i++;
+    } else if (ch === "}") {
+      depth--;
+      i++;
+    } else if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipString2(src, i);
+    } else {
+      i++;
+    }
+  }
+  return i;
+}
+function dynamicAttrHint(kind) {
+  if (kind === "region") {
+    return `Use a string literal: \`data-uidex-region="id"\`, or declare the region via \`export const uidex = { region: "id" } as const satisfies Uidex.Region\` on the file that passes the region value`;
+  }
+  return `The scanner requires string-literal attribute values. If this component forwards the annotation via a prop, restructure so the caller provides the annotated element directly (e.g. via a slot or render prop) with a string-literal \`data-uidex\` attribute`;
+}
 function stableStringify(value) {
   return JSON.stringify(value, stableReplacer);
 }
@@ -2513,7 +2652,7 @@ function stableReplacer(_key, value) {
   return value;
 }
 
-// src/scan/emit.ts
+// src/scanner/scan/emit.ts
 function sortById(arr) {
   return [...arr].sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -2637,6 +2776,7 @@ function emit(opts) {
   lines.push("  export interface Feature {");
   lines.push("    feature: FeatureId | false");
   lines.push("    name?: string");
+  lines.push("    features?: readonly FeatureId[]");
   lines.push("    acceptance?: readonly string[]");
   lines.push("    description?: string");
   lines.push("  }");
@@ -2651,6 +2791,11 @@ function emit(opts) {
   lines.push("    acceptance?: readonly string[]");
   lines.push("    description?: string");
   lines.push("  }");
+  lines.push("  export interface Region {");
+  lines.push("    region: RegionId | false");
+  lines.push("    name?: string");
+  lines.push("    description?: string");
+  lines.push("  }");
   lines.push("  export interface Flow {");
   lines.push("    flow: FlowId");
   lines.push("    name?: string");
@@ -2693,7 +2838,7 @@ function emit(opts) {
   return lines.join("\n");
 }
 
-// src/scan/git.ts
+// src/scanner/scan/git.ts
 import { execSync } from "child_process";
 function runGit(args, cwd) {
   try {
@@ -2725,7 +2870,7 @@ function parseGitHubRef(ref) {
   return m ? m[1] : null;
 }
 
-// src/scan/scaffold.ts
+// src/scanner/scan/scaffold.ts
 import * as fs3 from "fs";
 import * as path5 from "path";
 function scaffoldWidgetSpec(opts) {
@@ -2788,7 +2933,7 @@ function renderSpec(args) {
   return lines.join("\n");
 }
 
-// src/scan/pipeline.ts
+// src/scanner/scan/pipeline.ts
 import * as fs4 from "fs";
 import * as path6 from "path";
 function runScan(opts = {}) {
@@ -2862,18 +3007,18 @@ function writeScanResult(result) {
   fs4.writeFileSync(result.outputPath, result.generated, "utf8");
 }
 
-// src/scan/cli.ts
+// src/scanner/scan/cli.ts
 import * as fs7 from "fs";
 import * as path9 from "path";
 
-// src/scan/ai/index.ts
+// src/scanner/scan/ai/index.ts
 import * as p from "@clack/prompts";
 
-// src/scan/ai/providers/claude.ts
+// src/scanner/scan/ai/providers/claude.ts
 import * as fs6 from "fs";
 import * as path8 from "path";
 
-// src/scan/ai/templates.ts
+// src/scanner/scan/ai/templates.ts
 import * as fs5 from "fs";
 import * as path7 from "path";
 function templatePath(rel) {
@@ -2900,15 +3045,16 @@ function readTemplate(rel) {
   return fs5.readFileSync(templatePath(rel), "utf8");
 }
 
-// src/scan/ai/providers/claude.ts
+// src/scanner/scan/ai/providers/claude.ts
 var CLAUDE_FILES = [
   { dest: ".claude/rules/uidex.md", template: "claude/rules.md" },
-  { dest: ".claude/commands/uidex/audit.md", template: "claude/audit.md" }
+  { dest: ".claude/commands/uidex/audit.md", template: "claude/audit.md" },
+  { dest: ".claude/commands/uidex/api.md", template: "claude/api.md" }
 ];
 var claudeProvider = {
   id: "claude",
   label: "Claude Code",
-  description: "Adds .claude/rules/uidex.md and the /uidex:audit slash command.",
+  description: "Adds .claude/rules/uidex.md, /uidex:audit, and /uidex:api slash commands.",
   async install({ cwd, force }) {
     const changes = [];
     for (const file of CLAUDE_FILES) {
@@ -2956,13 +3102,13 @@ function cleanupEmpty(dir) {
   }
 }
 
-// src/scan/ai/providers/index.ts
+// src/scanner/scan/ai/providers/index.ts
 var PROVIDERS = [claudeProvider];
 function getProvider(id) {
   return PROVIDERS.find((p2) => p2.id === id);
 }
 
-// src/scan/ai/index.ts
+// src/scanner/scan/ai/index.ts
 async function runAiCommand(opts) {
   const { cwd, argv } = opts;
   const sub = argv[0];
@@ -3073,8 +3219,8 @@ function err(exitCode, stderr) {
   return { exitCode, stdout: "", stderr };
 }
 
-// src/scan/cli.ts
-function parseFlags2(args) {
+// src/scanner/cli/parse-args.ts
+function parseArgs(args) {
   const positional = [];
   const flags = {};
   for (let i = 0; i < args.length; i++) {
@@ -3098,9 +3244,11 @@ function parseFlags2(args) {
   }
   return { positional, flags };
 }
+
+// src/scanner/scan/cli.ts
 async function run(opts) {
   const cwd = opts.cwd ?? process.cwd();
-  const { positional, flags } = parseFlags2(opts.argv);
+  const { positional, flags } = parseArgs(opts.argv);
   const command = positional[0] ?? "help";
   const writer = createWriter();
   try {
@@ -3144,6 +3292,10 @@ function helpText2() {
     "  scan [flags]          Run the scanner pipeline",
     "  scaffold widget <id>  Emit a Playwright spec from a widget's acceptance",
     "  ai <install|uninstall|providers>  Manage AI assistant integrations",
+    "  api <METHOD> <PATH>              Call the uidex API",
+    "  api --list                       Show available API routes",
+    "  api login                        Authenticate via browser",
+    "  api login --token <tok>          Store an auth token directly",
     "",
     "Flags:",
     "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",