@xeonr/console-shell 0.5.7 → 0.5.9

package/scripts/check-entity-crumbs.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Entity-crumb check (NAV-DESIGN §6, NAV-CONTRACT §4, CON-41): a route whose
+// own path has a `:param` renders an entity, and the entity's name must reach
+// the trail — the screen calls `useCrumb` / `useCrumbs`, renders
+// `EntityScreen`, or (a project or namespace) publishes it as the context with
+// `useActiveContext`. Otherwise the crumb trail ends at the section, or worse,
+// a layout joins URL segments and the id reaches the trail.
+//
+// The workspace has no shared eslint preset to carry a rule, and every
+// console lints with `tsc --noEmit && xeonr-check-colour-literals`, so this
+// is a sibling of that check rather than an eslint plugin: plain Node ESM, no
+// dependencies, run from the package root:
+//
+//   xeonr-check-entity-crumbs [--ignore-param team,ns] [dir…]   (default dir: src)
+//
+// What it reads, heuristically (it is not a type checker):
+//   - route objects — `{ path: "t/:key", element: <TicketDetail /> }` — and
+//     `<Route path=":id" element={<X />} />` elements;
+//   - a route with `children` (or a JSX <Route> with children) is a layout
+//     and is skipped: its params are a scope or a context, not an entity;
+//   - params named by --ignore-param are skipped (default: team);
+//   - <Navigate>, elements named *Redirect, and components that render only
+//     <Navigate> (and a loading state) have nothing to name;
+//   - the element is followed to its definition (same file, a relative
+//     import, a re-export, or lazy(() => import(…))), and from there through
+//     the components it renders and the hooks it calls, four levels deep.
+//
+// Silence one route with a comment on its line or the line above:
+//   { path: "raw/:id", element: <Raw /> }, // entity-crumb: ok — a download, not a screen
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import process from "node:process";
+
+const PUBLISHES = /\buseCrumbs?\s*\(|<EntityScreen\b|\buseActiveContext\s*\(/;
+const MAX_DEPTH = 4;
+
+function parseArgs(argv) {
+  const ignore = new Set(["team"]);
+  const dirs = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--ignore-param") {
+      for (const p of (argv[++i] ?? "").split(",")) if (p.trim()) ignore.add(p.trim());
+    } else if (a.startsWith("--ignore-param=")) {
+      for (const p of a.slice("--ignore-param=".length).split(",")) if (p.trim()) ignore.add(p.trim());
+    } else dirs.push(a);
+  }
+  return { ignore, dirs: dirs.length ? dirs : ["src"] };
+}
+
+function collect(dir) {
+  const out = [];
+  for (const ent of readdirSync(dir, { withFileTypes: true })) {
+    if (ent.name === "node_modules" || ent.name === "gen" || ent.name.startsWith(".")) continue;
+    const p = join(dir, ent.name);
+    if (ent.isDirectory()) out.push(...collect(p));
+    else if (/\.tsx?$/.test(ent.name) && !/\.(test|stories)\.tsx?$/.test(ent.name) && !ent.name.endsWith(".d.ts")) out.push(p);
+  }
+  return out.sort();
+}
+
+const cache = new Map();
+function read(file) {
+  if (!cache.has(file)) cache.set(file, readFileSync(file, "utf8"));
+  return cache.get(file);
+}
+
+/** The index just past the bracket that closes the one at `open`, skipping strings. */
+function matchClose(src, open) {
+  const pairs = { "{": "}", "[": "]", "(": ")" };
+  const stack = [pairs[src[open]]];
+  for (let i = open + 1; i < src.length; i++) {
+    const ch = src[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      for (i++; i < src.length && src[i] !== ch; i++) if (src[i] === "\\") i++;
+      continue;
+    }
+    if (ch === "/" && src[i + 1] === "/") {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if (pairs[ch]) stack.push(pairs[ch]);
+    else if (ch === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) return i + 1;
+    }
+  }
+  return src.length;
+}
+
+/** The `{` that opens the object literal containing `at`. */
+function enclosingBrace(src, at) {
+  let depth = 0;
+  for (let i = at; i >= 0; i--) {
+    const ch = src[i];
+    if (ch === "}" || ch === "]" || ch === ")") depth++;
+    else if (ch === "{" || ch === "[" || ch === "(") {
+      if (depth === 0) return ch === "{" ? i : -1;
+      depth--;
+    }
+  }
+  return -1;
+}
+
+/** Blank every [...] inside an object's text, so a child route is not read as the parent's. */
+function topLevel(obj) {
+  let out = "";
+  for (let i = 0; i < obj.length; i++) {
+    if (obj[i] === "[" && i > 0) {
+      const end = matchClose(obj, i);
+      out += " ".repeat(end - i);
+      i = end - 1;
+    } else out += obj[i];
+  }
+  return out;
+}
+
+const lineOf = (src, at) => src.slice(0, at).split("\n").length;
+
+function silenced(src, at) {
+  const lines = src.split("\n");
+  const n = lineOf(src, at) - 1;
+  return /entity-crumb:\s*ok/.test(lines[n] ?? "") || /entity-crumb:\s*ok/.test(lines[n - 1] ?? "");
+}
+
+function entityParams(path, ignore) {
+  return [...path.matchAll(/:([A-Za-z_$][\w$]*)/g)].map((m) => m[1]).filter((p) => !ignore.has(p));
+}
+
+/** The components an element expression renders: `<Admin><TopicDetail /></Admin>` is both. */
+function componentsIn(expr) {
+  return [...new Set([...expr.matchAll(/<\s*([A-Z][\w$]*)/g)].map((x) => x[1]))];
+}
+
+/** The route objects a route object sits under (its parents' `children` arrays), innermost first. */
+function ancestorObjects(src, open) {
+  const out = [];
+  let at = open - 1;
+  for (;;) {
+    // the [ … ] this object is an element of, then the { … } that owns that array
+    let depth = 0;
+    let arr = -1;
+    for (let i = at; i >= 0; i--) {
+      const ch = src[i];
+      if (ch === "}" || ch === "]" || ch === ")") depth++;
+      else if (ch === "{" || ch === "(" || ch === "[") {
+        if (depth === 0) {
+          if (ch === "[") arr = i;
+          break;
+        }
+        depth--;
+      }
+    }
+    if (arr < 0) return out;
+    const parent = enclosingBrace(src, arr - 1);
+    if (parent < 0) return out;
+    out.push(topLevel(src.slice(parent, matchClose(src, parent))));
+    at = parent - 1;
+  }
+}
+
+/** Every route declaration in a file: { path, elements, parents, layout, at }. */
+function routesIn(src) {
+  const out = [];
+  for (const m of src.matchAll(/\bpath\s*:\s*(["'`])([^"'`]*)\1/g)) {
+    const open = enclosingBrace(src, m.index);
+    if (open < 0) continue;
+    const obj = topLevel(src.slice(open, matchClose(src, open)));
+    const el = obj.match(/\belement\s*:\s*(<[\s\S]*)/);
+    // a layout above this route that names the entity covers it (fer's ref layout)
+    const parents = ancestorObjects(src, open).flatMap((o) => {
+      const pe = o.match(/\belement\s*:\s*(<[\s\S]*)/);
+      return pe ? componentsIn(pe[1]) : [];
+    });
+    out.push({ path: m[2], elements: el ? componentsIn(el[1]) : [], parents, layout: /\bchildren\s*:/.test(obj), at: m.index });
+  }
+  for (const m of src.matchAll(/<Route\b/g)) {
+    // the opening tag ends at the first `>` outside braces
+    let i = m.index + 6;
+    let depth = 0;
+    for (; i < src.length; i++) {
+      if (src[i] === "{") depth++;
+      else if (src[i] === "}") depth--;
+      else if (src[i] === ">" && depth === 0) break;
+    }
+    const tag = src.slice(m.index, i + 1);
+    const path = tag.match(/\bpath\s*=\s*(?:\{\s*)?(["'`])([^"'`]*)\1/);
+    if (!path) continue;
+    const el = tag.match(/\belement\s*=\s*\{\s*(<[\s\S]*)/);
+    out.push({ path: path[2], elements: el ? componentsIn(el[1]) : [], parents: [], layout: !tag.endsWith("/>"), at: m.index });
+  }
+  return out;
+}
+
+function resolveFile(from, spec) {
+  if (!spec.startsWith(".")) return null;
+  const base = resolve(dirname(from), spec.replace(/\.(js|jsx|mjs)$/, ""));
+  for (const c of [base, `${base}.tsx`, `${base}.ts`, join(base, "index.tsx"), join(base, "index.ts")]) {
+    if (existsSync(c) && statSync(c).isFile()) return c;
+  }
+  return null;
+}
+
+/** Where `name` comes from when it is imported or re-exported by `file`. */
+function importOf(file, name) {
+  const src = read(file);
+  for (const m of src.matchAll(/\b(?:import|export)\s+(?:type\s+)?([\s\S]*?)\s+from\s+["']([^"']+)["']/g)) {
+    const clause = m[1];
+    const spec = m[2];
+    const braces = clause.match(/\{([\s\S]*)\}/);
+    if (braces) {
+      for (const part of braces[1].split(",")) {
+        const [orig, alias] = part.replace(/^\s*type\s+/, "").split(/\s+as\s+/).map((s) => s.trim());
+        if ((alias ?? orig) === name && orig) return { file: resolveFile(file, spec), name: orig };
+      }
+    }
+    const def = clause.replace(/\{[\s\S]*\}/, "").replace(/,/g, " ").trim();
+    if (def && !def.startsWith("*") && def.split(/\s+/)[0] === name && m[0].startsWith("import")) return { file: resolveFile(file, spec), name: "default" };
+  }
+  return null;
+}
+
+const DEF = (name) =>
+  name === "default"
+    ? /(^|\n)export\s+default\s+(?:async\s+)?(?:function\b[^(]*|class\b|)/
+    : new RegExp(`(^|\\n)(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function\\s+${name}\\s*[<(]|(?:const|let)\\s+${name}\\b[^=\\n]*=)`);
+const NEXT_DEF = /\n(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|const|let|class|interface|type|enum)\s/g;
+
+/** The source of `name`'s definition in `file`, to the next top-level declaration. */
+function bodyOf(file, name) {
+  const src = read(file);
+  const m = src.match(DEF(name));
+  if (!m) {
+    if (name === "default") {
+      const d = src.match(/\nexport\s+default\s+([A-Za-z_$][\w$]*)\s*;?/);
+      if (d) return bodyOf(file, d[1]);
+    }
+    return null;
+  }
+  const start = m.index + m[1].length;
+  NEXT_DEF.lastIndex = start + 1;
+  const next = NEXT_DEF.exec(src);
+  return src.slice(start, next ? next.index : src.length);
+}
+
+/** Does rendering `name` (defined in or imported by `file`) publish a crumb? null: cannot tell. */
+function publishes(file, name, depth = 0, seen = new Set()) {
+  if (!file) return null;
+  const key = `${file}#${name}`;
+  if (seen.has(key)) return false;
+  seen.add(key);
+  const body = bodyOf(file, name);
+  if (body === null) {
+    const imp = importOf(file, name);
+    return imp ? publishes(imp.file, imp.name, depth, seen) : null;
+  }
+  if (PUBLISHES.test(body)) return true;
+  // lazy(() => import("./x")) or import("./x").then((m) => ({ default: m.X }))
+  const lazy = body.match(/import\(\s*["']([^"']+)["']\s*\)(?:[\s\S]*?\bm\.([A-Za-z_$][\w$]*))?/);
+  if (lazy) {
+    const target = resolveFile(file, lazy[1]);
+    if (publishes(target, lazy[2] ?? "default", depth + 1, seen)) return true;
+  }
+  if (depth >= MAX_DEPTH) return false;
+  const next = new Set([...body.matchAll(/<([A-Z][\w$]*)/g), ...body.matchAll(/\b(use[A-Z][\w$]*)\s*\(/g)].map((x) => x[1]));
+  next.delete(name);
+  for (const n of next) if (publishes(file, n, depth + 1, seen)) return true;
+  return false;
+}
+
+/** A component that only ever redirects (it renders <Navigate> and at most a loading state). */
+const LOADING = new Set(["Navigate", "Splash", "Spinner", "Skeleton", "Loading"]);
+function redirectOnly(file, name, seen = new Set()) {
+  if (!file || seen.has(`${file}#${name}`)) return false;
+  seen.add(`${file}#${name}`);
+  const body = bodyOf(file, name);
+  if (body === null) {
+    const imp = importOf(file, name);
+    return imp ? redirectOnly(imp.file, imp.name, seen) : false;
+  }
+  const tags = componentsIn(body);
+  return tags.includes("Navigate") && tags.every((t) => LOADING.has(t));
+}
+
+const { ignore, dirs } = parseArgs(process.argv.slice(2));
+const ROOT = process.cwd();
+const misses = [];
+let routes = 0;
+for (const dir of dirs) {
+  const abs = resolve(ROOT, dir);
+  if (!existsSync(abs)) {
+    console.error(`entity-crumbs: ${dir} does not exist`);
+    process.exit(2);
+  }
+  for (const file of collect(abs)) {
+    const src = read(file);
+    for (const r of routesIn(src)) {
+      if (r.layout || r.elements.length === 0) continue;
+      const params = entityParams(r.path, ignore);
+      if (params.length === 0) continue;
+      if (r.elements.some((e) => e === "Navigate" || /Redirect$/.test(e) || redirectOnly(file, e))) continue;
+      if (silenced(src, r.at)) continue;
+      routes++;
+      const answers = [...r.elements, ...r.parents].map((e) => publishes(file, e));
+      // Unknown (an element from a package) never fails a route; only a screen we could read all of does.
+      if (answers.some((a) => a === true) || answers.some((a) => a === null)) continue;
+      misses.push(`${relative(ROOT, file)}:${lineOf(src, r.at)}  "${r.path}" renders <${r.elements.join("> <")}>, which never calls useCrumb/useCrumbs, renders EntityScreen or calls useActiveContext`);
+    }
+  }
+}
+
+if (misses.length) {
+  console.error(`entity-crumbs: ${misses.length} route(s) with :${"param"} render a screen that names no entity (NAV-CONTRACT §4):\n`);
+  for (const m of misses) console.error(`  ${m}`);
+  console.error(`\nCall useCrumb(entity.name) in the screen, or mark the route "// entity-crumb: ok — <why>".`);
+  process.exit(1);
+}
+console.log(`entity-crumbs: clean (${routes} entity route(s) checked)`);