uidex 0.3.0 → 0.4.0

package/dist/cli/cli.cjs

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // src/scan/cli.ts
 var fs7 = __toESM(require("fs"), 1);
-var path8 = __toESM(require("path"), 1);
+var path9 = __toESM(require("path"), 1);
 
 // src/scan/ai/index.ts
 var p = __toESM(require("@clack/prompts"), 1);
@@ -240,6 +240,10 @@ var path3 = __toESM(require("path"), 1);
 
 // src/scan/config.ts
 var DEFAULT_TYPE_MODE = "strict";
+var WELL_KNOWN_FILES = {
+  page: "uidex.page.ts",
+  feature: "uidex.feature.ts"
+};
 var ConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -277,14 +281,14 @@ var ALLOWED_AUDIT_KEYS = /* @__PURE__ */ new Set(["scopeLeak", "coverage", "acce
 function fail(msg) {
   throw new ConfigError(`Invalid .uidex.json: ${msg}`);
 }
-function assertObject(value, path9) {
+function assertObject(value, path10) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail(`${path9} must be an object`);
+    fail(`${path10} must be an object`);
   }
 }
-function assertStringArray(value, path9) {
+function assertStringArray(value, path10) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
-    fail(`${path9} must be a string[]`);
+    fail(`${path10} must be a string[]`);
   }
 }
 function validateConfig(raw) {
@@ -459,7 +463,10 @@ function discover(options = {}) {
 
 // src/scan/pipeline.ts
 var fs5 = __toESM(require("fs"), 1);
-var path6 = __toESM(require("path"), 1);
+var path7 = __toESM(require("path"), 1);
+
+// src/scan/audit.ts
+var path4 = __toESM(require("path"), 1);
 
 // src/entities/types.ts
 var ENTITY_KINDS = [
@@ -681,6 +688,32 @@ function audit(opts) {
       }
     }
   }
+  if (lint) {
+    const scannedPaths = new Set(files.map((f) => f.displayPath));
+    for (const ef of extracted) {
+      if (!ef.metadata) continue;
+      for (const m of ef.metadata) {
+        if (m.kind !== "page" && m.kind !== "feature") continue;
+        if (typeof m.id !== "string") continue;
+        const filePath = ef.file.displayPath;
+        const wellKnownName = WELL_KNOWN_FILES[m.kind];
+        if (path4.posix.basename(filePath) === wellKnownName) continue;
+        const dir = path4.posix.dirname(filePath);
+        const wellKnownPath = dir === "." ? wellKnownName : `${dir}/${wellKnownName}`;
+        if (scannedPaths.has(wellKnownPath)) continue;
+        const kindLabel = m.kind === "page" ? "Page" : "Feature";
+        diagnostics.push({
+          code: "prefer-well-known-file",
+          severity: "info",
+          message: `${kindLabel} "${m.id}" metadata lives on ${filePath}; prefer ${wellKnownPath}`,
+          file: filePath,
+          line: m.loc.line,
+          entity: { kind: m.kind, id: m.id },
+          hint: `Move the \`export const uidex\` block to ${wellKnownPath} and remove it from ${filePath}.`
+        });
+      }
+    }
+  }
   if (lint) {
     for (const f of files) {
       const lines = f.content.split("\n");
@@ -717,8 +750,8 @@ function audit(opts) {
           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 scope = primitive.scopes?.[0];
+        if (!scope) continue;
         const [kind, id] = scope.split(":");
         const importerSegments = f.displayPath.split("/");
         if (!importerSegments.includes(id) || !importerSegments.includes(kind + "s")) {
@@ -2256,7 +2289,7 @@ function parseGitHubRef(ref) {
 }
 
 // src/scan/resolve.ts
-var path5 = __toESM(require("path"), 1);
+var path6 = __toESM(require("path"), 1);
 
 // src/scan/routes.ts
 var PAGE_BASENAME = /^page\.(tsx|ts|jsx|js|mjs|cjs)$/;
@@ -2326,7 +2359,7 @@ function pathToId(routePath) {
 
 // src/scan/walk.ts
 var fs4 = __toESM(require("fs"), 1);
-var path4 = __toESM(require("path"), 1);
+var path5 = __toESM(require("path"), 1);
 var DEFAULT_INCLUDES = ["**/*.{ts,tsx,js,jsx,mjs,cjs}"];
 var BASE_EXCLUDES = [
   "**/node_modules/**",
@@ -2390,7 +2423,7 @@ function globToRegExp(glob) {
   return new RegExp(`^${out2}$`);
 }
 function toPosix(p2) {
-  return p2.split(path4.sep).join("/");
+  return p2.split(path5.sep).join("/");
 }
 function matchesAny(rel, patterns) {
   return patterns.some((g) => globToRegExp(g).test(rel));
@@ -2406,9 +2439,9 @@ function walk(sources, options) {
       ...globalExcludes,
       ...source.exclude ?? []
     ];
-    const absRoot = path4.resolve(cwd, source.rootDir);
+    const absRoot = path5.resolve(cwd, source.rootDir);
     for (const filePath of walkDir(absRoot, absRoot)) {
-      const rel = toPosix(path4.relative(absRoot, filePath));
+      const rel = toPosix(path5.relative(absRoot, filePath));
       if (matchesAny(rel, excludes)) continue;
       if (!matchesAny(rel, includes)) continue;
       let content;
@@ -2417,7 +2450,7 @@ function walk(sources, options) {
       } catch {
         continue;
       }
-      const relFromCwd = toPosix(path4.relative(cwd, filePath));
+      const relFromCwd = toPosix(path5.relative(cwd, filePath));
       const displayPath = source.prefix ? `${source.prefix.replace(/\/$/, "")}/${rel}` : relFromCwd;
       out2.push({
         sourcePath: filePath,
@@ -2437,7 +2470,7 @@ function* walkDir(root, dir) {
     return;
   }
   for (const entry of entries) {
-    const full = path4.join(dir, entry.name);
+    const full = path5.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;
@@ -2469,7 +2502,7 @@ 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);
+  const b = path6.posix.basename(file);
   return b.replace(/\.(tsx|ts|jsx|js|mjs|cjs)$/, "");
 }
 var LANDMARK_RE = /<(header|nav|main|aside|footer)(\s[^>]*)?>|role=["']region["']/gi;
@@ -2544,7 +2577,24 @@ function resolve3(ctx) {
   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");
+    const routeDir = path6.posix.dirname(route.file);
+    const wellKnownPath = `${routeDir}/${WELL_KNOWN_FILES.page}`;
+    const wellKnownExp = exportFor(wellKnownPath, "page");
+    const routeExp = exportFor(route.file, "page");
+    const exp = wellKnownExp ?? routeExp;
+    const locFile = wellKnownExp ? wellKnownPath : route.file;
+    if (wellKnownExp) handledPageFiles.add(wellKnownPath);
+    handledPageFiles.add(route.file);
+    if (wellKnownExp && routeExp) {
+      diagnostics.push({
+        code: "competing-uidex-export",
+        severity: "warning",
+        message: `Page metadata declared in both ${wellKnownPath} and ${route.file}; ${wellKnownPath} takes precedence.`,
+        file: route.file,
+        line: routeExp.loc.line,
+        hint: `Remove the export from ${route.file} or delete ${wellKnownPath}.`
+      });
+    }
     if (exp && exp.id === false) continue;
     const effectiveId = exp && typeof exp.id === "string" ? exp.id : route.id;
     const meta = exp ? buildMetaFromExport(exp) : void 0;
@@ -2552,11 +2602,10 @@ function resolve3(ctx) {
     const page = {
       kind: "page",
       id: effectiveId,
-      loc: { file: route.file, line: exp?.loc.line },
+      loc: { file: locFile, 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");
@@ -2572,7 +2621,8 @@ function resolve3(ctx) {
   }
   const featureGlob = typeof conventions.features === "string" ? conventions.features : null;
   const conventionalFeatureDirs = /* @__PURE__ */ new Set();
-  const featureExportsByDir = /* @__PURE__ */ new Map();
+  const featureExportFilesByDir = /* @__PURE__ */ new Map();
+  const wellKnownFeatureFileByDir = /* @__PURE__ */ new Map();
   const suppressedFeatureDirs = /* @__PURE__ */ new Set();
   if (featureGlob) {
     const re = globToRegExp(featureGlob + "/**");
@@ -2581,17 +2631,44 @@ function resolve3(ctx) {
       const dir = extractFeatureDir(ef.file.displayPath, featureGlob);
       if (!dir) continue;
       conventionalFeatureDirs.add(dir);
+      const isWellKnown = path6.posix.basename(ef.file.displayPath) === WELL_KNOWN_FILES.feature;
+      if (isWellKnown) wellKnownFeatureFileByDir.set(dir, ef.file.displayPath);
       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);
+        else {
+          let arr = featureExportFilesByDir.get(dir);
+          if (!arr) {
+            arr = [];
+            featureExportFilesByDir.set(dir, arr);
+          }
+          arr.push({ file: ef.file.displayPath, 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 allExports = featureExportFilesByDir.get(dir) ?? [];
+      const wellKnownPath = wellKnownFeatureFileByDir.get(dir);
+      const wellKnownEntry = wellKnownPath ? allExports.find((e) => e.file === wellKnownPath) : void 0;
+      let exp;
+      if (wellKnownEntry) {
+        exp = wellKnownEntry.exp;
+        for (const other of allExports) {
+          if (other.file === wellKnownEntry.file) continue;
+          diagnostics.push({
+            code: "competing-uidex-export",
+            severity: "warning",
+            message: `Feature metadata declared in both ${wellKnownEntry.file} and ${other.file}; ${wellKnownEntry.file} takes precedence.`,
+            file: other.file,
+            line: other.exp.loc.line,
+            hint: `Remove the export from ${other.file} or delete ${wellKnownEntry.file}.`
+          });
+        }
+      } else if (allExports.length > 0) {
+        exp = allExports[0].exp;
+      }
+      const id = exp && typeof exp.id === "string" ? exp.id : path6.posix.basename(dir);
       const meta = exp ? buildMetaFromExport(exp) : void 0;
       const feature = {
         kind: "feature",
@@ -2723,11 +2800,12 @@ function resolve3(ctx) {
         exp.id,
         buildMetaFromExport(exp)
       );
+      const scope = computeScope(file);
       const primitive = {
         kind: "primitive",
         id: exp.id,
         loc: { file, line: exp.loc.line },
-        scopes: [computeScope(file)],
+        ...scope ? { scopes: [scope] } : {},
         ...meta ? { meta } : {}
       };
       registry.add(primitive);
@@ -2739,11 +2817,12 @@ function resolve3(ctx) {
     if (domPrimitives.length > 0) {
       for (const p2 of domPrimitives) {
         const meta = metaWithComposes("primitive", p2.id);
+        const domScope = computeScope(p2.file);
         const primitive = {
           kind: "primitive",
           id: p2.id,
           loc: { file: p2.file, line: p2.line },
-          scopes: [computeScope(p2.file)],
+          ...domScope ? { scopes: [domScope] } : {},
           ...meta ? { meta } : {}
         };
         registry.add(primitive);
@@ -2753,13 +2832,13 @@ function resolve3(ctx) {
     if (primitiveConventions && fileMatchesAny(file, primitiveConventions)) {
       const name = kebab(baseName(file));
       if (!name) continue;
-      const scope = computeScope(file);
+      const convScope = computeScope(file);
       const meta = metaWithComposes("primitive", name);
       const primitive = {
         kind: "primitive",
         id: name,
         loc: { file },
-        scopes: [scope],
+        ...convScope ? { scopes: [convScope] } : {},
         ...meta ? { meta } : {}
       };
       registry.add(primitive);
@@ -2789,7 +2868,8 @@ function resolve3(ctx) {
           kind: "flow",
           id: flowExport.id,
           loc: base.loc,
-          touches: base.touches
+          touches: base.touches,
+          steps: base.steps
         };
         registry.add(flow);
       } else {
@@ -2834,7 +2914,7 @@ function computeScope(displayPath) {
   if (pagesIdx !== -1 && parts[pagesIdx + 1]) {
     return `page:${parts[pagesIdx + 1]}`;
   }
-  return "global";
+  return null;
 }
 function extractFlowsFromSource(file) {
   const flows = [];
@@ -2868,17 +2948,18 @@ function extractFlowsFromSource(file) {
       kind: "flow",
       id,
       loc: { file: file.displayPath, line },
-      touches: dedupe(touches.map((t) => t.id))
+      touches: dedupe(touches.map((t) => t.id)),
+      steps: touches.filter((t) => t.action).map((t) => ({ entityId: t.id, action: t.action }))
     });
   }
   return flows;
 }
 function captureUidexIds(body) {
   const out2 = [];
-  const re = /uidex\(\s*(?:'([^']+)'|"([^"]+)"|`([^`$]+)`)\s*\)/g;
+  const re = /uidex\(\s*(?:'([^']+)'|"([^"]+)"|`([^`$]+)`)\s*\)(?:\.(\w+)\s*\()?/g;
   let m;
   while ((m = re.exec(body)) !== null) {
-    out2.push({ id: m[1] || m[2] || m[3] });
+    out2.push({ id: m[1] || m[2] || m[3], action: m[4] });
   }
   return out2;
 }
@@ -2918,7 +2999,7 @@ function runOne(dc, opts) {
     gitContext,
     typeMode: config.typeMode
   });
-  const outputPath = path6.resolve(configDir, config.output);
+  const outputPath = path7.resolve(configDir, config.output);
   const outputRel = config.output;
   let existingOnDisk = null;
   if (opts.check) {
@@ -2954,13 +3035,13 @@ function runOne(dc, opts) {
   };
 }
 function writeScanResult(result) {
-  fs5.mkdirSync(path6.dirname(result.outputPath), { recursive: true });
+  fs5.mkdirSync(path7.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);
+var path8 = __toESM(require("path"), 1);
 function scaffoldWidgetSpec(opts) {
   const {
     registry,
@@ -2975,7 +3056,7 @@ function scaffoldWidgetSpec(opts) {
   }
   const criteria = widget.meta?.acceptance ?? [];
   const filename = `widget-${widgetId}.spec.ts`;
-  const outputPath = path7.resolve(outDir, filename);
+  const outputPath = path8.resolve(outDir, filename);
   if (fs6.existsSync(outputPath) && !force) {
     return {
       outputPath,
@@ -2989,7 +3070,7 @@ function scaffoldWidgetSpec(opts) {
     criteria,
     fixtureImport
   });
-  fs6.mkdirSync(path7.dirname(outputPath), { recursive: true });
+  fs6.mkdirSync(path8.dirname(outputPath), { recursive: true });
   fs6.writeFileSync(outputPath, content, "utf8");
   return { outputPath, written: true, skipped: false };
 }
@@ -3103,7 +3184,7 @@ function helpText2() {
   ].join("\n");
 }
 function runInit(cwd, w) {
-  const configPath = path8.join(cwd, CONFIG_FILENAME);
+  const configPath = path9.join(cwd, CONFIG_FILENAME);
   if (fs7.existsSync(configPath)) {
     w.err(`.uidex.json already exists at ${configPath}`);
     return w.result(1);
@@ -3115,7 +3196,7 @@ function runInit(cwd, w) {
   };
   fs7.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
   w.out(`Created ${configPath}`);
-  const gitignorePath = path8.join(cwd, ".gitignore");
+  const gitignorePath = path9.join(cwd, ".gitignore");
   const entry = "*.gen.ts";
   if (fs7.existsSync(gitignorePath)) {
     const existing = fs7.readFileSync(gitignorePath, "utf8");
@@ -3193,7 +3274,7 @@ function runScaffold(cwd, args, flags, w) {
   for (const r of results) {
     const widget = r.registry.get("widget", id);
     if (!widget) continue;
-    const outDir = path8.resolve(r.configDir, "e2e");
+    const outDir = path9.resolve(r.configDir, "e2e");
     const result = scaffoldWidgetSpec({
       registry: r.registry,
       widgetId: id,