uidex 0.2.4 → 0.3.0

package/dist/cli/cli.cjs

@@ -0,0 +1,3243 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/scan/cli.ts
+var fs7 = __toESM(require("fs"), 1);
+var path8 = __toESM(require("path"), 1);
+
+// src/scan/ai/index.ts
+var p = __toESM(require("@clack/prompts"), 1);
+
+// src/scan/ai/providers/claude.ts
+var fs2 = __toESM(require("fs"), 1);
+var path2 = __toESM(require("path"), 1);
+
+// src/scan/ai/templates.ts
+var fs = __toESM(require("fs"), 1);
+var path = __toESM(require("path"), 1);
+function templatePath(rel) {
+  const candidates = [
+    path.resolve(__dirname, "../../templates", rel),
+    // dist/cli/cli.cjs    → ../../templates
+    path.resolve(__dirname, "../../../templates", rel)
+    // src/scan/ai/foo.ts → ../../../templates
+  ];
+  for (const c of candidates) {
+    try {
+      fs.accessSync(c, fs.constants.R_OK);
+      return c;
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(
+    `uidex: template not found: ${rel}. Looked in:
+  ${candidates.join("\n  ")}`
+  );
+}
+function readTemplate(rel) {
+  return fs.readFileSync(templatePath(rel), "utf8");
+}
+
+// src/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" }
+];
+var claudeProvider = {
+  id: "claude",
+  label: "Claude Code",
+  description: "Adds .claude/rules/uidex.md and the /uidex:audit slash command.",
+  async install({ cwd, force }) {
+    const changes = [];
+    for (const file of CLAUDE_FILES) {
+      const dest = path2.join(cwd, file.dest);
+      const exists = fs2.existsSync(dest);
+      if (exists && !force) {
+        changes.push({
+          path: file.dest,
+          action: "skipped",
+          reason: "exists (use --force to overwrite)"
+        });
+        continue;
+      }
+      fs2.mkdirSync(path2.dirname(dest), { recursive: true });
+      fs2.writeFileSync(dest, readTemplate(file.template));
+      changes.push({
+        path: file.dest,
+        action: exists ? "overwritten" : "created"
+      });
+    }
+    return { changes };
+  },
+  async uninstall({ cwd }) {
+    const changes = [];
+    for (const file of CLAUDE_FILES) {
+      const dest = path2.join(cwd, file.dest);
+      if (!fs2.existsSync(dest)) {
+        changes.push({ path: file.dest, action: "skipped", reason: "absent" });
+        continue;
+      }
+      fs2.unlinkSync(dest);
+      changes.push({ path: file.dest, action: "removed" });
+    }
+    cleanupEmpty(path2.join(cwd, ".claude/commands/uidex"));
+    cleanupEmpty(path2.join(cwd, ".claude/commands"));
+    cleanupEmpty(path2.join(cwd, ".claude/rules"));
+    return { changes };
+  }
+};
+function cleanupEmpty(dir) {
+  try {
+    const entries = fs2.readdirSync(dir);
+    if (entries.length === 0) fs2.rmdirSync(dir);
+  } catch {
+  }
+}
+
+// src/scan/ai/providers/index.ts
+var PROVIDERS = [claudeProvider];
+function getProvider(id) {
+  return PROVIDERS.find((p2) => p2.id === id);
+}
+
+// src/scan/ai/index.ts
+async function runAiCommand(opts) {
+  const { cwd, argv } = opts;
+  const sub = argv[0];
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    return out(0, helpText());
+  }
+  if (sub === "providers") {
+    return out(
+      0,
+      PROVIDERS.map((pr) => `  ${pr.id.padEnd(10)} ${pr.label}`).join("\n") + "\n"
+    );
+  }
+  if (sub !== "install" && sub !== "uninstall") {
+    return err(1, `Unknown ai subcommand: ${sub}
+
+${helpText()}`);
+  }
+  const flags = parseFlags(argv.slice(1));
+  const provider = await selectProvider(opts, flags.provider);
+  if (!provider) return out(0, "Cancelled.\n");
+  if (sub === "install") {
+    const result2 = await provider.install({
+      cwd,
+      force: flags.force === true
+    });
+    return out(0, formatChanges(provider, "Installed", result2));
+  }
+  const result = await provider.uninstall({ cwd });
+  return out(0, formatChanges(provider, "Uninstalled", result));
+}
+async function selectProvider(opts, explicit) {
+  if (explicit) {
+    const found = getProvider(explicit);
+    if (!found) {
+      throw new Error(
+        `Unknown provider: ${explicit}. Run 'uidex ai providers' to list.`
+      );
+    }
+    return found;
+  }
+  if (PROVIDERS.length === 1) return PROVIDERS[0];
+  if (opts.nonInteractive) {
+    throw new Error(
+      "Multiple providers available; pass --provider <id> in non-interactive mode."
+    );
+  }
+  if (opts.prompt?.selectProvider) {
+    const id = await opts.prompt.selectProvider(PROVIDERS);
+    return id ? getProvider(id) ?? null : null;
+  }
+  const choice = await p.select({
+    message: "Which AI assistant?",
+    options: PROVIDERS.map((pr) => ({
+      value: pr.id,
+      label: pr.label,
+      hint: pr.description
+    }))
+  });
+  if (p.isCancel(choice)) return null;
+  return getProvider(choice) ?? null;
+}
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--force") flags.force = true;
+    else if (a === "--provider" || a === "-p") flags.provider = args[++i];
+    else if (a.startsWith("--provider=")) flags.provider = a.slice(11);
+  }
+  return flags;
+}
+function formatChanges(provider, verb, result) {
+  const lines = [`${verb} ${provider.label}:`];
+  for (const c of result.changes) lines.push(`  ${describe(c)}`);
+  return lines.join("\n") + "\n";
+}
+function describe(c) {
+  switch (c.action) {
+    case "created":
+      return `+ ${c.path}`;
+    case "overwritten":
+      return `~ ${c.path}`;
+    case "removed":
+      return `- ${c.path}`;
+    case "skipped":
+      return `\xB7 ${c.path}${c.reason ? `  (${c.reason})` : ""}`;
+  }
+}
+function helpText() {
+  return [
+    "uidex ai \u2014 install AI assistant integrations",
+    "",
+    "Subcommands:",
+    "  install               Install an AI integration into the current repo",
+    "  uninstall             Remove an AI integration from the current repo",
+    "  providers             List available providers",
+    "",
+    "Flags:",
+    "  --provider <id>, -p   Skip the prompt and pick a provider by id",
+    "  --force               (install) overwrite existing files",
+    ""
+  ].join("\n");
+}
+function out(exitCode, stdout) {
+  return { exitCode, stdout, stderr: "" };
+}
+function err(exitCode, stderr) {
+  return { exitCode, stdout: "", stderr };
+}
+
+// src/scan/discover.ts
+var fs3 = __toESM(require("fs"), 1);
+var path3 = __toESM(require("path"), 1);
+
+// src/scan/config.ts
+var DEFAULT_TYPE_MODE = "strict";
+var ConfigError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+};
+var LEGACY_KEYS = /* @__PURE__ */ new Set([
+  "scanner",
+  "defaults",
+  "colors",
+  "components",
+  "triggerElement",
+  "devtools"
+]);
+var ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "$schema",
+  "sources",
+  "exclude",
+  "output",
+  "flows",
+  "typeMode",
+  "audit",
+  "conventions"
+]);
+var ALLOWED_TYPE_MODES = /* @__PURE__ */ new Set(["strict", "loose"]);
+var ALLOWED_SOURCE_KEYS = /* @__PURE__ */ new Set(["rootDir", "include", "exclude", "prefix"]);
+var ALLOWED_CONVENTIONS_KEYS = /* @__PURE__ */ new Set([
+  "primitives",
+  "features",
+  "pages",
+  "flows",
+  "regions"
+]);
+var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set(["scopeLeak", "coverage", "acceptance"]);
+function fail(msg) {
+  throw new ConfigError(`Invalid .uidex.json: ${msg}`);
+}
+function assertObject(value, path9) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail(`${path9} must be an object`);
+  }
+}
+function assertStringArray(value, path9) {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
+    fail(`${path9} must be a string[]`);
+  }
+}
+function validateConfig(raw) {
+  assertObject(raw, "root");
+  for (const key of Object.keys(raw)) {
+    if (LEGACY_KEYS.has(key)) {
+      fail(
+        `legacy nested key "${key}" is not supported; v2 uses a flat schema (sources[], output, flows, audit, conventions)`
+      );
+    }
+    if (!ALLOWED_TOP_LEVEL_KEYS.has(key)) {
+      fail(`unknown top-level key "${key}"`);
+    }
+  }
+  if (!("sources" in raw)) {
+    fail(
+      `required key "sources" is missing (must be an array with at least one entry)`
+    );
+  }
+  const sources = raw.sources;
+  if (!Array.isArray(sources) || sources.length === 0) {
+    fail(`"sources" must be a non-empty array`);
+  }
+  const validatedSources = sources.map((src, i) => {
+    assertObject(src, `sources[${i}]`);
+    for (const key of Object.keys(src)) {
+      if (!ALLOWED_SOURCE_KEYS.has(key)) {
+        fail(`unknown key "${key}" in sources[${i}]`);
+      }
+    }
+    if (typeof src.rootDir !== "string" || src.rootDir.length === 0) {
+      fail(`sources[${i}].rootDir must be a non-empty string`);
+    }
+    if (src.include !== void 0)
+      assertStringArray(src.include, `sources[${i}].include`);
+    if (src.exclude !== void 0)
+      assertStringArray(src.exclude, `sources[${i}].exclude`);
+    if (src.prefix !== void 0 && typeof src.prefix !== "string") {
+      fail(`sources[${i}].prefix must be a string`);
+    }
+    return src;
+  });
+  if (typeof raw.output !== "string" || raw.output.length === 0) {
+    fail(`"output" must be a non-empty string`);
+  }
+  if (raw.exclude !== void 0) assertStringArray(raw.exclude, `exclude`);
+  if (raw.flows !== void 0) assertStringArray(raw.flows, `flows`);
+  if (raw.typeMode !== void 0) {
+    if (typeof raw.typeMode !== "string" || !ALLOWED_TYPE_MODES.has(raw.typeMode)) {
+      fail(`"typeMode" must be "strict" or "loose"`);
+    }
+  }
+  if (raw.audit !== void 0) {
+    assertObject(raw.audit, "audit");
+    for (const key of Object.keys(raw.audit)) {
+      if (!ALLOWED_AUDIT_KEYS.has(key)) fail(`unknown key "${key}" in audit`);
+      const v = raw.audit[key];
+      if (typeof v !== "boolean") fail(`audit.${key} must be a boolean`);
+    }
+  }
+  if (raw.conventions !== void 0) {
+    assertObject(raw.conventions, "conventions");
+    const c = raw.conventions;
+    for (const key of Object.keys(c)) {
+      if (!ALLOWED_CONVENTIONS_KEYS.has(key)) {
+        fail(`unknown key "${key}" in conventions`);
+      }
+    }
+    if (c.primitives !== void 0 && c.primitives !== false) {
+      assertStringArray(c.primitives, "conventions.primitives");
+    }
+    if (c.features !== void 0 && c.features !== false && typeof c.features !== "string") {
+      fail(`conventions.features must be a string or false`);
+    }
+    if (c.pages !== void 0 && c.pages !== false && c.pages !== "auto") {
+      fail(`conventions.pages must be "auto" or false`);
+    }
+    if (c.flows !== void 0 && c.flows !== false) {
+      assertStringArray(c.flows, "conventions.flows");
+    }
+    if (c.regions !== void 0 && c.regions !== false && c.regions !== "landmarks") {
+      fail(`conventions.regions must be "landmarks" or false`);
+    }
+  }
+  return {
+    $schema: typeof raw.$schema === "string" ? raw.$schema : void 0,
+    sources: validatedSources,
+    exclude: raw.exclude,
+    output: raw.output,
+    flows: raw.flows,
+    typeMode: raw.typeMode ?? DEFAULT_TYPE_MODE,
+    audit: raw.audit,
+    conventions: raw.conventions
+  };
+}
+function parseConfig(json) {
+  let raw;
+  try {
+    raw = JSON.parse(json);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new ConfigError(`Invalid .uidex.json: JSON parse error: ${msg}`);
+  }
+  return validateConfig(raw);
+}
+var DEFAULT_CONVENTIONS = {
+  primitives: ["src/ui/**", "src/components/ui/**"],
+  features: "src/features/*",
+  pages: "auto",
+  flows: ["e2e/**/*.spec.ts"],
+  regions: "landmarks"
+};
+
+// src/scan/discover.ts
+var CONFIG_FILENAME = ".uidex.json";
+var SKIP_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".turbo",
+  ".cache",
+  "coverage"
+]);
+var MAX_DEPTH = 4;
+function tryReadConfig(configPath) {
+  let source;
+  try {
+    source = fs3.readFileSync(configPath, "utf8");
+  } catch {
+    return null;
+  }
+  return {
+    configPath,
+    configDir: path3.dirname(configPath),
+    config: parseConfig(source)
+  };
+}
+function discover(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const maxDepth = options.maxDepth ?? MAX_DEPTH;
+  const rootMatch = tryReadConfig(path3.join(cwd, CONFIG_FILENAME));
+  if (rootMatch) return [rootMatch];
+  const results = [];
+  const queue = [[cwd, 0]];
+  while (queue.length > 0) {
+    const [dir, depth] = queue.shift();
+    let entries;
+    try {
+      entries = fs3.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name)) continue;
+      if (entry.name.startsWith(".")) continue;
+      const childDir = path3.join(dir, entry.name);
+      const candidate = tryReadConfig(path3.join(childDir, CONFIG_FILENAME));
+      if (candidate) {
+        results.push(candidate);
+        continue;
+      }
+      if (depth + 1 < maxDepth) {
+        queue.push([childDir, depth + 1]);
+      }
+    }
+  }
+  return results.sort((a, b) => a.configPath.localeCompare(b.configPath));
+}
+
+// src/scan/pipeline.ts
+var fs5 = __toESM(require("fs"), 1);
+var path6 = __toESM(require("path"), 1);
+
+// src/entities/types.ts
+var ENTITY_KINDS = [
+  "route",
+  "page",
+  "feature",
+  "widget",
+  "region",
+  "element",
+  "primitive",
+  "flow"
+];
+function isMetaKind(kind) {
+  return kind !== "route" && kind !== "flow";
+}
+function isMetaEntity(entity) {
+  return isMetaKind(entity.kind);
+}
+function entityKey(entity) {
+  return entity.kind === "route" ? entity.path : entity.id;
+}
+var UnknownEntityKindError = class extends Error {
+  kind;
+  constructor(kind) {
+    super(`Unknown entity kind: ${kind}`);
+    this.name = "UnknownEntityKindError";
+    this.kind = kind;
+  }
+};
+var KIND_SET = new Set(ENTITY_KINDS);
+function assertEntityKind(kind) {
+  if (!KIND_SET.has(kind)) throw new UnknownEntityKindError(kind);
+}
+
+// src/entities/registry.ts
+function emptyStore() {
+  return {
+    route: /* @__PURE__ */ new Map(),
+    page: /* @__PURE__ */ new Map(),
+    feature: /* @__PURE__ */ new Map(),
+    widget: /* @__PURE__ */ new Map(),
+    region: /* @__PURE__ */ new Map(),
+    element: /* @__PURE__ */ new Map(),
+    primitive: /* @__PURE__ */ new Map(),
+    flow: /* @__PURE__ */ new Map()
+  };
+}
+function computeFlowIds(flows, targetId) {
+  const ids = [];
+  for (const flow of flows) {
+    if (flow.touches.includes(targetId)) ids.push(flow.id);
+  }
+  return ids;
+}
+function freezeEntity(entity, flows) {
+  if (!isMetaKind(entity.kind)) return entity;
+  const withMeta = entity;
+  if (withMeta.meta === void 0) return entity;
+  const computedFlows = Object.freeze(computeFlowIds(flows, withMeta.id));
+  const mergedMeta = { ...withMeta.meta, flows: computedFlows };
+  return { ...entity, meta: Object.freeze(mergedMeta) };
+}
+function createRegistry() {
+  const store = emptyStore();
+  let flowsCache = null;
+  const getFlows = () => {
+    if (flowsCache === null) flowsCache = Array.from(store.flow.values());
+    return flowsCache;
+  };
+  const add = (entity) => {
+    assertEntityKind(entity.kind);
+    const key = entityKey(entity);
+    store[entity.kind].set(key, entity);
+    flowsCache = null;
+  };
+  const get = (kind, id) => {
+    assertEntityKind(kind);
+    const raw = store[kind].get(id);
+    if (raw === void 0) return void 0;
+    return freezeEntity(raw, getFlows());
+  };
+  const list = (kind) => {
+    assertEntityKind(kind);
+    const flows = getFlows();
+    return Array.from(
+      store[kind].values(),
+      (e) => freezeEntity(e, flows)
+    );
+  };
+  const allEntities = function* () {
+    for (const kind of Object.keys(store)) {
+      for (const entity of store[kind].values()) {
+        yield entity;
+      }
+    }
+  };
+  const query = (predicate) => {
+    const flows = getFlows();
+    const result = [];
+    for (const entity of allEntities()) {
+      if (predicate(entity)) result.push(freezeEntity(entity, flows));
+    }
+    return result;
+  };
+  const byScope = (scope) => query(
+    (entity) => "scopes" in entity && Array.isArray(entity.scopes) && entity.scopes.includes(scope)
+  );
+  const touchedBy = (flowId) => {
+    const flow = store.flow.get(flowId);
+    if (flow === void 0) return [];
+    const ids = new Set(flow.touches);
+    return query((entity) => {
+      if (!isMetaEntity(entity)) return false;
+      return ids.has(entity.id);
+    });
+  };
+  return { add, get, list, query, byScope, touchedBy };
+}
+
+// src/scan/audit.ts
+var MARKER_FILENAMES = ["UIDEX_PAGE.md", "UIDEX_FEATURE.md"];
+function audit(opts) {
+  const diagnostics = [];
+  const { registry, extracted, files, config } = opts;
+  const check = opts.check ?? false;
+  const lint = opts.lint ?? false;
+  const acceptanceEnabled = config.audit?.acceptance ?? true;
+  const scopeLeakEnabled = config.audit?.scopeLeak ?? true;
+  const coverageEnabled = config.audit?.coverage ?? true;
+  if (opts.resolveDiagnostics) diagnostics.push(...opts.resolveDiagnostics);
+  if (check) {
+    for (const f of files) {
+      const base = f.displayPath.split("/").pop() ?? "";
+      if (MARKER_FILENAMES.includes(base)) {
+        diagnostics.push({
+          code: "marker-md-ignored",
+          severity: "warning",
+          message: `Marker file "${base}" is ignored in v2; migrate to \`export const uidex\``,
+          file: f.displayPath
+        });
+      }
+    }
+  }
+  if (check && opts.generated !== void 0) {
+    const outRel = opts.outputPath ?? config.output;
+    const fresh = normalizeLineEndings(opts.generated);
+    if (opts.existingOnDisk === null || opts.existingOnDisk === void 0) {
+      diagnostics.push({
+        code: "gen-missing",
+        severity: "error",
+        message: `Generated file "${outRel}" does not exist on disk; run \`uidex scan\` and commit the result`,
+        file: outRel,
+        hint: "Run `uidex scan` (without --check) to regenerate"
+      });
+    } else {
+      const existing = normalizeLineEndings(opts.existingOnDisk);
+      if (existing !== fresh) {
+        const changed = diffEntities(existing, opts.generated, registry);
+        const summary2 = formatChangedSummary(changed);
+        diagnostics.push({
+          code: "gen-stale",
+          severity: "error",
+          message: `Generated file "${outRel}" is stale${summary2 ? `; ${summary2}` : ""}`,
+          file: outRel,
+          hint: "Run `uidex scan` (without --check) to regenerate and commit the result"
+        });
+      }
+    }
+  }
+  if (lint) {
+    for (const ef of extracted) {
+      for (const a of ef.annotations) {
+        const migration = legacyJsdocMigration(a);
+        if (!migration) continue;
+        diagnostics.push({
+          code: "legacy-jsdoc",
+          severity: "warning",
+          message: migration.message,
+          file: a.file,
+          line: a.line,
+          hint: migration.hint
+        });
+      }
+    }
+  }
+  if (lint && acceptanceEnabled) {
+    for (const kind of ["widget", "feature", "page"]) {
+      for (const e of registry.list(kind)) {
+        const criteria = e.meta?.acceptance ?? [];
+        if (criteria.length === 0) {
+          if (kind === "widget") {
+            diagnostics.push({
+              code: "widget-missing-acceptance",
+              severity: "warning",
+              message: `Widget "${e.id}" has no acceptance metadata; add \`export const uidex = { widget: "${e.id}", acceptance: [...] }\` at the widget's definition site`,
+              file: e.loc?.file,
+              line: e.loc?.line,
+              entity: { kind, id: e.id },
+              hint: `Adding acceptance criteria allows \`uidex scaffold widget ${e.id}\` to generate a Playwright spec`
+            });
+          }
+          continue;
+        }
+        const flowIds = e.meta?.flows ?? [];
+        if (flowIds.length === 0) {
+          const hint = kind === "widget" ? `uidex scaffold widget ${e.id}` : `Add a Playwright flow under e2e/** that touches ${kind} "${e.id}" (tag the describe with @uidex:flow)`;
+          for (const c of criteria) {
+            diagnostics.push({
+              code: "acceptance-uncovered",
+              severity: "warning",
+              message: `${kind} "${e.id}" has acceptance criterion not covered by any flow: "${c}"`,
+              file: e.loc?.file,
+              line: e.loc?.line,
+              entity: { kind, id: e.id },
+              hint
+            });
+          }
+        }
+      }
+    }
+  }
+  if (lint) {
+    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;
+        let line = 1;
+        for (let i = 0; i < idx; i++) if (f.content[i] === "\n") line++;
+        void lines;
+        diagnostics.push({
+          code: "missing-element-annotation",
+          severity: "info",
+          message: `Interactive <${m[1].toLowerCase()}> without data-uidex annotation`,
+          file: f.displayPath,
+          line
+        });
+      }
+    }
+  }
+  if (lint && scopeLeakEnabled) {
+    const primitives = registry.list("primitive");
+    const byName = /* @__PURE__ */ new Map();
+    for (const p2 of primitives) byName.set(p2.id, p2);
+    for (const f of files) {
+      const importRe = /import\s+(?:[^'"]+)\s+from\s+['"]([^'"]+)['"]/g;
+      let m;
+      while ((m = importRe.exec(f.content)) !== null) {
+        const spec = m[1];
+        const baseName2 = spec.split("/").pop() ?? "";
+        const primitive = byName.get(
+          baseName2.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()
+        );
+        if (!primitive) continue;
+        const scope = primitive.scopes?.[0] ?? "global";
+        if (scope === "global") 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 (lint && coverageEnabled) {
+    for (const flow of registry.list("flow")) {
+      for (const touchedId of flow.touches) {
+        const found = registry.get("element", touchedId) ?? registry.get("widget", touchedId) ?? registry.get("region", touchedId);
+        if (!found) {
+          diagnostics.push({
+            code: "unknown-reference",
+            severity: "warning",
+            message: `Flow "${flow.id}" references unknown entity "${touchedId}"`,
+            file: flow.loc.file,
+            line: flow.loc.line
+          });
+        }
+      }
+    }
+  }
+  const summary = {
+    errors: diagnostics.filter((d) => d.severity === "error").length,
+    warnings: diagnostics.filter((d) => d.severity === "warning").length
+  };
+  return { diagnostics, summary };
+}
+function legacyJsdocMigration(a) {
+  const quote = (s) => JSON.stringify(s);
+  const arr = (xs) => xs && xs.length > 0 ? `[${xs.map(quote).join(", ")}]` : "";
+  const entityHint = (kind) => {
+    const uidexKind = kind.charAt(0).toUpperCase() + kind.slice(1);
+    const parts = [`${kind}: ${quote(a.id)}`];
+    if (a.acceptance?.length) parts.push(`acceptance: ${arr(a.acceptance)}`);
+    return {
+      message: `Legacy JSDoc tag \`@uidex ${kind} ${a.id}\` is no longer recognised; migrate to \`export const uidex\``,
+      hint: `Replace with: export const uidex = { ${parts.join(", ")} } as const satisfies Uidex.${uidexKind}`
+    };
+  };
+  switch (a.kind) {
+    case "page-doc":
+      return entityHint("page");
+    case "feature-doc":
+      return entityHint("feature");
+    case "widget-doc":
+      return entityHint("widget");
+    case "not-flow":
+      return {
+        message: `Legacy JSDoc tag \`@uidex:not-flow\` is no longer recognised; migrate to \`export const uidex\``,
+        hint: `Replace with: export const uidex = { notFlow: true } as const satisfies Uidex.NotFlow`
+      };
+    case "orphan-acceptance":
+      return {
+        message: `Legacy JSDoc tag \`@acceptance\` is no longer recognised; migrate to the \`acceptance\` field on \`export const uidex\``,
+        hint: `Replace with: export const uidex = { /* kind */, acceptance: ${arr(a.acceptance)} } as const`
+      };
+    default:
+      return null;
+  }
+}
+function normalizeLineEndings(s) {
+  return s.replace(/\r\n/g, "\n");
+}
+function formatChangedSummary(change) {
+  const parts = [];
+  const fmt = (kind, names) => {
+    if (names.length === 0) return;
+    const preview = names.slice(0, 3).join(", ");
+    const suffix = names.length > 3 ? ` (+${names.length - 3} more)` : "";
+    parts.push(`${kind}: ${preview}${suffix}`);
+  };
+  fmt("added", change.added);
+  fmt("removed", change.removed);
+  fmt("modified", change.modified);
+  return parts.join("; ");
+}
+function diffEntities(existing, generated, registry) {
+  const oldEntities = extractEntitiesArray(existing);
+  const newEntities = extractEntitiesArray(generated) ?? freshEntities(registry);
+  const added = [];
+  const removed = [];
+  const modified = [];
+  if (!oldEntities) {
+    for (const e of newEntities) added.push(labelFor(e));
+    return { added, removed, modified };
+  }
+  const oldByKey = /* @__PURE__ */ new Map();
+  for (const e of oldEntities) oldByKey.set(entityKey(e) + "@" + e.kind, e);
+  const newByKey = /* @__PURE__ */ new Map();
+  for (const e of newEntities) newByKey.set(entityKey(e) + "@" + e.kind, e);
+  for (const [k, e] of newByKey) {
+    const prev = oldByKey.get(k);
+    if (!prev) {
+      added.push(labelFor(e));
+    } else if (stableStringify(prev) !== stableStringify(e)) {
+      modified.push(labelFor(e));
+    }
+  }
+  for (const [k, e] of oldByKey) {
+    if (!newByKey.has(k)) removed.push(labelFor(e));
+  }
+  return { added, removed, modified };
+}
+function labelFor(e) {
+  return `${e.kind} "${entityKey(e)}"`;
+}
+function freshEntities(registry) {
+  const kinds = [
+    "route",
+    "page",
+    "feature",
+    "widget",
+    "region",
+    "element",
+    "primitive",
+    "flow"
+  ];
+  const out2 = [];
+  for (const k of kinds) out2.push(...registry.list(k));
+  return out2;
+}
+function extractEntitiesArray(source) {
+  const marker = "export const entities: ReadonlyArray<Entity> = ";
+  const idx = source.indexOf(marker);
+  if (idx === -1) return null;
+  const start = source.indexOf("[", idx);
+  if (start === -1) return null;
+  let depth = 0;
+  let inStr = null;
+  let escaped = false;
+  for (let i = start; i < source.length; i++) {
+    const c = source[i];
+    if (inStr) {
+      if (escaped) {
+        escaped = false;
+      } else if (c === "\\") {
+        escaped = true;
+      } else if (c === inStr) {
+        inStr = null;
+      }
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      inStr = c;
+      continue;
+    }
+    if (c === "[") depth++;
+    else if (c === "]") {
+      depth--;
+      if (depth === 0) {
+        const json = source.slice(start, i + 1);
+        try {
+          return JSON.parse(json);
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+function stableStringify(value) {
+  return JSON.stringify(value, stableReplacer);
+}
+function stableReplacer(_key, value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = value[k];
+    }
+    return sorted;
+  }
+  return value;
+}
+
+// src/scan/emit.ts
+function sortById(arr) {
+  return [...arr].sort((a, b) => a.id.localeCompare(b.id));
+}
+function jsonStable(value, indent = 2) {
+  return JSON.stringify(value, replacerSorted, indent);
+}
+function replacerSorted(_key, value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const sorted = {};
+    for (const k of Object.keys(value).sort()) {
+      sorted[k] = value[k];
+    }
+    return sorted;
+  }
+  return value;
+}
+function emitIdUnion(name, ids, typeMode) {
+  if (typeMode === "loose") return `export type ${name} = string
+`;
+  if (ids.length === 0) return `export type ${name} = never
+`;
+  const sorted = [...ids].sort();
+  const body = sorted.map((id) => `  | ${JSON.stringify(id)}`).join("\n");
+  return `export type ${name} =
+${body}
+`;
+}
+function emit(opts) {
+  const {
+    registry,
+    gitContext,
+    uidexImport = "uidex",
+    typeMode = "strict"
+  } = opts;
+  const routes = [...registry.list("route")].sort(
+    (a, b) => a.path.localeCompare(b.path)
+  );
+  const pages = sortById(registry.list("page"));
+  const features = sortById(registry.list("feature"));
+  const widgets = sortById(registry.list("widget"));
+  const regions = sortById(registry.list("region"));
+  const elements = sortById(registry.list("element"));
+  const primitives = sortById(registry.list("primitive"));
+  const flows = sortById(registry.list("flow"));
+  const lines = [];
+  lines.push("// THIS FILE IS AUTO-GENERATED BY `uidex scan`. DO NOT EDIT.");
+  lines.push("/* eslint-disable */");
+  lines.push(`import { createUidex } from ${JSON.stringify(uidexImport)}`);
+  lines.push(
+    `import type { Entity, Registry } from ${JSON.stringify(uidexImport)}`
+  );
+  lines.push("");
+  lines.push("// ---- id unions ----");
+  lines.push(
+    emitIdUnion(
+      "PageId",
+      pages.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "FeatureId",
+      features.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "WidgetId",
+      widgets.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "RegionId",
+      regions.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "ElementId",
+      elements.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "PrimitiveId",
+      primitives.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "FlowId",
+      flows.map((e) => e.id),
+      typeMode
+    )
+  );
+  lines.push(
+    emitIdUnion(
+      "RouteId",
+      routes.map((e) => e.path),
+      typeMode
+    )
+  );
+  lines.push("");
+  lines.push("// ---- authoring-surface shape types ----");
+  lines.push("export namespace Uidex {");
+  lines.push("  export interface Page {");
+  lines.push("    page: PageId | false");
+  lines.push("    name?: string");
+  lines.push("    features?: readonly FeatureId[]");
+  lines.push("    widgets?: readonly WidgetId[]");
+  lines.push("    acceptance?: readonly string[]");
+  lines.push("    description?: string");
+  lines.push("  }");
+  lines.push("  export interface Feature {");
+  lines.push("    feature: FeatureId | false");
+  lines.push("    name?: string");
+  lines.push("    acceptance?: readonly string[]");
+  lines.push("    description?: string");
+  lines.push("  }");
+  lines.push("  export interface Primitive {");
+  lines.push("    primitive: PrimitiveId");
+  lines.push("    name?: string");
+  lines.push("    description?: string");
+  lines.push("  }");
+  lines.push("  export interface Widget {");
+  lines.push("    widget: WidgetId");
+  lines.push("    name?: string");
+  lines.push("    acceptance?: readonly string[]");
+  lines.push("    description?: string");
+  lines.push("  }");
+  lines.push("  export interface Flow {");
+  lines.push("    flow: FlowId");
+  lines.push("    name?: string");
+  lines.push("    description?: string");
+  lines.push("  }");
+  lines.push("  export interface NotFlow {");
+  lines.push("    notFlow: true");
+  lines.push("  }");
+  lines.push("}");
+  lines.push("");
+  lines.push("// ---- entities ----");
+  const allEntities = [
+    ...routes,
+    ...pages,
+    ...features,
+    ...widgets,
+    ...regions,
+    ...elements,
+    ...primitives,
+    ...flows
+  ];
+  lines.push(
+    `export const entities: ReadonlyArray<Entity> = ${jsonStable(allEntities)}`
+  );
+  lines.push("");
+  lines.push("// ---- git context ----");
+  const gc = gitContext ?? { branch: null, commit: null, pr: null };
+  lines.push(`export const gitContext = ${jsonStable(gc)} as const`);
+  lines.push("");
+  lines.push("// ---- registry factory ----");
+  lines.push("export function loadRegistry(target: Registry): Registry {");
+  lines.push("  for (const entity of entities) target.add(entity)");
+  lines.push("  return target");
+  lines.push("}");
+  lines.push("");
+  lines.push("// ---- preconfigured uidex instance ----");
+  lines.push("export const uidex = createUidex()");
+  lines.push("for (const entity of entities) uidex.registry.add(entity)");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/scan/extract-uidex-export.ts
+var KIND_DISCRIMINATORS = [
+  "page",
+  "feature",
+  "primitive",
+  "widget",
+  "flow",
+  "notFlow"
+];
+var ALLOWED_FIELDS = {
+  page: /* @__PURE__ */ new Set([
+    "page",
+    "name",
+    "features",
+    "widgets",
+    "acceptance",
+    "description"
+  ]),
+  feature: /* @__PURE__ */ new Set(["feature", "name", "acceptance", "description"]),
+  primitive: /* @__PURE__ */ new Set(["primitive", "name", "description"]),
+  widget: /* @__PURE__ */ new Set(["widget", "name", "acceptance", "description"]),
+  flow: /* @__PURE__ */ new Set(["flow", "notFlow", "name", "description"])
+};
+var FALSEABLE = /* @__PURE__ */ new Set([
+  "page",
+  "feature",
+  "primitive"
+]);
+var ExtractError = class extends Error {
+  code;
+  hint;
+  pos;
+  constructor(code, message, pos, hint) {
+    super(message);
+    this.code = code;
+    this.pos = pos;
+    this.hint = hint;
+  }
+};
+function extractUidexExports(file) {
+  const exports2 = [];
+  const diagnostics = [];
+  const { content, displayPath } = file;
+  for (const header of findExportHeaders(content)) {
+    try {
+      const value = parseExpression(content, header.exprStart);
+      const metadata = buildMetadata(
+        value,
+        displayPath,
+        header.headerPos,
+        diagnostics
+      );
+      exports2.push(metadata);
+    } catch (e) {
+      if (e instanceof ExtractError) {
+        diagnostics.push({
+          code: e.code,
+          severity: "error",
+          message: e.message,
+          file: displayPath,
+          line: e.pos.line,
+          hint: e.hint
+        });
+      } else {
+        throw e;
+      }
+    }
+  }
+  return { exports: exports2, diagnostics };
+}
+var HEADER_RE = /(?:^|\n)[\t ]*export\s+const\s+uidex\b(?:\s*:\s*[^=\n]+?)?\s*=\s*/g;
+function findExportHeaders(content) {
+  const out2 = [];
+  HEADER_RE.lastIndex = 0;
+  let m;
+  while ((m = HEADER_RE.exec(content)) !== null) {
+    const leadingNewline = m[0].startsWith("\n") ? 1 : 0;
+    const headerOffset = m.index + leadingNewline;
+    const exprStart = m.index + m[0].length;
+    if (isInsideCommentOrString(content, headerOffset)) continue;
+    out2.push({
+      headerPos: posAt(content, headerOffset),
+      exprStart
+    });
+  }
+  return out2;
+}
+function isInsideCommentOrString(content, target) {
+  let i = 0;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let stringDelim = null;
+  let inTemplate = false;
+  let templateDepth = 0;
+  while (i < target) {
+    const c = content[i];
+    const n = content[i + 1];
+    if (inLineComment) {
+      if (c === "\n") inLineComment = false;
+      i++;
+      continue;
+    }
+    if (inBlockComment) {
+      if (c === "*" && n === "/") {
+        inBlockComment = false;
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (stringDelim !== null) {
+      if (c === "\\") {
+        i += 2;
+        continue;
+      }
+      if (c === stringDelim) stringDelim = null;
+      i++;
+      continue;
+    }
+    if (inTemplate) {
+      if (c === "\\") {
+        i += 2;
+        continue;
+      }
+      if (c === "$" && n === "{") {
+        templateDepth++;
+        i += 2;
+        continue;
+      }
+      if (c === "`" && templateDepth === 0) {
+        inTemplate = false;
+        i++;
+        continue;
+      }
+      if (templateDepth > 0 && c === "}") {
+        templateDepth--;
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (c === "/" && n === "/") {
+      inLineComment = true;
+      i += 2;
+      continue;
+    }
+    if (c === "/" && n === "*") {
+      inBlockComment = true;
+      i += 2;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      stringDelim = c;
+      i++;
+      continue;
+    }
+    if (c === "`") {
+      inTemplate = true;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return inLineComment || inBlockComment || stringDelim !== null || inTemplate;
+}
+var Tokenizer = class {
+  constructor(src, start) {
+    this.src = src;
+    this.pos = start;
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < start; i++) {
+      if (src[i] === "\n") {
+        line++;
+        lineStart = i + 1;
+      }
+    }
+    this.line = line;
+    this.lineStart = lineStart;
+  }
+  src;
+  pos;
+  line;
+  lineStart;
+  currentPos() {
+    return {
+      offset: this.pos,
+      line: this.line,
+      column: this.pos - this.lineStart + 1
+    };
+  }
+  advance(n = 1) {
+    for (let i = 0; i < n; i++) {
+      if (this.pos < this.src.length && this.src[this.pos] === "\n") {
+        this.line++;
+        this.lineStart = this.pos + 1;
+      }
+      this.pos++;
+    }
+  }
+  skipTrivia() {
+    while (this.pos < this.src.length) {
+      const c = this.src[this.pos];
+      const n = this.src[this.pos + 1];
+      if (c === " " || c === "	" || c === "\r" || c === "\n") {
+        this.advance();
+        continue;
+      }
+      if (c === "/" && n === "/") {
+        while (this.pos < this.src.length && this.src[this.pos] !== "\n") {
+          this.advance();
+        }
+        continue;
+      }
+      if (c === "/" && n === "*") {
+        this.advance(2);
+        while (this.pos < this.src.length) {
+          if (this.src[this.pos] === "*" && this.src[this.pos + 1] === "/") {
+            this.advance(2);
+            break;
+          }
+          this.advance();
+        }
+        continue;
+      }
+      break;
+    }
+  }
+  next() {
+    this.skipTrivia();
+    if (this.pos >= this.src.length) {
+      return { kind: "eof", value: "", pos: this.currentPos(), end: this.pos };
+    }
+    const pos = this.currentPos();
+    const c = this.src[this.pos];
+    switch (c) {
+      case "{":
+        this.advance();
+        return { kind: "lbrace", value: c, pos, end: this.pos };
+      case "}":
+        this.advance();
+        return { kind: "rbrace", value: c, pos, end: this.pos };
+      case "[":
+        this.advance();
+        return { kind: "lbracket", value: c, pos, end: this.pos };
+      case "]":
+        this.advance();
+        return { kind: "rbracket", value: c, pos, end: this.pos };
+      case "(":
+        this.advance();
+        return { kind: "lparen", value: c, pos, end: this.pos };
+      case ")":
+        this.advance();
+        return { kind: "rparen", value: c, pos, end: this.pos };
+      case ",":
+        this.advance();
+        return { kind: "comma", value: c, pos, end: this.pos };
+      case ":":
+        this.advance();
+        return { kind: "colon", value: c, pos, end: this.pos };
+    }
+    if (c === "." && this.src[this.pos + 1] === "." && this.src[this.pos + 2] === ".") {
+      this.advance(3);
+      return { kind: "spread", value: "...", pos, end: this.pos };
+    }
+    if (c === '"' || c === "'") {
+      return this.readString(pos, c);
+    }
+    if (c === "`") {
+      return this.readTemplate(pos);
+    }
+    if (isDigit(c) || c === "-" && isDigit(this.src[this.pos + 1])) {
+      return this.readNumber(pos);
+    }
+    if (isIdentStart(c)) {
+      return this.readIdent(pos);
+    }
+    this.advance();
+    return { kind: "punct", value: c, pos, end: this.pos };
+  }
+  readString(pos, delim) {
+    this.advance();
+    let value = "";
+    while (this.pos < this.src.length) {
+      const c = this.src[this.pos];
+      if (c === "\\") {
+        const esc = this.src[this.pos + 1];
+        this.advance(2);
+        value += decodeEscape(esc);
+        continue;
+      }
+      if (c === delim) {
+        this.advance();
+        return { kind: "string", value, pos, end: this.pos };
+      }
+      if (c === "\n") {
+        return { kind: "punct", value: delim, pos, end: this.pos };
+      }
+      value += c;
+      this.advance();
+    }
+    return { kind: "punct", value: delim, pos, end: this.pos };
+  }
+  readTemplate(pos) {
+    this.advance();
+    let value = "";
+    let hasExpression = false;
+    while (this.pos < this.src.length) {
+      const c = this.src[this.pos];
+      const n = this.src[this.pos + 1];
+      if (c === "\\") {
+        const esc = this.src[this.pos + 1];
+        this.advance(2);
+        value += decodeEscape(esc);
+        continue;
+      }
+      if (c === "$" && n === "{") {
+        hasExpression = true;
+        this.advance(2);
+        let depth = 1;
+        while (this.pos < this.src.length && depth > 0) {
+          const ch = this.src[this.pos];
+          if (ch === "{") depth++;
+          else if (ch === "}") depth--;
+          this.advance();
+        }
+        continue;
+      }
+      if (c === "`") {
+        this.advance();
+        if (hasExpression) {
+          return { kind: "template", value, pos, end: this.pos };
+        }
+        return { kind: "string", value, pos, end: this.pos };
+      }
+      value += c;
+      this.advance();
+    }
+    return { kind: "template", value, pos, end: this.pos };
+  }
+  readNumber(pos) {
+    const start = this.pos;
+    if (this.src[this.pos] === "-") this.advance();
+    while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
+      this.advance();
+    }
+    if (this.src[this.pos] === ".") {
+      this.advance();
+      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
+        this.advance();
+      }
+    }
+    if (this.src[this.pos] === "e" || this.src[this.pos] === "E") {
+      this.advance();
+      if (this.src[this.pos] === "+" || this.src[this.pos] === "-") {
+        this.advance();
+      }
+      while (this.pos < this.src.length && isDigit(this.src[this.pos])) {
+        this.advance();
+      }
+    }
+    const value = this.src.slice(start, this.pos);
+    return { kind: "number", value, pos, end: this.pos };
+  }
+  readIdent(pos) {
+    const start = this.pos;
+    while (this.pos < this.src.length && isIdentPart(this.src[this.pos])) {
+      this.advance();
+    }
+    const value = this.src.slice(start, this.pos);
+    return { kind: "ident", value, pos, end: this.pos };
+  }
+};
+function isDigit(c) {
+  return c !== void 0 && c >= "0" && c <= "9";
+}
+function isIdentStart(c) {
+  if (c === void 0) return false;
+  return c >= "a" && c <= "z" || c >= "A" && c <= "Z" || c === "_" || c === "$";
+}
+function isIdentPart(c) {
+  return isIdentStart(c) || isDigit(c);
+}
+function decodeEscape(esc) {
+  switch (esc) {
+    case "n":
+      return "\n";
+    case "t":
+      return "	";
+    case "r":
+      return "\r";
+    case "\\":
+      return "\\";
+    case "'":
+      return "'";
+    case '"':
+      return '"';
+    case "`":
+      return "`";
+    case "0":
+      return "\0";
+    case "b":
+      return "\b";
+    case "f":
+      return "\f";
+    case "v":
+      return "\v";
+    default:
+      return esc ?? "";
+  }
+}
+function parseExpression(content, start) {
+  const tokenizer = new Tokenizer(content, start);
+  const parser = new Parser(tokenizer);
+  const value = parser.parseValue();
+  parser.consumeTrailingAssertions();
+  return value;
+}
+var Parser = class {
+  constructor(tok) {
+    this.tok = tok;
+  }
+  tok;
+  lookahead = null;
+  peek() {
+    if (this.lookahead === null) this.lookahead = this.tok.next();
+    return this.lookahead;
+  }
+  consume() {
+    const t = this.peek();
+    this.lookahead = null;
+    return t;
+  }
+  parseValue() {
+    const t = this.peek();
+    switch (t.kind) {
+      case "lbrace":
+        return this.parseObject();
+      case "lbracket":
+        return this.parseArray();
+      case "string":
+        this.consume();
+        return { kind: "string", value: t.value, pos: t.pos };
+      case "template":
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Template literal with expression parts is not allowed in `export const uidex`; use a plain string literal.",
+          t.pos
+        );
+      case "number": {
+        this.consume();
+        const n = Number(t.value);
+        if (!Number.isFinite(n)) {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            `Invalid numeric literal "${t.value}" in \`export const uidex\`.`,
+            t.pos
+          );
+        }
+        return { kind: "number", value: n, pos: t.pos };
+      }
+      case "ident":
+        if (t.value === "true" || t.value === "false") {
+          this.consume();
+          return {
+            kind: "boolean",
+            value: t.value === "true",
+            pos: t.pos
+          };
+        }
+        if (t.value === "null") {
+          this.consume();
+          return { kind: "null", pos: t.pos };
+        }
+        if (t.value === "undefined") {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "`undefined` is not allowed as a value in `export const uidex`; omit the field instead.",
+            t.pos
+          );
+        }
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          `Identifier reference "${t.value}" is not allowed in \`export const uidex\`; the right-hand side must be a plain literal.`,
+          t.pos
+        );
+      case "spread":
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Spread (`...`) is not allowed in `export const uidex`; the right-hand side must be a plain literal.",
+          t.pos
+        );
+      case "lparen":
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Parenthesised or grouped expressions are not allowed in `export const uidex`.",
+          t.pos
+        );
+      case "punct":
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          `Unexpected token "${t.value}" in \`export const uidex\`.`,
+          t.pos
+        );
+      case "eof":
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Expected a value for `export const uidex` but reached end of file.",
+          t.pos
+        );
+      default:
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          `Unexpected token in \`export const uidex\`.`,
+          t.pos
+        );
+    }
+  }
+  parseObject() {
+    const open = this.consume();
+    const entries = [];
+    const seen = /* @__PURE__ */ new Set();
+    while (true) {
+      const t = this.peek();
+      if (t.kind === "rbrace") {
+        this.consume();
+        break;
+      }
+      if (t.kind === "spread") {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Spread (`...`) is not allowed inside `export const uidex`.",
+          t.pos
+        );
+      }
+      if (t.kind === "lbracket") {
+        this.consume();
+        const keyTok = this.peek();
+        if (keyTok.kind !== "string") {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "Computed property keys must be string literals in `export const uidex`.",
+            keyTok.pos
+          );
+        }
+        this.consume();
+        const close = this.peek();
+        if (close.kind !== "rbracket") {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "Expected `]` after computed property key.",
+            close.pos
+          );
+        }
+        this.consume();
+        const colon = this.peek();
+        if (colon.kind !== "colon") {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            "Expected `:` after computed property key.",
+            colon.pos
+          );
+        }
+        this.consume();
+        const value = this.parseValue();
+        this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
+      } else if (t.kind === "ident" || t.kind === "string") {
+        const keyTok = this.consume();
+        const next = this.peek();
+        if (next.kind === "colon") {
+          this.consume();
+          const value = this.parseValue();
+          this.recordEntry(entries, seen, keyTok.value, value, keyTok.pos);
+        } else {
+          throw new ExtractError(
+            "uidex-export-invalid-literal",
+            keyTok.kind === "ident" ? `Shorthand property "${keyTok.value}" is not allowed; write "${keyTok.value}: ..." with a literal value.` : "Expected `:` after property key.",
+            keyTok.pos
+          );
+        }
+      } else if (t.kind === "number") {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Numeric property keys are not allowed in `export const uidex`.",
+          t.pos
+        );
+      } else {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          `Unexpected token "${t.value}" inside object.`,
+          t.pos
+        );
+      }
+      const after = this.peek();
+      if (after.kind === "comma") {
+        this.consume();
+        continue;
+      }
+      if (after.kind === "rbrace") {
+        this.consume();
+        break;
+      }
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Expected \`,\` or \`}\`, got "${after.value}".`,
+        after.pos
+      );
+    }
+    return { kind: "object", entries, pos: open.pos };
+  }
+  recordEntry(entries, seen, key, value, pos) {
+    if (seen.has(key)) {
+      throw new ExtractError(
+        "uidex-export-duplicate-field",
+        `Duplicate field "${key}" in \`export const uidex\`.`,
+        pos
+      );
+    }
+    seen.add(key);
+    entries.push([key, value]);
+  }
+  parseArray() {
+    const open = this.consume();
+    const items = [];
+    while (true) {
+      const t = this.peek();
+      if (t.kind === "rbracket") {
+        this.consume();
+        break;
+      }
+      if (t.kind === "spread") {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Spread (`...`) is not allowed inside `export const uidex`.",
+          t.pos
+        );
+      }
+      const value = this.parseValue();
+      if (value.kind === "object") {
+      }
+      items.push(value);
+      const after = this.peek();
+      if (after.kind === "comma") {
+        this.consume();
+        continue;
+      }
+      if (after.kind === "rbracket") {
+        this.consume();
+        break;
+      }
+      throw new ExtractError(
+        "uidex-export-invalid-literal",
+        `Expected \`,\` or \`]\`, got "${after.value}".`,
+        after.pos
+      );
+    }
+    return { kind: "array", items, pos: open.pos };
+  }
+  consumeTrailingAssertions() {
+    const first = this.peek();
+    if (first.kind === "ident" && first.value === "as") {
+      this.consume();
+      const next = this.peek();
+      if (next.kind === "ident" && next.value === "const") {
+        this.consume();
+      } else {
+        throw new ExtractError(
+          "uidex-export-invalid-literal",
+          "Only `as const` is allowed after the `export const uidex` value.",
+          next.pos
+        );
+      }
+    }
+    const maybeSatisfies = this.peek();
+    if (maybeSatisfies.kind === "ident" && maybeSatisfies.value === "satisfies") {
+      return;
+    }
+  }
+};
+function buildMetadata(value, file, headerPos, diagnostics) {
+  if (value.kind !== "object") {
+    throw new ExtractError(
+      "uidex-export-invalid-literal",
+      "`export const uidex` must be assigned an object literal.",
+      value.pos
+    );
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const [k, v] of value.entries) byKey.set(k, v);
+  const presentKinds = KIND_DISCRIMINATORS.filter(
+    (k) => byKey.has(k)
+  );
+  if (presentKinds.length === 0) {
+    throw new ExtractError(
+      "uidex-export-missing-kind",
+      "`export const uidex` must declare one of: " + KIND_DISCRIMINATORS.join(", ") + ".",
+      value.pos
+    );
+  }
+  if (presentKinds.length > 1) {
+    throw new ExtractError(
+      "uidex-export-ambiguous-kind",
+      `\`export const uidex\` declares multiple kinds (${presentKinds.join(
+        ", "
+      )}); exactly one kind discriminator is allowed per module.`,
+      value.pos
+    );
+  }
+  const discriminator = presentKinds[0];
+  const kind = discriminator === "notFlow" ? "flow" : discriminator;
+  const allowed = ALLOWED_FIELDS[kind];
+  for (const [k] of value.entries) {
+    if (!allowed.has(k)) {
+      const fieldVal = byKey.get(k);
+      throw new ExtractError(
+        "uidex-export-unknown-field",
+        `Unknown field "${k}" in \`export const uidex\` for kind "${kind}". Allowed: ${Array.from(
+          allowed
+        ).sort().join(", ")}.`,
+        fieldVal.pos
+      );
+    }
+  }
+  const idField = discriminator === "notFlow" ? "flow" : discriminator;
+  const idValue = byKey.get(discriminator);
+  let id;
+  if (discriminator === "notFlow") {
+    const v = idValue;
+    if (v.kind !== "boolean" || v.value !== true) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        "`notFlow` must be `true`.",
+        v.pos
+      );
+    }
+    id = false;
+  } else {
+    id = readIdField(idValue, kind, idField);
+  }
+  const acceptance = readStringArrayField(byKey, "acceptance");
+  const description = readStringField(byKey, "description");
+  const name = readStringField(byKey, "name");
+  if (name === "") {
+    const pos = byKey.get("name").pos;
+    diagnostics.push({
+      code: "uidex-export-empty-name",
+      severity: "info",
+      message: "`name` is an empty string; treating as unset.",
+      file,
+      line: pos.line
+    });
+  }
+  const features = kind === "page" ? 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 = {
+    source: "ts-export",
+    kind,
+    id,
+    loc: {
+      file,
+      line: headerPos.line,
+      column: headerPos.column
+    }
+  };
+  if (name) metadata.name = name;
+  if (acceptance) metadata.acceptance = acceptance;
+  if (description) metadata.description = description;
+  if (features) metadata.features = features;
+  if (widgets) metadata.widgets = widgets;
+  if (notFlow) metadata.notFlow = true;
+  return metadata;
+}
+function readIdField(value, kind, fieldName) {
+  if (value.kind === "string") {
+    if (value.value.length === 0) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `\`${fieldName}\` must be a non-empty string.`,
+        value.pos
+      );
+    }
+    return value.value;
+  }
+  if (value.kind === "boolean" && value.value === false) {
+    if (!FALSEABLE.has(kind)) {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `\`${fieldName}: false\` is only valid for page, feature, and primitive kinds.`,
+        value.pos
+      );
+    }
+    return false;
+  }
+  throw new ExtractError(
+    "uidex-export-invalid-field",
+    `\`${fieldName}\` must be a string${FALSEABLE.has(kind) ? " or `false`" : ""}.`,
+    value.pos
+  );
+}
+function readStringField(byKey, name) {
+  const v = byKey.get(name);
+  if (!v) return void 0;
+  if (v.kind !== "string") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      `\`${name}\` must be a string.`,
+      v.pos
+    );
+  }
+  return v.value;
+}
+function readStringArrayField(byKey, name) {
+  const v = byKey.get(name);
+  if (!v) return void 0;
+  if (v.kind !== "array") {
+    throw new ExtractError(
+      "uidex-export-invalid-field",
+      `\`${name}\` must be an array of strings.`,
+      v.pos
+    );
+  }
+  const out2 = [];
+  for (const item of v.items) {
+    if (item.kind !== "string") {
+      throw new ExtractError(
+        "uidex-export-invalid-field",
+        `\`${name}\` must contain only string literals.`,
+        item.pos
+      );
+    }
+    out2.push(item.value);
+  }
+  return out2;
+}
+function posAt(content, offset) {
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < offset && i < content.length; i++) {
+    if (content[i] === "\n") {
+      line++;
+      lineStart = i + 1;
+    }
+  }
+  return { offset, line, column: offset - lineStart + 1 };
+}
+
+// src/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 [];
+  const out2 = [];
+  for (const m of tagSource.matchAll(DATA_ATTR_RE)) {
+    const kind = m[1] ?? "element";
+    const id = m[2] ?? m[3];
+    if (id) out2.push({ kind, id });
+  }
+  return out2;
+}
+function collectJSXAncestry(content) {
+  if (!content.includes("data-uidex")) return [];
+  const out2 = [];
+  const ancestors = [];
+  const stack = [];
+  const N = content.length;
+  let i = 0;
+  let line = 1;
+  const advanceLines = (from, to) => {
+    for (let k = from; k < to; k++) {
+      if (content.charCodeAt(k) === 10) line++;
+    }
+  };
+  while (i < N) {
+    const c = content[i];
+    if (c === "\n") {
+      line++;
+      i++;
+      continue;
+    }
+    if (c === "/" && content[i + 1] === "/") {
+      while (i < N && content[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && content[i + 1] === "*") {
+      const end = content.indexOf("*/", i + 2);
+      const next = end === -1 ? N : end + 2;
+      advanceLines(i, next);
+      i = next;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      const next = skipString(content, i, c);
+      advanceLines(i, next);
+      i = next;
+      continue;
+    }
+    if (c === "`") {
+      const next = skipTemplate(content, i);
+      advanceLines(i, next);
+      i = next;
+      continue;
+    }
+    if (c === "<") {
+      const nextCh = content[i + 1];
+      if (nextCh === "/") {
+        const end = content.indexOf(">", i);
+        if (end === -1) break;
+        const tagName = content.slice(i + 2, end).match(/^\s*([\w.-]*)/)?.[1] ?? "";
+        if (tagName) {
+          for (let k = stack.length - 1; k >= 0; k--) {
+            if (stack[k].tagName === tagName) {
+              for (let j = stack.length - 1; j >= k; j--) {
+                ancestors.length -= stack[j].pushed;
+              }
+              stack.length = k;
+              break;
+            }
+          }
+        }
+        advanceLines(i, end + 1);
+        i = end + 1;
+        continue;
+      }
+      if (nextCh && /[A-Za-z_]/.test(nextCh)) {
+        const end = findTagEnd(content, i + 1);
+        if (end === -1) break;
+        const tagSource = content.slice(i, end + 1);
+        const tagName = tagSource.match(/^<\s*([\w.-]*)/)?.[1] ?? "";
+        const isSelf = content[end - 1] === "/";
+        if (tagName) {
+          const attrs = parseDataAttrs(tagSource);
+          if (attrs.length > 0) {
+            const snapshot = ancestors.slice();
+            for (const a of attrs) {
+              out2.push({ kind: a.kind, id: a.id, line, ancestors: snapshot });
+            }
+          }
+          if (!isSelf) {
+            for (const a of attrs) ancestors.push(a);
+            stack.push({ tagName, pushed: attrs.length });
+          }
+        }
+        advanceLines(i, end + 1);
+        i = end + 1;
+        continue;
+      }
+    }
+    i++;
+  }
+  return out2;
+}
+function skipString(content, start, quote) {
+  const N = content.length;
+  let i = start + 1;
+  while (i < N) {
+    const c = content[i];
+    if (c === "\\") {
+      i += 2;
+      continue;
+    }
+    if (c === quote) return i + 1;
+    i++;
+  }
+  return N;
+}
+function skipTemplate(content, start) {
+  const N = content.length;
+  let i = start + 1;
+  while (i < N) {
+    const c = content[i];
+    if (c === "\\") {
+      i += 2;
+      continue;
+    }
+    if (c === "`") return i + 1;
+    if (c === "$" && content[i + 1] === "{") {
+      i += 2;
+      let depth = 1;
+      while (i < N && depth > 0) {
+        const cj = content[i];
+        if (cj === '"' || cj === "'") {
+          i = skipString(content, i, cj);
+          continue;
+        }
+        if (cj === "`") {
+          i = skipTemplate(content, i);
+          continue;
+        }
+        if (cj === "{") depth++;
+        else if (cj === "}") depth--;
+        i++;
+      }
+      continue;
+    }
+    i++;
+  }
+  return N;
+}
+function findTagEnd(content, start) {
+  const N = content.length;
+  let i = start;
+  while (i < N) {
+    const c = content[i];
+    if (c === '"' || c === "'") {
+      i = skipString(content, i, c);
+      continue;
+    }
+    if (c === "`") {
+      i = skipTemplate(content, i);
+      continue;
+    }
+    if (c === "{") {
+      let depth = 1;
+      i++;
+      while (i < N && depth > 0) {
+        const cj = content[i];
+        if (cj === '"' || cj === "'") {
+          i = skipString(content, i, cj);
+          continue;
+        }
+        if (cj === "`") {
+          i = skipTemplate(content, i);
+          continue;
+        }
+        if (cj === "{") depth++;
+        else if (cj === "}") depth--;
+        i++;
+      }
+      continue;
+    }
+    if (c === ">") return i;
+    i++;
+  }
+  return -1;
+}
+
+// src/scan/extract.ts
+var JSDOC_BLOCK = /\/\*\*([\s\S]*?)\*\//g;
+function lineAt(content, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === "\n") line++;
+  }
+  return line;
+}
+function parseJSDoc(block) {
+  const lines = block.split("\n").map((l) => l.replace(/^\s*\*\s?/, "").replace(/^\s*\/?\*+/, ""));
+  let kind = null;
+  let id = null;
+  const acceptance = [];
+  const desc = [];
+  let notFlow = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    const uidex = line.match(
+      /^@uidex\s+(page|feature|widget)\s+(\S+)(?:\s+-\s+(.+))?/
+    );
+    if (uidex) {
+      kind = uidex[1];
+      id = uidex[2];
+      if (uidex[3]) desc.push(uidex[3].trim());
+      continue;
+    }
+    if (/^@uidex:not-flow\b/.test(line)) {
+      notFlow = true;
+      continue;
+    }
+    const accept = line.match(/^@acceptance\s+(.+)$/);
+    if (accept) {
+      acceptance.push(accept[1].trim());
+      continue;
+    }
+    if (line.startsWith("@")) continue;
+    desc.push(line);
+  }
+  return {
+    kind,
+    id,
+    description: desc.join(" ").trim(),
+    acceptance,
+    notFlow
+  };
+}
+function extract(files) {
+  return files.map((file) => {
+    const { exports: exports2, diagnostics } = extractUidexExports(file);
+    const out2 = {
+      file,
+      annotations: extractOne(file)
+    };
+    if (exports2.length > 0) out2.metadata = exports2;
+    if (diagnostics.length > 0) out2.diagnostics = diagnostics;
+    return out2;
+  });
+}
+function extractOne(file) {
+  const annotations = [];
+  const { content, displayPath } = file;
+  for (const occ of collectJSXAncestry(content)) {
+    annotations.push({
+      kind: occ.kind,
+      id: occ.id,
+      file: displayPath,
+      line: occ.line,
+      ...occ.ancestors.length > 0 ? { ancestors: occ.ancestors } : {}
+    });
+  }
+  JSDOC_BLOCK.lastIndex = 0;
+  let jm;
+  while ((jm = JSDOC_BLOCK.exec(content)) !== null) {
+    const parsed = parseJSDoc(jm[1]);
+    const line = lineAt(content, jm.index);
+    if (parsed.notFlow) {
+      annotations.push({ kind: "not-flow", id: "", file: displayPath, line });
+    }
+    if (parsed.kind && parsed.id) {
+      const kind = parsed.kind === "page" ? "page-doc" : parsed.kind === "feature" ? "feature-doc" : "widget-doc";
+      annotations.push({
+        kind,
+        id: parsed.id,
+        file: displayPath,
+        line,
+        description: parsed.description || void 0,
+        acceptance: parsed.acceptance.length ? parsed.acceptance : void 0
+      });
+    } else if (parsed.acceptance.length > 0) {
+      annotations.push({
+        kind: "orphan-acceptance",
+        id: "",
+        file: displayPath,
+        line,
+        acceptance: parsed.acceptance
+      });
+    }
+  }
+  return annotations;
+}
+
+// src/scan/git.ts
+var import_node_child_process = require("child_process");
+function runGit(args, cwd) {
+  try {
+    const out2 = (0, import_node_child_process.execSync)(`git ${args.join(" ")}`, {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf8"
+    });
+    return out2.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function resolveGitContext(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const branch = env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME || env.BUILDKITE_BRANCH || env.CI_COMMIT_REF_NAME || env.BITBUCKET_BRANCH || runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd) || null;
+  const commit = env.GITHUB_SHA || env.BUILDKITE_COMMIT || env.CI_COMMIT_SHA || env.BITBUCKET_COMMIT || runGit(["rev-parse", "HEAD"], cwd) || null;
+  const pr = env.PR_NUMBER || env.GITHUB_PR_NUMBER || parseGitHubRef(env.GITHUB_REF) || env.BUILDKITE_PULL_REQUEST || env.CI_MERGE_REQUEST_IID || env.BITBUCKET_PR_ID || null;
+  return {
+    branch: branch || null,
+    commit: commit || null,
+    pr: pr && pr !== "false" ? String(pr) : null
+  };
+}
+function parseGitHubRef(ref) {
+  if (!ref) return null;
+  const m = ref.match(/^refs\/pull\/(\d+)\/merge$/);
+  return m ? m[1] : null;
+}
+
+// src/scan/resolve.ts
+var path5 = __toESM(require("path"), 1);
+
+// src/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)$/;
+function detectRoutes(files) {
+  const out2 = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const f of files) {
+    const rel = f.displayPath;
+    const parts = rel.split("/");
+    const base = parts[parts.length - 1];
+    const appIdx = parts.indexOf("app");
+    if (appIdx !== -1 && PAGE_BASENAME.test(base)) {
+      const routeSegments = parts.slice(appIdx + 1, parts.length - 1);
+      const routePath = formatNextAppPath(routeSegments);
+      push(out2, seen, routePath, f.displayPath);
+      continue;
+    }
+    if (appIdx !== -1 && ROUTE_BASENAME.test(base)) {
+      continue;
+    }
+    const pagesIdx = parts.indexOf("pages");
+    if (pagesIdx !== -1 && PAGES_ROUTER_BASENAME.test(base)) {
+      const segs = parts.slice(pagesIdx + 1);
+      if (segs[0] === "api") continue;
+      const last = segs[segs.length - 1];
+      if (last.startsWith("_")) continue;
+      const normalized = [
+        ...segs.slice(0, -1),
+        base.replace(/\.[^.]+$/, "")
+      ].filter((s) => s !== "index");
+      const routePath = formatNextAppPath(normalized);
+      push(out2, seen, routePath, f.displayPath);
+      continue;
+    }
+    const routesIdx = parts.indexOf("routes");
+    if (routesIdx !== -1 && PAGES_ROUTER_BASENAME.test(base)) {
+      const segs = parts.slice(routesIdx + 1);
+      const last = segs[segs.length - 1];
+      if (last.startsWith("_")) continue;
+      const normalized = [
+        ...segs.slice(0, -1),
+        base.replace(/\.[^.]+$/, "")
+      ].filter((s) => s !== "index" && s !== "__root");
+      const routePath = formatNextAppPath(normalized);
+      push(out2, seen, routePath, f.displayPath);
+      continue;
+    }
+  }
+  return out2.sort((a, b) => a.path.localeCompare(b.path));
+}
+function push(out2, seen, routePath, file) {
+  if (seen.has(routePath)) return;
+  seen.add(routePath);
+  out2.push({ id: pathToId(routePath), path: routePath, file });
+}
+function formatNextAppPath(segments) {
+  const kept = segments.filter((s) => !(s.startsWith("(") && s.endsWith(")")));
+  if (kept.length === 0) return "/";
+  return "/" + kept.join("/");
+}
+function pathToId(routePath) {
+  if (routePath === "/") return "root";
+  return routePath.replace(/^\/+/, "").replace(/\[\.{3}([^\]]+)\]/g, "$1").replace(/\[([^\]]+)\]/g, "$1").replace(/\//g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+
+// src/scan/walk.ts
+var fs4 = __toESM(require("fs"), 1);
+var path4 = __toESM(require("path"), 1);
+var DEFAULT_INCLUDES = ["**/*.{ts,tsx,js,jsx,mjs,cjs}"];
+var BASE_EXCLUDES = [
+  "**/node_modules/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/*.gen.ts"
+];
+var TEST_EXCLUDES = [
+  "**/*.test.ts",
+  "**/*.test.tsx",
+  "**/*.spec.ts",
+  "**/*.spec.tsx"
+];
+var DEFAULT_EXCLUDES = [...BASE_EXCLUDES, ...TEST_EXCLUDES];
+function globToRegExp(glob) {
+  let i = 0;
+  let out2 = "";
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === "*" && glob[i + 1] === "*") {
+      if (glob[i + 2] === "/") {
+        out2 += "(?:.*/)?";
+        i += 3;
+        continue;
+      }
+      out2 += ".*";
+      i += 2;
+      continue;
+    }
+    if (c === "*") {
+      out2 += "[^/]*";
+      i++;
+      continue;
+    }
+    if (c === "?") {
+      out2 += "[^/]";
+      i++;
+      continue;
+    }
+    if (c === "{") {
+      const end = glob.indexOf("}", i);
+      if (end === -1) {
+        out2 += "\\{";
+        i++;
+        continue;
+      }
+      const parts = glob.slice(i + 1, end).split(",").map((p2) => p2.replace(/[.+^$()|\\]/g, "\\$&"));
+      out2 += `(?:${parts.join("|")})`;
+      i = end + 1;
+      continue;
+    }
+    if (/[.+^$()|\\]/.test(c)) {
+      out2 += "\\" + c;
+      i++;
+      continue;
+    }
+    out2 += c;
+    i++;
+  }
+  return new RegExp(`^${out2}$`);
+}
+function toPosix(p2) {
+  return p2.split(path4.sep).join("/");
+}
+function matchesAny(rel, patterns) {
+  return patterns.some((g) => globToRegExp(g).test(rel));
+}
+function walk(sources, options) {
+  const { cwd, globalExcludes = [], includeTests = false } = options;
+  const out2 = [];
+  const baseDefaults = includeTests ? BASE_EXCLUDES : DEFAULT_EXCLUDES;
+  for (const source of sources) {
+    const includes = source.include?.length ? source.include : DEFAULT_INCLUDES;
+    const excludes = [
+      ...baseDefaults,
+      ...globalExcludes,
+      ...source.exclude ?? []
+    ];
+    const absRoot = path4.resolve(cwd, source.rootDir);
+    for (const filePath of walkDir(absRoot, absRoot)) {
+      const rel = toPosix(path4.relative(absRoot, filePath));
+      if (matchesAny(rel, excludes)) continue;
+      if (!matchesAny(rel, includes)) continue;
+      let content;
+      try {
+        content = fs4.readFileSync(filePath, "utf8");
+      } catch {
+        continue;
+      }
+      const relFromCwd = toPosix(path4.relative(cwd, filePath));
+      const displayPath = source.prefix ? `${source.prefix.replace(/\/$/, "")}/${rel}` : relFromCwd;
+      out2.push({
+        sourcePath: filePath,
+        relativePath: rel,
+        displayPath,
+        content
+      });
+    }
+  }
+  return out2.sort((a, b) => a.displayPath.localeCompare(b.displayPath));
+}
+function* walkDir(root, dir) {
+  let entries;
+  try {
+    entries = fs4.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path4.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git" || entry.name === "build" || entry.name === ".next") {
+        continue;
+      }
+      yield* walkDir(root, full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+
+// src/scan/resolve.ts
+var DOM_ATTR_KINDS = /* @__PURE__ */ new Set([
+  "element",
+  "region",
+  "widget",
+  "primitive"
+]);
+function resolveConventions(c) {
+  return {
+    primitives: c?.primitives === void 0 ? DEFAULT_CONVENTIONS.primitives : c.primitives,
+    features: c?.features === void 0 ? DEFAULT_CONVENTIONS.features : c.features,
+    pages: c?.pages === void 0 ? DEFAULT_CONVENTIONS.pages : c.pages,
+    flows: c?.flows === void 0 ? DEFAULT_CONVENTIONS.flows : c.flows,
+    regions: c?.regions === void 0 ? DEFAULT_CONVENTIONS.regions : c.regions
+  };
+}
+function kebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").toLowerCase();
+}
+function baseName(file) {
+  const b = path5.posix.basename(file);
+  return b.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "");
+}
+var LANDMARK_RE = /<(header|nav|main|aside|footer)(\s[^>]*)?>|role=["']region["']/gi;
+function extractLandmarks(file) {
+  const out2 = [];
+  LANDMARK_RE.lastIndex = 0;
+  let m;
+  while ((m = LANDMARK_RE.exec(file.content)) !== null) {
+    const tag = m[1] ?? "region";
+    const line = 1 + file.content.slice(0, m.index).split("\n").length - 1;
+    out2.push({ tag, line });
+  }
+  return out2;
+}
+function fileMatchesAny(displayPath, patterns) {
+  return patterns.some((g) => globToRegExp(g).test(displayPath));
+}
+function buildMetaFromExport(exp) {
+  const meta = {};
+  if (exp.name) meta.name = exp.name;
+  if (exp.description) meta.description = exp.description;
+  if (exp.acceptance?.length) meta.acceptance = exp.acceptance;
+  if (exp.features?.length) meta.features = exp.features;
+  if (exp.widgets?.length) meta.widgets = exp.widgets;
+  return Object.keys(meta).length > 0 ? meta : void 0;
+}
+function resolve3(ctx) {
+  const conventions = resolveConventions(ctx.config.conventions);
+  const registry = createRegistry();
+  const diagnostics = [];
+  const exportsByFile = /* @__PURE__ */ new Map();
+  for (const ef of ctx.extracted) {
+    if (!ef.metadata) continue;
+    const map = /* @__PURE__ */ new Map();
+    for (const m of ef.metadata) map.set(m.kind, m);
+    exportsByFile.set(ef.file.displayPath, map);
+  }
+  function exportFor(file, kind) {
+    return exportsByFile.get(file)?.get(kind);
+  }
+  const allAnnotations = [];
+  for (const ef of ctx.extracted) {
+    for (const a of ef.annotations) allAnnotations.push(a);
+  }
+  const directChildren = /* @__PURE__ */ new Map();
+  const seenPerParent = /* @__PURE__ */ new Map();
+  for (const ann of allAnnotations) {
+    if (!DOM_ATTR_KINDS.has(ann.kind)) continue;
+    const parent = ann.ancestors?.[ann.ancestors.length - 1];
+    if (!parent) continue;
+    const pk = `${parent.kind}:${parent.id}`;
+    const childKey = `${ann.kind}:${ann.id}`;
+    let seen = seenPerParent.get(pk);
+    if (!seen) {
+      seen = /* @__PURE__ */ new Set();
+      seenPerParent.set(pk, seen);
+    }
+    if (seen.has(childKey)) continue;
+    seen.add(childKey);
+    let arr = directChildren.get(pk);
+    if (!arr) {
+      arr = [];
+      directChildren.set(pk, arr);
+    }
+    arr.push({ kind: ann.kind, id: ann.id });
+  }
+  function metaWithComposes(kind, id, base) {
+    const composes = directChildren.get(`${kind}:${id}`);
+    if (!composes || composes.length === 0) return base;
+    return { ...base ?? {}, composes };
+  }
+  const routes = conventions.pages === "auto" ? detectRoutes(ctx.extracted.map((e) => e.file)) : [];
+  const handledPageFiles = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    const exp = exportFor(route.file, "page");
+    if (exp && exp.id === false) continue;
+    const effectiveId = exp && typeof exp.id === "string" ? exp.id : route.id;
+    const meta = exp ? buildMetaFromExport(exp) : void 0;
+    registry.add({ kind: "route", path: route.path, page: effectiveId });
+    const page = {
+      kind: "page",
+      id: effectiveId,
+      loc: { file: route.file, line: exp?.loc.line },
+      ...meta ? { meta } : {}
+    };
+    registry.add(page);
+    handledPageFiles.add(route.file);
+  }
+  for (const ef of ctx.extracted) {
+    const exp = exportFor(ef.file.displayPath, "page");
+    if (!exp || typeof exp.id !== "string") continue;
+    if (handledPageFiles.has(ef.file.displayPath)) continue;
+    const meta = buildMetaFromExport(exp);
+    registry.add({
+      kind: "page",
+      id: exp.id,
+      loc: { file: ef.file.displayPath, line: exp.loc.line },
+      ...meta ? { meta } : {}
+    });
+  }
+  const featureGlob = typeof conventions.features === "string" ? conventions.features : null;
+  const conventionalFeatureDirs = /* @__PURE__ */ new Set();
+  const featureExportsByDir = /* @__PURE__ */ new Map();
+  const suppressedFeatureDirs = /* @__PURE__ */ new Set();
+  if (featureGlob) {
+    const re = globToRegExp(featureGlob + "/**");
+    for (const ef of ctx.extracted) {
+      if (!re.test(ef.file.displayPath)) continue;
+      const dir = extractFeatureDir(ef.file.displayPath, featureGlob);
+      if (!dir) continue;
+      conventionalFeatureDirs.add(dir);
+      const exp = exportFor(ef.file.displayPath, "feature");
+      if (exp) {
+        if (exp.id === false) suppressedFeatureDirs.add(dir);
+        else if (!featureExportsByDir.has(dir))
+          featureExportsByDir.set(dir, exp);
+      }
+    }
+    for (const dir of conventionalFeatureDirs) {
+      if (suppressedFeatureDirs.has(dir)) continue;
+      const exp = featureExportsByDir.get(dir);
+      const id = exp && typeof exp.id === "string" ? exp.id : path5.posix.basename(dir);
+      const meta = exp ? buildMetaFromExport(exp) : void 0;
+      const feature = {
+        kind: "feature",
+        id,
+        loc: exp ? { file: exp.loc.file, line: exp.loc.line } : { file: dir },
+        ...meta ? { meta } : {}
+      };
+      registry.add(feature);
+    }
+  }
+  for (const ef of ctx.extracted) {
+    const exp = exportFor(ef.file.displayPath, "feature");
+    if (!exp || typeof exp.id !== "string") continue;
+    if (featureGlob) {
+      const dir = extractFeatureDir(ef.file.displayPath, featureGlob);
+      if (dir && conventionalFeatureDirs.has(dir)) continue;
+    }
+    const meta = buildMetaFromExport(exp);
+    registry.add({
+      kind: "feature",
+      id: exp.id,
+      loc: { file: ef.file.displayPath, line: exp.loc.line },
+      ...meta ? { meta } : {}
+    });
+  }
+  const widgetDomByFile = /* @__PURE__ */ new Map();
+  for (const a of allAnnotations) {
+    if (a.kind !== "widget") continue;
+    const list = widgetDomByFile.get(a.file) ?? [];
+    list.push(a);
+    widgetDomByFile.set(a.file, list);
+  }
+  const widgetFiles = /* @__PURE__ */ new Set([
+    ...widgetDomByFile.keys(),
+    ...[...exportsByFile.entries()].filter(([, kinds]) => kinds.has("widget")).map(([file]) => file)
+  ]);
+  for (const file of widgetFiles) {
+    const domAnnotations = widgetDomByFile.get(file) ?? [];
+    const exp = exportFor(file, "widget");
+    if (exp && typeof exp.id === "string") {
+      const exportId = exp.id;
+      const domIds = domAnnotations.map((a) => a.id);
+      if (domAnnotations.length === 0) {
+        diagnostics.push({
+          code: "widget-missing-dom",
+          severity: "error",
+          message: `Widget "${exportId}" declared via export const uidex but no data-uidex-widget="${exportId}" attribute found in the same file`,
+          file,
+          line: exp.loc.line,
+          entity: { kind: "widget", id: exportId },
+          hint: `Add \`<... data-uidex-widget="${exportId}">\` at the widget's DOM root`
+        });
+        continue;
+      }
+      if (!domIds.includes(exportId)) {
+        const domList = domIds.map((i) => `"${i}"`).join(", ");
+        diagnostics.push({
+          code: "widget-id-mismatch",
+          severity: "error",
+          message: `Widget id mismatch in ${file}: export declares "${exportId}" but data-uidex-widget attribute(s) are [${domList}]`,
+          file,
+          line: exp.loc.line,
+          entity: { kind: "widget", id: exportId },
+          hint: `Update either the export or the DOM attribute so both sides use the same id`
+        });
+        continue;
+      }
+      const match = domAnnotations.find((a) => a.id === exportId);
+      const meta = metaWithComposes(
+        "widget",
+        exportId,
+        buildMetaFromExport(exp)
+      );
+      const widget = {
+        kind: "widget",
+        id: exportId,
+        loc: { file, line: match.line },
+        ...meta ? { meta } : {}
+      };
+      registry.add(widget);
+    } else {
+      for (const a of domAnnotations) {
+        const meta = metaWithComposes("widget", a.id);
+        const widget = {
+          kind: "widget",
+          id: a.id,
+          loc: { file: a.file, line: a.line },
+          ...meta ? { meta } : {}
+        };
+        registry.add(widget);
+      }
+    }
+  }
+  if (conventions.regions === "landmarks") {
+    for (const ef of ctx.extracted) {
+      for (const lm of extractLandmarks(ef.file)) {
+        const id = kebab(`${lm.tag}`);
+        if (!registry.get("region", id)) {
+          const meta = metaWithComposes("region", id);
+          const region = {
+            kind: "region",
+            id,
+            loc: { file: ef.file.displayPath, line: lm.line },
+            ...meta ? { meta } : {}
+          };
+          registry.add(region);
+        }
+      }
+    }
+  }
+  for (const r of allAnnotations.filter((a) => a.kind === "region")) {
+    const meta = metaWithComposes("region", r.id);
+    const region = {
+      kind: "region",
+      id: r.id,
+      loc: { file: r.file, line: r.line },
+      ...meta ? { meta } : {}
+    };
+    registry.add(region);
+  }
+  const primitiveConventions = conventions.primitives;
+  for (const ef of ctx.extracted) {
+    const file = ef.file.displayPath;
+    const exp = exportFor(file, "primitive");
+    if (exp && exp.id === false) continue;
+    if (exp && typeof exp.id === "string") {
+      const meta = metaWithComposes(
+        "primitive",
+        exp.id,
+        buildMetaFromExport(exp)
+      );
+      const primitive = {
+        kind: "primitive",
+        id: exp.id,
+        loc: { file, line: exp.loc.line },
+        scopes: [computeScope(file)],
+        ...meta ? { meta } : {}
+      };
+      registry.add(primitive);
+      continue;
+    }
+    const domPrimitives = allAnnotations.filter(
+      (a) => a.kind === "primitive" && a.file === file
+    );
+    if (domPrimitives.length > 0) {
+      for (const p2 of domPrimitives) {
+        const meta = metaWithComposes("primitive", p2.id);
+        const primitive = {
+          kind: "primitive",
+          id: p2.id,
+          loc: { file: p2.file, line: p2.line },
+          scopes: [computeScope(p2.file)],
+          ...meta ? { meta } : {}
+        };
+        registry.add(primitive);
+      }
+      continue;
+    }
+    if (primitiveConventions && fileMatchesAny(file, primitiveConventions)) {
+      const name = kebab(baseName(file));
+      if (!name) continue;
+      const scope = computeScope(file);
+      const meta = metaWithComposes("primitive", name);
+      const primitive = {
+        kind: "primitive",
+        id: name,
+        loc: { file },
+        scopes: [scope],
+        ...meta ? { meta } : {}
+      };
+      registry.add(primitive);
+    }
+  }
+  for (const e of allAnnotations.filter((a) => a.kind === "element")) {
+    const element = {
+      kind: "element",
+      id: e.id,
+      loc: { file: e.file, line: e.line }
+    };
+    registry.add(element);
+  }
+  if (ctx.flowFiles && conventions.flows) {
+    for (const ff of ctx.flowFiles) {
+      const notFlowExport = (ff.metadata ?? []).find(
+        (m) => m.kind === "flow" && m.notFlow === true
+      );
+      if (notFlowExport) continue;
+      const flowExport = (ff.metadata ?? []).find(
+        (m) => m.kind === "flow" && typeof m.id === "string"
+      );
+      const derived = extractFlowsFromSource(ff.file);
+      if (flowExport && typeof flowExport.id === "string" && derived.length === 1) {
+        const base = derived[0];
+        const flow = {
+          kind: "flow",
+          id: flowExport.id,
+          loc: base.loc,
+          touches: base.touches
+        };
+        registry.add(flow);
+      } else {
+        for (const flow of derived) registry.add(flow);
+      }
+    }
+  }
+  const entities = [];
+  for (const kind of [
+    "route",
+    "page",
+    "feature",
+    "widget",
+    "region",
+    "element",
+    "primitive",
+    "flow"
+  ]) {
+    entities.push(...registry.list(kind));
+  }
+  return { registry, entities, routes, diagnostics };
+}
+function extractFeatureDir(displayPath, featureGlob) {
+  const parts = featureGlob.split("/");
+  const starIdx = parts.indexOf("*");
+  if (starIdx === -1) return null;
+  const prefixParts = parts.slice(0, starIdx);
+  const pathParts = displayPath.split("/");
+  for (let i = 0; i < prefixParts.length; i++) {
+    if (pathParts[i] !== prefixParts[i]) return null;
+  }
+  if (pathParts.length <= starIdx) return null;
+  return pathParts.slice(0, starIdx + 1).join("/");
+}
+function computeScope(displayPath) {
+  const parts = displayPath.split("/");
+  const featureIdx = parts.indexOf("features");
+  if (featureIdx !== -1 && parts[featureIdx + 1]) {
+    return `feature:${parts[featureIdx + 1]}`;
+  }
+  const pagesIdx = parts.indexOf("pages");
+  if (pagesIdx !== -1 && parts[pagesIdx + 1]) {
+    return `page:${parts[pagesIdx + 1]}`;
+  }
+  return "global";
+}
+function extractFlowsFromSource(file) {
+  const flows = [];
+  const source = file.content;
+  const describeRe = /test\.describe\(\s*(?:'([^']*)'|"([^"]*)")\s*,\s*\{[^}]*tag:\s*(?:'@uidex:flow'|"@uidex:flow"|\[[^\]]*@uidex:flow[^\]]*\])[^}]*\}/g;
+  let m;
+  while ((m = describeRe.exec(source)) !== null) {
+    const title = m[1] ?? m[2];
+    const id = kebab(title);
+    const line = 1 + source.slice(0, m.index).split("\n").length - 1;
+    const after = source.slice(m.index + m[0].length);
+    const arrow = after.match(/=>\s*\{/);
+    if (!arrow || arrow.index === void 0) continue;
+    const bodyStart = m.index + m[0].length + arrow.index + arrow[0].length;
+    let depth = 1;
+    let bodyEnd = -1;
+    for (let i = bodyStart; i < source.length; i++) {
+      if (source[i] === "{") depth++;
+      else if (source[i] === "}") {
+        depth--;
+        if (depth === 0) {
+          bodyEnd = i;
+          break;
+        }
+      }
+    }
+    if (bodyEnd === -1) continue;
+    const body = source.slice(bodyStart, bodyEnd);
+    const touches = captureUidexIds(body);
+    flows.push({
+      kind: "flow",
+      id,
+      loc: { file: file.displayPath, line },
+      touches: dedupe(touches.map((t) => t.id))
+    });
+  }
+  return flows;
+}
+function captureUidexIds(body) {
+  const out2 = [];
+  const re = /uidex\(\s*(?:'([^']+)'|"([^"]+)"|`([^`$]+)`)\s*\)/g;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    out2.push({ id: m[1] || m[2] || m[3] });
+  }
+  return out2;
+}
+function dedupe(arr) {
+  return Array.from(new Set(arr));
+}
+
+// src/scan/pipeline.ts
+function runScan(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const configs = opts.configs ?? discover({ cwd });
+  if (configs.length === 0) {
+    throw new Error(`No .uidex.json found starting from ${cwd}`);
+  }
+  return configs.map((dc) => runOne(dc, opts));
+}
+function runOne(dc, opts) {
+  const { config, configDir } = dc;
+  const sourceFiles = walk(config.sources, {
+    cwd: configDir,
+    globalExcludes: config.exclude
+  });
+  const extracted = extract(sourceFiles);
+  const flowFiles = config.flows ? walk(
+    config.flows.map((glob) => ({ rootDir: ".", include: [glob] })),
+    { cwd: configDir, includeTests: true }
+  ) : [];
+  const extractedFlows = extract(flowFiles);
+  const resolved = resolve3({
+    config,
+    extracted,
+    flowFiles: extractedFlows
+  });
+  const gitContext = resolveGitContext({ cwd: configDir });
+  const generated = emit({
+    registry: resolved.registry,
+    gitContext,
+    typeMode: config.typeMode
+  });
+  const outputPath = path6.resolve(configDir, config.output);
+  const outputRel = config.output;
+  let existingOnDisk = null;
+  if (opts.check) {
+    try {
+      existingOnDisk = fs5.readFileSync(outputPath, "utf8");
+    } catch {
+      existingOnDisk = null;
+    }
+  }
+  let auditResult;
+  if (opts.check || opts.lint || resolved.diagnostics.length > 0) {
+    auditResult = audit({
+      registry: resolved.registry,
+      extracted,
+      files: sourceFiles,
+      config,
+      check: opts.check,
+      lint: opts.lint,
+      resolveDiagnostics: resolved.diagnostics,
+      generated,
+      existingOnDisk,
+      outputPath: outputRel
+    });
+  }
+  return {
+    config,
+    configDir,
+    registry: resolved.registry,
+    gitContext,
+    audit: auditResult,
+    generated,
+    outputPath
+  };
+}
+function writeScanResult(result) {
+  fs5.mkdirSync(path6.dirname(result.outputPath), { recursive: true });
+  fs5.writeFileSync(result.outputPath, result.generated, "utf8");
+}
+
+// src/scan/scaffold.ts
+var fs6 = __toESM(require("fs"), 1);
+var path7 = __toESM(require("path"), 1);
+function scaffoldWidgetSpec(opts) {
+  const {
+    registry,
+    widgetId,
+    outDir,
+    force = false,
+    fixtureImport = "./fixtures"
+  } = opts;
+  const widget = registry.get("widget", widgetId);
+  if (!widget) {
+    throw new Error(`Widget "${widgetId}" not found in registry`);
+  }
+  const criteria = widget.meta?.acceptance ?? [];
+  const filename = `widget-${widgetId}.spec.ts`;
+  const outputPath = path7.resolve(outDir, filename);
+  if (fs6.existsSync(outputPath) && !force) {
+    return {
+      outputPath,
+      written: false,
+      skipped: true,
+      reason: `spec already exists at ${outputPath}; pass --force to overwrite`
+    };
+  }
+  const content = renderSpec({
+    widgetId,
+    criteria,
+    fixtureImport
+  });
+  fs6.mkdirSync(path7.dirname(outputPath), { recursive: true });
+  fs6.writeFileSync(outputPath, content, "utf8");
+  return { outputPath, written: true, skipped: false };
+}
+function renderSpec(args) {
+  const lines = [];
+  lines.push(
+    `import { test, expect } from ${JSON.stringify(args.fixtureImport)}`
+  );
+  lines.push("");
+  lines.push(
+    `test.describe(${JSON.stringify(args.widgetId)}, { tag: "@uidex:flow" }, () => {`
+  );
+  if (args.criteria.length === 0) {
+    lines.push(`  test("TODO: add acceptance criteria", async () => {`);
+    lines.push(`    // TODO`);
+    lines.push(`  })`);
+  } else {
+    for (const criterion of args.criteria) {
+      lines.push(`  test(${JSON.stringify(criterion)}, async ({ uidex }) => {`);
+      lines.push(`    // TODO: implement criterion`);
+      lines.push(`    void uidex`);
+      lines.push(`    expect(true).toBe(true)`);
+      lines.push(`  })`);
+      lines.push("");
+    }
+  }
+  lines.push("})");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/scan/cli.ts
+function parseFlags2(args) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("--")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        flags[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const next = args[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[a.slice(2)] = next;
+          i++;
+        } else {
+          flags[a.slice(2)] = true;
+        }
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+async function run(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const { positional, flags } = parseFlags2(opts.argv);
+  const command = positional[0] ?? "help";
+  const writer = createWriter();
+  try {
+    switch (command) {
+      case "help":
+      case "--help":
+      case "-h":
+        writer.out(helpText2());
+        return writer.result(0);
+      case "init":
+        return runInit(cwd, writer);
+      case "scan":
+        return runScanCommand(cwd, flags, writer);
+      case "scaffold":
+        return runScaffold(cwd, positional.slice(1), flags, writer);
+      case "ai": {
+        const result = await runAiCommand({
+          cwd,
+          argv: opts.argv.slice(1)
+        });
+        if (result.stdout) writer.out(result.stdout.replace(/\n$/, ""));
+        if (result.stderr) writer.err(result.stderr.replace(/\n$/, ""));
+        return writer.result(result.exitCode);
+      }
+      default:
+        writer.err(`Unknown command: ${command}`);
+        writer.err(helpText2());
+        return writer.result(1);
+    }
+  } catch (e) {
+    writer.err(e instanceof Error ? e.message : String(e));
+    return writer.result(1);
+  }
+}
+function helpText2() {
+  return [
+    "uidex \u2014 scanner CLI",
+    "",
+    "Commands:",
+    "  init                  Create a .uidex.json",
+    "  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",
+    "",
+    "Flags:",
+    "  --check               Verify the on-disk gen file matches a fresh scan; exit non-zero on drift (read-only)",
+    "  --lint                Run lint diagnostics (missing annotations, scope leak, legacy JSDoc)",
+    "  --audit               Equivalent to --check --lint (read-only)",
+    "  --json                Emit JSON diagnostics on stdout",
+    "  --force               (scaffold) overwrite existing spec",
+    ""
+  ].join("\n");
+}
+function runInit(cwd, w) {
+  const configPath = path8.join(cwd, CONFIG_FILENAME);
+  if (fs7.existsSync(configPath)) {
+    w.err(`.uidex.json already exists at ${configPath}`);
+    return w.result(1);
+  }
+  const config = {
+    $schema: "https://uidex.dev/schema/v2.json",
+    sources: [{ rootDir: "src" }],
+    output: "src/uidex.gen.ts"
+  };
+  fs7.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+  w.out(`Created ${configPath}`);
+  const gitignorePath = path8.join(cwd, ".gitignore");
+  const entry = "*.gen.ts";
+  if (fs7.existsSync(gitignorePath)) {
+    const existing = fs7.readFileSync(gitignorePath, "utf8");
+    const hasEntry = existing.split("\n").some((line) => line.trim() === entry);
+    if (!hasEntry) {
+      const needsNewline = existing.length > 0 && !existing.endsWith("\n");
+      fs7.appendFileSync(
+        gitignorePath,
+        `${needsNewline ? "\n" : ""}${entry}
+`,
+        "utf8"
+      );
+      w.out(`Appended ${entry} to ${gitignorePath}`);
+    }
+  } else {
+    fs7.writeFileSync(gitignorePath, `${entry}
+`, "utf8");
+    w.out(`Created ${gitignorePath} with ${entry}`);
+  }
+  return w.result(0);
+}
+function runScanCommand(cwd, flags, w) {
+  const check = Boolean(flags.check || flags.audit);
+  const lint = Boolean(flags.lint || flags.audit);
+  const asJson = Boolean(flags.json);
+  const configs = discover({ cwd });
+  if (configs.length === 0) {
+    w.err(`No ${CONFIG_FILENAME} found under ${cwd}`);
+    return w.result(1);
+  }
+  const results = runScan({ cwd, check, lint, configs });
+  if (!check) {
+    for (const r of results) writeScanResult(r);
+  }
+  const allDiagnostics = results.flatMap((r) => r.audit?.diagnostics ?? []);
+  const summary = results.reduce(
+    (acc, r) => {
+      acc.errors += r.audit?.summary.errors ?? 0;
+      acc.warnings += r.audit?.summary.warnings ?? 0;
+      return acc;
+    },
+    { errors: 0, warnings: 0 }
+  );
+  if (asJson) {
+    const out2 = { diagnostics: allDiagnostics, summary };
+    w.out(JSON.stringify(out2, null, 2));
+  } else {
+    for (const r of results) {
+      if (check) {
+        w.out(`Checked ${r.outputPath}`);
+      } else {
+        w.out(`Wrote ${r.outputPath}`);
+      }
+      for (const d of r.audit?.diagnostics ?? []) {
+        const loc = d.file ? `${d.file}${d.line ? `:${d.line}` : ""}` : "";
+        const stream = d.severity === "error" ? w.err : w.out;
+        stream(`${d.severity.toUpperCase()} [${d.code}] ${loc} ${d.message}`);
+        if (d.hint) stream(`  hint: ${d.hint}`);
+      }
+    }
+    if (check || lint) {
+      w.out(`${summary.errors} error(s), ${summary.warnings} warning(s)`);
+    }
+  }
+  const exit = summary.errors > 0 ? 1 : 0;
+  return w.result(exit);
+}
+function runScaffold(cwd, args, flags, w) {
+  const [kind, id] = args;
+  if (kind !== "widget" || !id) {
+    w.err("Usage: uidex scaffold widget <id> [--force]");
+    return w.result(1);
+  }
+  const results = runScan({ cwd });
+  for (const r of results) {
+    const widget = r.registry.get("widget", id);
+    if (!widget) continue;
+    const outDir = path8.resolve(r.configDir, "e2e");
+    const result = scaffoldWidgetSpec({
+      registry: r.registry,
+      widgetId: id,
+      outDir,
+      force: Boolean(flags.force)
+    });
+    if (result.skipped) {
+      w.err(result.reason ?? "skipped");
+      return w.result(1);
+    }
+    w.out(`Wrote ${result.outputPath}`);
+    return w.result(0);
+  }
+  w.err(`Widget "${id}" not found in registry`);
+  return w.result(1);
+}
+function createWriter() {
+  let stdout = "";
+  let stderr = "";
+  return {
+    out(msg) {
+      stdout += msg + "\n";
+    },
+    err(msg) {
+      stderr += msg + "\n";
+    },
+    result(exitCode) {
+      return { exitCode, stdout, stderr };
+    }
+  };
+}
+
+// src/cli/cli.ts
+run({ argv: process.argv.slice(2) }).then(
+  (result) => {
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+  },
+  (error) => {
+    process.stderr.write(
+      (error instanceof Error ? error.message : String(error)) + "\n"
+    );
+    process.exit(1);
+  }
+);
+//# sourceMappingURL=cli.cjs.map