@wssto2/vue-core 0.11.0 → 0.12.1

package/bin/commands/lint.mjs

@@ -0,0 +1,532 @@
+// `vue-core lint`: runs ESLint once, enforces errors at zero, and enforces every ratcheted (warn-level) rule against a baseline file.
+//
+// The application's guards are ratchets: a guard fails on a NEW violation and also on a STALE allowlist entry, so the list only
+// shrinks. Type-aware linting produces rules with hundreds of pre-existing hits, where a path set is unmanageable and "turn it
+// on later, in its own PR" means it never turns on. This is the same ratchet expressed as a COUNT: the rule is live today at
+// `warn`, a new violation pushes the count over the ceiling and fails the build, and the existing debt is grandfathered at a
+// number that may only go down.
+//
+// Two modes, because type-aware linting cannot run over the whole tree on every push (it is per file, ~1.5s each, through the
+// Vue parser):
+//
+//   vue-core lint                          untyped, whole tree  -> pre-push + CI
+//   LINT_TYPED=1 vue-core lint             type-aware, CHANGED FILES  -> CI (and fine locally)
+//
+// Typed debt is tracked PER FILE (`typedByFile`) so a partial run can judge exactly what it linted; a global count would read a
+// 20-file run as a huge false improvement. Which rules are type-aware is TYPED_RULES of `@wssto2/vue-core/eslint`, the list the
+// application's eslint.config.js enables them from.
+//
+// ESLint is invoked exactly ONCE per run and both the error check and the ratchet read that one result.
+//
+//   vue-core lint                          enforce (fast, untyped)
+//   vue-core lint --fix                    autofix, then enforce
+//   vue-core lint --update                 rewrite the ceilings
+//   LINT_TYPED=1 vue-core lint             enforce typed, changed files
+//   LINT_TYPED=1 vue-core lint --update    lower ceilings for those files
+//   LINT_TYPED=1 vue-core lint --update --all    full reseed
+//   --report [--rule=<substr>] [--file=<substr>] [--summary]    list the grandfathered debt (read-only)
+//   --file=<substr>   lint every .ts/.vue file whose path contains <substr> (typed mode), in every mode
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULTS } from "../config.mjs";
+
+const baselineComment = (commands) => [
+  "Count ratchet. Generated by `vue-core lint` — do not hand-edit.",
+  "",
+  "Every ceiling is keyed BY FILE, then by rule. Per file is deliberate: it is",
+  "the stricter ratchet (you cannot add a violation in one file and pay for it",
+  "by deleting one in another), and it is what makes a failure actionable — the",
+  "driver can print the offending lines for that one file and rule instead of a",
+  "bare count with nowhere to look.",
+  "",
+  "`syntacticByFile` + `patternByFile` are measured by the untyped whole-tree run",
+  "and enforced on every push.",
+  "",
+  "`typedByFile` needs type information (LINT_TYPED=1). The full tree is slow, so",
+  "the typed run lints only the files the branch changed and judges exactly those;",
+  "the rest keep their recorded ceilings.",
+  "",
+  "Counts may only go DOWN. Fix, rerun the matching update command, commit the",
+  "smaller number. Raising one needs a recorded decision, exactly like adding an",
+  "allowlist entry.",
+  "",
+  `Reseed: ${commands.update} && ${commands.typedUpdate} --all`,
+];
+
+const toPosix = (value) => value.split(path.sep).join("/");
+
+/**
+ * The commit a typed run measures the branch against. Picking the base matters more than it looks. A fixed preference list
+ * ("try origin/main, then main, ...") is wrong: on a long-lived branch the merge-base with main can be hundreds of commits back,
+ * and at ~1.5s per file a 443-file scope is 11 minutes — worse than useless. The base has to be what this branch is actually
+ * being compared against:
+ *
+ *   1. LINT_BASE        — an explicit ref.
+ *   2. GITHUB_BASE_REF  — the PR's target branch, when running in CI.
+ *   3. @{upstream}      — the tracking branch, i.e. what `git push` updates.
+ *   4. the NEAREST of the known trunks, by merge-base commit date — never the first one that happens to resolve.
+ *
+ * Returns null when no base resolves at all (a shallow clone), which makes the caller lint the whole tree: correct, just slow,
+ * and rare.
+ *
+ * @param {(args: string[]) => string} git runs git and returns its trimmed stdout; throws when git fails
+ */
+export function resolveBase(git) {
+  const commitTime = (ref) => {
+    try {
+      return Number(git(["show", "-s", "--format=%ct", ref]));
+    } catch {
+      return 0;
+    }
+  };
+  const mergeBase = (ref) => {
+    try {
+      return git(["merge-base", "HEAD", ref]) || null;
+    } catch {
+      return null;
+    }
+  };
+
+  // An explicit base wins: a worktree branched off a long-lived branch would
+  // otherwise measure against the nearest trunk and lint its whole lead.
+  if (process.env.LINT_BASE) {
+    const base = mergeBase(process.env.LINT_BASE);
+    if (base) return base;
+  }
+  if (process.env.GITHUB_BASE_REF) {
+    const base = mergeBase(`origin/${process.env.GITHUB_BASE_REF}`);
+    if (base) return base;
+  }
+  try {
+    const upstream = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+    const base = mergeBase(upstream);
+    if (base) return base;
+  } catch {
+    // no tracking branch configured — fall through
+  }
+
+  let best = null;
+  for (const trunk of ["origin/main", "main", "origin/dev", "dev", "origin/master", "master"]) {
+    const base = mergeBase(trunk);
+    if (!base) continue;
+    const when = commitTime(base);
+    if (!best || when > best.when) best = { base, when };
+  }
+  return best?.base ?? null;
+}
+
+/**
+ * The .ts/.vue files under `rootDir` that changed since the branch point, plus uncommitted work (relative to `rootDir`);
+ * null when no base resolves. Git prints repo-relative paths, so the folder `rootDir` has inside the repository
+ * (`git rev-parse --show-prefix`, "frontend/" for a monorepo, "" at the top) is stripped.
+ */
+export function changedFiles(rootDir, generated) {
+  const git = (args) => execFileSync("git", args, { cwd: rootDir, encoding: "utf8" }).trim();
+
+  let prefix;
+  try {
+    prefix = git(["rev-parse", "--show-prefix"]);
+  } catch {
+    return null; // not a git checkout: lint the whole tree
+  }
+  const base = resolveBase(git);
+  if (!base) return null;
+
+  const out = new Set();
+  for (const args of [
+    ["diff", "--name-only", "--diff-filter=ACMR", base, "--"],
+    ["diff", "--name-only", "--diff-filter=ACMR", "--"],
+    ["ls-files", "--others", "--exclude-standard", "--full-name"],
+  ]) {
+    for (const line of git(args).split("\n")) {
+      if (!line) continue;
+      // Paths are repo-relative; this runs from rootDir.
+      if (!line.startsWith(prefix)) continue;
+      const rel = line.slice(prefix.length);
+      if (!/\.(ts|vue)$/.test(rel)) continue;
+      if (generated.some((dir) => rel.startsWith(`${dir}/`))) continue;
+      if (existsSync(path.join(rootDir, rel))) out.add(rel);
+    }
+  }
+  return [...out];
+}
+
+function collectFiles(dir, extensions, ignoredDirs, acc = []) {
+  for (const entry of readdirSync(dir)) {
+    if (ignoredDirs.has(entry)) continue;
+    const full = path.join(dir, entry);
+    if (statSync(full).isDirectory()) collectFiles(full, extensions, ignoredDirs, acc);
+    else if (extensions.includes(path.extname(full))) acc.push(full);
+  }
+  return acc;
+}
+
+function sorted(entries) {
+  return Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function sortedByFile(map) {
+  return sorted(Object.entries(map).map(([file, rules]) => [file, sorted(Object.entries(rules))]));
+}
+
+function totalOf(map) {
+  return Object.values(map).reduce((sum, rules) => sum + Object.values(rules).reduce((a, b) => a + b, 0), 0);
+}
+
+// Merge rather than replace, so an incremental run never discards ceilings for
+// files it did not look at: entries inside the scope are rewritten from what was
+// just measured, and a file whose debt reached zero drops out entirely.
+function mergeByFile(previous, observed, touchedFiles) {
+  if (!touchedFiles) return sortedByFile(observed);
+  const merged = { ...previous };
+  for (const file of touchedFiles) delete merged[file];
+  return sortedByFile({ ...merged, ...observed });
+}
+
+/** @returns {Promise<number>} the exit code */
+export default async function lint({ args, config: given, root, out, err }) {
+  const log = out;
+  const rootDir = root;
+  const config = { ...DEFAULTS.lint, ...given };
+  const baselineFile = path.resolve(rootDir, config.baselines);
+  const { generated, patternCounters, policy } = config;
+  const commands = { ...DEFAULTS.lint.commands, ...config.commands };
+  const ignoredDirs = new Set(["node_modules", "dist", "coverage", ...generated, ".git", "playwright-report", "test-results"]);
+
+  const { TYPED_RULE_SET } = await import("@wssto2/vue-core/eslint");
+
+  const argv = new Set(args);
+  const shouldUpdate = argv.has("--update");
+  const shouldFix = argv.has("--fix");
+
+  // --report lists the grandfathered debt itself. Without it the debt is
+  // invisible: this prints ERRORS and ratchet failures, while the
+  // warn-level violations under a ceiling are only counted — which is right for a
+  // gate (they are known and accepted) and useless for anyone trying to pay them
+  // down. --report is the read-only view: what is left, where, and what to fix.
+  //   --rule=<substr>  narrow to matching rule ids
+  //   --file=<substr>  narrow to matching paths
+  //   --summary        rankings only, no per-line listing
+  const shouldReport = argv.has("--report");
+  const summaryOnly = argv.has("--summary");
+  const argValue = (name) => {
+    const hit = [...argv].find((a) => a.startsWith(`--${name}=`));
+    return hit ? hit.slice(name.length + 3) : null;
+  };
+  const ruleFilter = argValue("rule");
+  const fileFilter = argValue("file");
+
+  // Which mode ESLint ran in — read by the application's eslint.config.js (vueCoreConfig).
+  // It decides which half of the baselines is enforceable: the fast path never
+  // runs the typed rules, so their counts come back 0 and must NOT be compared
+  // (that would look like "everything fixed" and fail on a false improvement).
+  const TYPED = process.env.LINT_TYPED === "1";
+
+  // Typed mode lints only the files the branch changed, because the full tree
+  // is slow while 5 files take ~8s — the marginal per-file cost is ~1.5s and
+  // the program build is ~7s of that, so volume is the whole problem. `--all`
+  // forces the full sweep (used to seed or re-seed the per-file baselines).
+  const ALL = argv.has("--all");
+
+  // Pattern counters cover debt ESLint cannot count itself: an inline
+  // `eslint-disable` is invisible to the rule it silences, so a rule kept at
+  // `error` with justified per-site exemptions still needs a ceiling on how many
+  // exemptions exist. Same ratchet, different source of truth.
+  function countPatterns() {
+    const byFile = {};
+    const messages = {};
+    for (const counter of patternCounters) {
+      for (const file of collectFiles(rootDir, counter.extensions, ignoredDirs)) {
+        const rel = toPosix(path.relative(rootDir, file));
+        readFileSync(file, "utf8")
+          .split("\n")
+          .forEach((line, i) => {
+            counter.pattern.lastIndex = 0;
+            if (!counter.pattern.test(line)) return;
+            ((byFile[rel] ??= {})[counter.name] ??= 0);
+            byFile[rel][counter.name]++;
+            (messages[`${rel}\u0000${counter.name}`] ??= []).push(`${rel}:${i + 1}  ${counter.hint}`);
+          });
+      }
+    }
+    return { byFile, messages };
+  }
+
+  // What to lint. Typed runs are scoped because the full tree is slow:
+  //   --all         everything (seeding, or a full audit)
+  //   --file=<sub>  every file whose path contains <sub>, in every mode (check,
+  //                 report, update) — the cheap way to judge the files you touched;
+  //                 a filter that matches nothing lints nothing
+  //   otherwise     the files this branch changed (LINT_BASE=<ref> sets the base)
+  function typedScope() {
+    if (ALL) return null;
+    if (fileFilter) {
+      return collectFiles(rootDir, [".ts", ".vue"], ignoredDirs)
+        .map((f) => toPosix(path.relative(rootDir, f)))
+        .filter((f) => f.includes(fileFilter));
+    }
+    return changedFiles(rootDir, generated);
+  }
+
+  const scope = TYPED ? typedScope() : null;
+  const targets = scope ?? ["."];
+
+  if (TYPED) {
+    if (scope && scope.length === 0) {
+      log(
+        fileFilter
+          ? `lint (typed): no .ts/.vue file path contains "${fileFilter}" — nothing to check`
+          : shouldReport
+            ? "lint (typed): nothing in scope — pass --file=<substring> or --all"
+            : "lint (typed): no changed .ts/.vue files — nothing to check",
+      );
+      return 0;
+    }
+    log(scope ? `lint (typed): ${scope.length} file(s)` : "lint (typed): full tree — this takes ~22min");
+  }
+
+  const { loadESLint } = await import("eslint");
+  const ESLint = await loadESLint({ useFlatConfig: true });
+  const eslint = new ESLint({ cwd: rootDir, fix: shouldFix });
+  const results = await eslint.lintFiles(targets);
+
+  if (shouldFix) await ESLint.outputFixes(results);
+
+  // ---------------------------------------------------------------------------
+  // Errors: always zero-tolerance. These are the rules with no outstanding debt.
+  // ---------------------------------------------------------------------------
+  const errorResults = results
+    .map((r) => ({
+      ...r,
+      messages: r.messages.filter((m) => m.severity === 2),
+      warningCount: 0,
+    }))
+    .filter((r) => r.messages.length > 0);
+
+  let failed = false;
+
+  if (errorResults.length > 0) {
+    const formatter = await eslint.loadFormatter("stylish");
+    err(await formatter.format(errorResults));
+    err("eslint: errors must be fixed — they are not ratcheted.\n");
+    failed = true;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Warnings: ratcheted PER FILE against the baseline.
+  // ---------------------------------------------------------------------------
+  // Per file rather than one number per rule, for two reasons. It is the stricter
+  // ratchet — you cannot add a violation in one file and pay for it by deleting
+  // one somewhere else. And it is the only way the failure can be actionable: a
+  // global "190 (ceiling 189)" cannot say where the new one is, and dumping all
+  // 190 locations is not an answer. Scoped to one file and one rule, printing
+  // every occurrence IS the answer — the offending lines are few, and your own
+  // diff tells you which is yours.
+  const byFile = {};
+  const messagesFor = {};
+  for (const result of results) {
+    const rel = toPosix(path.relative(rootDir, result.filePath));
+    for (const message of result.messages) {
+      if (message.severity !== 1) continue;
+      const rule = message.ruleId ?? "(unknown)";
+      ((byFile[rel] ??= {})[rule] ??= 0);
+      byFile[rel][rule]++;
+      (messagesFor[`${rel}\u0000${rule}`] ??= []).push(`${rel}:${message.line}:${message.column}  ${message.message}`);
+    }
+  }
+
+  function splitByFile(source, wantTyped) {
+    const split = {};
+    for (const [file, rules] of Object.entries(source)) {
+      for (const [rule, count] of Object.entries(rules)) {
+        if (TYPED_RULE_SET.has(rule) !== wantTyped) continue;
+        (split[file] ??= {})[rule] = count;
+      }
+    }
+    return split;
+  }
+
+  const syntacticByFile = splitByFile(byFile, false);
+  const typedByFile = splitByFile(byFile, true);
+
+  // Pattern counters scan the tree themselves (an inline eslint-disable is
+  // invisible to the rule it silences), so they only mean anything on a run that
+  // covered the whole tree.
+  const fullTree = !scope;
+  const { byFile: patternByFile, messages: patternMessages } = fullTree ? countPatterns() : { byFile: {}, messages: {} };
+
+  const baseline = existsSync(baselineFile) ? JSON.parse(readFileSync(baselineFile, "utf8")) : {};
+  const baselineRel = toPosix(path.relative(rootDir, baselineFile));
+
+  if (shouldReport) {
+    const rows = [];
+    for (const [key, lines] of Object.entries(messagesFor)) {
+      const [file, rule] = key.split("\u0000");
+      if (ruleFilter && !rule.includes(ruleFilter)) continue;
+      if (fileFilter && !file.includes(fileFilter)) continue;
+      rows.push({ file, rule, lines });
+    }
+    for (const [key, lines] of Object.entries(patternMessages)) {
+      const [file, name] = key.split("\u0000");
+      if (ruleFilter && !name.includes(ruleFilter)) continue;
+      if (fileFilter && !file.includes(fileFilter)) continue;
+      rows.push({ file, rule: name, lines });
+    }
+
+    if (rows.length === 0) {
+      log("no grandfathered violations match that filter — nothing to pay down");
+      return 0;
+    }
+
+    const byRule = {};
+    const byFileTotal = {};
+    for (const row of rows) {
+      byRule[row.rule] = (byRule[row.rule] ?? 0) + row.lines.length;
+      byFileTotal[row.file] = (byFileTotal[row.file] ?? 0) + row.lines.length;
+    }
+    const total = Object.values(byRule).reduce((a, b) => a + b, 0);
+
+    if (!summaryOnly) {
+      // Heaviest files first: that is the order you would actually work in, since
+      // one file's violations tend to share a root cause (an untyped helper, a
+      // props block with no defaults) and fall together.
+      const files = Object.keys(byFileTotal).sort((a, b) => byFileTotal[b] - byFileTotal[a] || a.localeCompare(b));
+      for (const file of files) {
+        log(`\n${file}  (${byFileTotal[file]})`);
+        for (const row of rows.filter((r) => r.file === file).sort((a, b) => a.rule.localeCompare(b.rule))) {
+          log(`  ${row.rule}  x${row.lines.length}`);
+          for (const line of row.lines) log(`    ${line}`);
+        }
+      }
+    }
+
+    const pad = Math.max(...Object.keys(byRule).map((r) => r.length));
+    log(`\n${"-".repeat(pad + 12)}`);
+    log(`grandfathered debt: ${total} violation(s) in ${Object.keys(byFileTotal).length} file(s)`);
+    log(`${"-".repeat(pad + 12)}`);
+    for (const [rule, n] of Object.entries(byRule).sort((a, b) => b[1] - a[1])) {
+      log(`  ${String(n).padStart(5)}  ${rule}`);
+    }
+    log("\nheaviest files:");
+    for (const [file, n] of Object.entries(byFileTotal)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 15)) {
+      log(`  ${String(n).padStart(5)}  ${file}`);
+    }
+    log(`\nFix some, then: ${TYPED ? commands.typedUpdate : commands.update}`);
+    if (!TYPED) {
+      const column = Math.max(commands.typedReport.length, commands.typedReportAll.length) + 4;
+      log("Type-aware debt (floating promises, unsafe access) needs:");
+      log(`  ${commands.typedReport.padEnd(column)}# changed files`);
+      log(`  ${commands.typedReportAll.padEnd(column)}# whole tree, ~22min`);
+    }
+    return 0;
+  }
+
+  if (shouldUpdate) {
+    const updated = {
+      _comment: baseline._comment ?? baselineComment(commands),
+      // Only the untyped whole-tree run can judge the syntactic and pattern
+      // sections; a typed run leaves them exactly as it found them.
+      syntacticByFile: TYPED ? (baseline.syntacticByFile ?? {}) : mergeByFile(baseline.syntacticByFile ?? {}, syntacticByFile, null),
+      patternByFile: fullTree ? sortedByFile(patternByFile) : (baseline.patternByFile ?? {}),
+      typedByFile: TYPED ? mergeByFile(baseline.typedByFile ?? {}, typedByFile, ALL ? null : scope) : (baseline.typedByFile ?? {}),
+    };
+    mkdirSync(path.dirname(baselineFile), { recursive: true });
+    writeFileSync(baselineFile, `${JSON.stringify(updated, null, 2)}\n`);
+
+    const mode = TYPED ? (ALL ? "typed, full tree" : "typed, changed files") : "fast";
+    log(`baselines written to ${baselineRel} (${mode})`);
+    if (TYPED) {
+      log(`  typed debt: ${totalOf(updated.typedByFile)} violation(s) across ${Object.keys(updated.typedByFile).length} file(s)`);
+    } else {
+      log(`  syntactic debt: ${totalOf(updated.syntacticByFile)} violation(s) across ${Object.keys(updated.syntacticByFile).length} file(s)`);
+      log(`  typed section untouched — refresh it with ${commands.typedUpdate}`);
+    }
+    return failed ? 1 : 0;
+  }
+
+  const regressions = [];
+  const improvements = [];
+
+  // Compare one file's rule counts against its recorded ceiling. `detail` looks up
+  // the actual ESLint messages so a failure can print the offending lines rather
+  // than just a number.
+  function compareFile(file, current, expected, detail) {
+    const rules = new Set([...Object.keys(current), ...Object.keys(expected)]);
+    for (const rule of rules) {
+      const now = current[rule] ?? 0;
+      const max = expected[rule] ?? 0;
+      if (now > max) {
+        regressions.push({ file, rule, now, max, lines: detail?.[`${file}\u0000${rule}`] ?? [] });
+      } else if (now < max) {
+        improvements.push({ file, rule, now, max });
+      }
+    }
+  }
+
+  // The untyped run is the only one that sees the whole tree, so it is the only
+  // one that can judge the syntactic and pattern sections. A typed run skips them:
+  // it covers a handful of files and would read as a huge false improvement.
+  if (!TYPED) {
+    const expected = baseline.syntacticByFile ?? {};
+    for (const file of new Set([...Object.keys(expected), ...Object.keys(syntacticByFile)])) {
+      compareFile(file, syntacticByFile[file] ?? {}, expected[file] ?? {}, messagesFor);
+    }
+    const expectedPatterns = baseline.patternByFile ?? {};
+    for (const file of new Set([...Object.keys(expectedPatterns), ...Object.keys(patternByFile)])) {
+      compareFile(file, patternByFile[file] ?? {}, expectedPatterns[file] ?? {}, patternMessages);
+    }
+  } else {
+    // Only the files actually linted are judged — everything outside this run's
+    // scope keeps its recorded ceiling untouched.
+    const expected = baseline.typedByFile ?? {};
+    const linted = scope ?? Object.keys({ ...expected, ...typedByFile });
+    for (const file of linted) {
+      compareFile(file, typedByFile[file] ?? {}, expected[file] ?? {}, messagesFor);
+    }
+  }
+
+  const updateCmd = TYPED ? commands.typedUpdate : commands.update;
+
+  if (regressions.length > 0) {
+    failed = true;
+    const added = regressions.reduce((sum, r) => sum + (r.now - r.max), 0);
+    err(`\nlint ratchet: ${added} NEW violation(s).\n`);
+    err("These rules are `warn` only because existing code predates them. The");
+    err("ceiling is grandfathered debt, not headroom — new code lands clean.\n");
+    for (const r of regressions) {
+      err(`  ${r.file}`);
+      err(`    ${r.rule}: ${r.now}, was ${r.max} (+${r.now - r.max})`);
+      // Scoped to one file and one rule the list is short, so print every
+      // occurrence with its message. The ratchet cannot know which one you added —
+      // your diff can, and these are the candidates.
+      for (const line of r.lines) err(`      ${line}`);
+      err("");
+    }
+    err("Fix the new one(s). If a violation is unavoidable and reviewed, raising a");
+    err(`ceiling is a CODEOWNERS decision — see ${policy}.\n`);
+  }
+
+  if (improvements.length > 0) {
+    const totalFixed = improvements.reduce((sum, i) => sum + (i.max - i.now), 0);
+    err(`\nlint ratchet: ${totalFixed} violation(s) fixed — lock it in:\n`);
+    for (const i of improvements) {
+      err(`  ${i.file}`);
+      err(`    ${i.rule}: ${i.max} -> ${i.now}`);
+    }
+    err(`\n  ${updateCmd} && git add ${baselineRel}\n`);
+    err("A ratchet that does not tighten is just a warning, so this is a hard");
+    err("failure for the same reason a stale allowlist entry is.\n");
+    failed = true;
+  }
+
+  if (!failed) {
+    const debt = TYPED ? totalOf(typedByFile) : totalOf(syntacticByFile) + totalOf(patternByFile);
+    const where = TYPED ? `${results.length} changed file(s)` : "whole tree";
+    log(`eslint${TYPED ? " (typed)" : ""}: clean — ${where}, ${debt} grandfathered violation(s) at ceiling, none new`);
+  }
+
+  return failed ? 1 : 0;
+}

package/bin/config.mjs

@@ -0,0 +1,72 @@
+// Finds, loads and validates `vue-core.config.mjs` for the `vue-core` command. Plain Node, no dependency:
+// the types of the file are src/config (`@wssto2/vue-core/config`).
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const CONFIG_FILE = "vue-core.config.mjs";
+
+/** The top-level sections, one per command, with their defaults; a command that has defaults adds them here. */
+export const DEFAULTS = {
+  lint: {
+    baselines: "scripts/lint-baselines.json",
+    generated: ["generated"],
+    patternCounters: [],
+    // What the messages tell the developer to run; an application points them at its own npm scripts.
+    commands: {
+      update: "vue-core lint --update",
+      typedUpdate: "LINT_TYPED=1 vue-core lint --update",
+      typedReport: "LINT_TYPED=1 vue-core lint --report",
+      typedReportAll: "LINT_TYPED=1 vue-core lint --report --all",
+    },
+    policy: "the project's lint policy",
+  },
+  architecture: {
+    featuresDir: "features",
+    alias: "@/",
+    sharedLayers: ["components", "composables"],
+    skip: ["dist", "generated", "node_modules"],
+    allow: {},
+    packs: [],
+    rules: [],
+    doc: {},
+  },
+  generator: { template: join(dirname(fileURLToPath(import.meta.url)), "templates", "feature-crud"), out: "features" },
+  e2eTimings: { report: "e2e-timings/results.json" },
+};
+
+export class ConfigError extends Error {}
+
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** The nearest `vue-core.config.mjs` from `from` upwards, or null. */
+export function findConfig(from) {
+  for (let dir = resolve(from); ; dir = dirname(dir)) {
+    const candidate = join(dir, CONFIG_FILE);
+    if (existsSync(candidate)) return candidate;
+    if (dirname(dir) === dir) return null;
+  }
+}
+
+/**
+ * @param {{ cwd: string, path?: string }} options `path` is `--config`; without it the file is searched from `cwd`
+ * @returns {Promise<{ path: string | null, root: string, config: typeof DEFAULTS }>} `root` is the config file's folder (`cwd` without a file);
+ *   no file is valid and gives the defaults
+ */
+export async function loadConfig({ cwd, path }) {
+  const file = path ? resolve(cwd, path) : findConfig(cwd);
+  if (path && !existsSync(file)) throw new ConfigError(`--config ${path}: no such file`);
+  let given = {};
+  if (file) {
+    const module = await import(pathToFileURL(file).href);
+    given = module.default;
+    if (!isObject(given)) throw new ConfigError(`${file}: the default export must be an object (export default defineConfig({ … }))`);
+    const unknown = Object.keys(given).filter((key) => !(key in DEFAULTS));
+    if (unknown.length > 0) throw new ConfigError(`${file}: unknown section ${unknown.join(", ")}; the sections are ${Object.keys(DEFAULTS).join(", ")}`);
+    for (const [name, section] of Object.entries(given)) {
+      if (!isObject(section)) throw new ConfigError(`${file}: "${name}" must be an object`);
+    }
+  }
+  const config = Object.fromEntries(Object.entries(DEFAULTS).map(([name, defaults]) => [name, { ...defaults, ...given[name] }]));
+  return { path: file, root: file ? dirname(file) : resolve(cwd), config };
+}

package/bin/templates/feature-crud/api.ts.tpl

@@ -0,0 +1,35 @@
+import type { HttpClient } from "@wssto2/vue-core/client";
+import { defineCollection, httpList } from "@wssto2/vue-core/collection";
+import { __FEATURE_ROUTE_TABLE__ } from "@/generated/routes/__FEATURE_ROUTE_MODULE__/routes";
+import type { __FEATURE_FORM_TYPE__ } from "./form";
+import type { __FEATURE_ENTITY__ } from "./types";
+
+export type __FEATURE_ENTITY__Sort = "name" | "created_at" | "updated_at";
+
+// The requests are the route table go-core generates from the Go feature's Contract (ts:generate-routes): the ids
+// are the URL's, the rest of the input is the body.
+export const __FEATURE_API_CLIENT__ = (http: HttpClient) => ({
+  list: httpList<__FEATURE_ENTITY__, __FEATURE_ENTITY__Sort, never>(http, __FEATURE_ROUTE_TABLE__.list.path),
+
+  async get(id: number): Promise<__FEATURE_ENTITY__> {
+    return (await http.request(__FEATURE_ROUTE_TABLE__.show, { id })).data;
+  },
+
+  /** A 422 lands on the form's fields (`form.submit`). */
+  async create(payload: __FEATURE_FORM_TYPE__, idempotencyKey: string): Promise<__FEATURE_ENTITY__> {
+    return (await http.request(__FEATURE_ROUTE_TABLE__.create, payload, { headers: { "Idempotency-Key": idempotencyKey } })).data;
+  },
+});
+
+export type __FEATURE_ENTITY__Api = ReturnType<typeof __FEATURE_API_CLIENT__>;
+
+/** The list: the list page and a record's previous / next both read this one definition. */
+export const __FEATURE_LIST__ = (api: __FEATURE_ENTITY__Api) =>
+  defineCollection({
+    id: "__FEATURE_I18N_MODULE__",
+    stateVersion: 1,
+    load: api.list,
+    key: (item: __FEATURE_ENTITY__) => item.id ?? 0, // generated entities type `id` as nullable
+    query: { sorts: ["name", "created_at", "updated_at"], filters: [] },
+    defaults: { sort: "created_at", direction: "asc" },
+  });

package/bin/templates/feature-crud/components/__FEATURE_ENTITY__Modal.vue.tpl

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import { TextField, useForm } from "@wssto2/vue-core/form";
+import { Modal } from "@wssto2/vue-core/modal";
+import { usePlatform } from "@wssto2/vue-core/platform";
+import { ref } from "vue";
+import { useI18n } from "vue-i18n";
+import { __FEATURE_API_CLIENT__ } from "../api";
+import { __FEATURE_FORM_SCHEMA__ } from "../form";
+
+const emit = defineEmits<{ changed: [] }>();
+const { t } = useI18n();
+const api = __FEATURE_API_CLIENT__(usePlatform().http);
+
+const modal = ref<InstanceType<typeof Modal> | null>(null);
+const form = useForm({ defaults: () => ({ name: "" }), validator: __FEATURE_FORM_SCHEMA__ });
+
+async function save() {
+  const result = await form.submit((payload, { idempotencyKey }) => api.create(payload, idempotencyKey));
+  if (result.status !== "saved") return;
+  void modal.value?.dismiss();
+  emit("changed");
+}
+
+function show() {
+  form.reset();
+  modal.value?.present();
+}
+
+defineExpose({ show });
+</script>
+
+<template>
+  <Modal ref="modal" :title="t('__FEATURE_I18N_MODULE__.actions.create')" :primary-label="t('general.actions.save')" :status="form.submitting.value ? 'processing' : 'idle'" @primary="save">
+    <TextField v-bind="form.bind('name')" :label="t('__FEATURE_I18N_MODULE__.table_columns.name')" />
+  </Modal>
+</template>