@starci/hfs 4.0.10 → 4.1.0

package/runtime/scripts/hfs/rules/lint-suppression.mjs

@@ -14,6 +14,14 @@ const SUPPRESSION_FLAG = /--(?:suppressions-location|suppress-all|suppress-rule|
 const ESLINT_CONFIG = /(?:^|\/)eslint\.config\.[cm]?[jt]s$/;
 const CONFIG_SUPPRESSION = /suppressions/i;
 
+function packageSuppressionFindings(file, pkg) {
+  const findings = [];
+  for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
+    if (SUPPRESSION_SCRIPT_NAME.test(name) || SUPPRESSION_FLAG.test(String(command))) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} script ${name} manages lint suppressions (${String(command).slice(0, 80)}); delete the script and fix the findings in the code`));
+  }
+  return findings;
+}
+
 /** The findings of R104 over the tracked paths `files` of the repository at `repoRoot`. */
 export function lintSuppressionFindings({ repoRoot, files }) {
   const findings = [];
@@ -25,9 +33,7 @@ export function lintSuppressionFindings({ repoRoot, files }) {
       if (text !== null && CONFIG_SUPPRESSION.test(text)) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} passes a suppressions configuration to eslint; a repository suppresses nothing`));
     } else if (file === 'package.json' || file.endsWith('/package.json')) {
       const pkg = readJson(repoRoot, file);
-      for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
-        if (SUPPRESSION_SCRIPT_NAME.test(name) || SUPPRESSION_FLAG.test(String(command))) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} script ${name} manages lint suppressions (${String(command).slice(0, 80)}); delete the script and fix the findings in the code`));
-      }
+      findings.push(...packageSuppressionFindings(file, pkg));
     }
   }
   return findings;

package/runtime/scripts/hfs/rules/monorepo.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readJson, readText } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const MONO_WORKSPACES = 'HFS_MONO_WORKSPACES';
 const MONO_FE_WORKSPACE = 'HFS_MONO_FE_WORKSPACE';
@@ -51,7 +52,7 @@ function workspacesOf(files) {
     const parts = file.split('/');
     if (parts.length === 4 && parts[0] === 'fe' && (parts[1] === 'apps' || parts[1] === 'packages') && parts[3] === MANIFEST) folders.add(parts.slice(0, 3).join('/'));
   }
-  return [...folders].sort();
+  return [...folders].sort(byCodeUnit);
 }
 
 /** R143: the root package.json declares the workspaces, the package manager and turbo. */
@@ -66,6 +67,24 @@ function rootFindings(repoRoot) {
 }
 
 /** R144: the manifest of each fe workspace. */
+function appWorkspaceScriptFindings(file, project, name, pkg, scripts) {
+  const findings = [];
+  const expected = feAppPackageName(project, name);
+  if (pkg.name !== expected) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is named ${JSON.stringify(pkg.name ?? null)}; the fe app ${name} is the workspace ${expected}.`, { expected }));
+  const want = Object.keys(FE_APP_SCRIPTS).sort(byCodeUnit);
+  const off = [...new Set([...want, ...Object.keys(scripts)])].sort(byCodeUnit).filter((key) => scripts[key] !== FE_APP_SCRIPTS[key]);
+  if (off.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev, lint and typecheck; differs at ${off.join(', ')}).`, { scripts: off }));
+  return findings;
+}
+
+function packageWorkspaceScriptFindings(file, scripts) {
+  const findings = [];
+  const missing = FE_PACKAGE_SCRIPTS.filter((key) => typeof scripts[key] !== 'string' || !scripts[key]);
+  if (missing.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds, type-checks and lints (turbo builds it before the apps that import it).`, { scripts: missing }));
+  else if (scripts.lint !== WORKSPACE_LINT) findings.push(found(MONO_FE_WORKSPACE, file, `${file} lints with ${JSON.stringify(scripts.lint)}; a workspace lints with ${JSON.stringify(WORKSPACE_LINT)}, the one lint of the app scoped to it.`, { scripts: ['lint'] }));
+  return findings;
+}
+
 function workspaceManifestFindings(repoRoot, project, workspaces) {
   const findings = [];
   for (const folder of workspaces) {
@@ -75,21 +94,32 @@ function workspaceManifestFindings(repoRoot, project, workspaces) {
     const name = folder.split('/')[2];
     if (pkg.private !== true) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is not \`"private": true\`; a workspace of the app is never published.`));
     const scripts = pkg.scripts ?? {};
-    if (folder.startsWith('fe/apps/')) {
-      const expected = feAppPackageName(project, name);
-      if (pkg.name !== expected) findings.push(found(MONO_FE_WORKSPACE, file, `${file} is named ${JSON.stringify(pkg.name ?? null)}; the fe app ${name} is the workspace ${expected}.`, { expected }));
-      const want = Object.keys(FE_APP_SCRIPTS).sort();
-      const off = [...new Set([...want, ...Object.keys(scripts)])].sort().filter((key) => scripts[key] !== FE_APP_SCRIPTS[key]);
-      if (off.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has scripts ${JSON.stringify(scripts)}; an fe app workspace has exactly ${JSON.stringify(FE_APP_SCRIPTS)} (turbo runs build, dev, lint and typecheck; differs at ${off.join(', ')}).`, { scripts: off }));
-    } else {
-      const missing = FE_PACKAGE_SCRIPTS.filter((key) => typeof scripts[key] !== 'string' || !scripts[key]);
-      if (missing.length) findings.push(found(MONO_FE_WORKSPACE, file, `${file} has no ${missing.join(', ')} script; an fe package workspace builds, type-checks and lints (turbo builds it before the apps that import it).`, { scripts: missing }));
-      else if (scripts.lint !== WORKSPACE_LINT) findings.push(found(MONO_FE_WORKSPACE, file, `${file} lints with ${JSON.stringify(scripts.lint)}; a workspace lints with ${JSON.stringify(WORKSPACE_LINT)}, the one lint of the app scoped to it.`, { scripts: ['lint'] }));
-    }
+    if (folder.startsWith('fe/apps/')) findings.push(...appWorkspaceScriptFindings(file, project, name, pkg, scripts));
+    else findings.push(...packageWorkspaceScriptFindings(file, scripts));
   }
   return findings;
 }
 
+const nestProjectShape = (project) => JSON.stringify({ type: project.type, root: project.root, sourceRoot: project.sourceRoot });
+
+/** One finding per declared project whose type, root or sourceRoot departs from the application layout. */
+function nestProjectFindings(cli, projects, declared) {
+  const findings = [];
+  for (const name of projects.filter((project) => declared.includes(project))) {
+    const project = cli.projects[name] ?? {};
+    if (project.type !== 'application' || project.root !== `apps/${name}` || project.sourceRoot !== `apps/${name}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} project ${name} is ${nestProjectShape(project)}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
+  }
+  return findings;
+}
+
+/** The finding when the default project of nest-cli.json is no declared api app, or null. */
+function nestRootFinding(cli, beApps) {
+  const apis = beApps.filter((app) => app.kind === 'api').map((app) => app.name);
+  const rootApp = /^apps\/([^/]+)$/.exec(String(cli.root ?? ''))?.[1];
+  if (apis.includes(rootApp) && cli.sourceRoot === `apps/${rootApp}/src`) return null;
+  return found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has root ${JSON.stringify(cli.root ?? null)} and sourceRoot ${JSON.stringify(cli.sourceRoot ?? null)}; the default project is an api app (${apis.join(', ') || 'none declared'}): root apps/<api>, sourceRoot apps/<api>/src.`, { root: cli.root ?? null });
+}
+
 /** R145: be/nest-cli.json is the Nest monorepo of exactly the declared be apps. */
 function nestFindings(repoRoot, files, beApps) {
   if (!files.includes(NEST_CLI)) return [];
@@ -97,16 +127,12 @@ function nestFindings(repoRoot, files, beApps) {
   if (!cli) return [found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not readable JSON.`)];
   const findings = [];
   if (cli.monorepo !== true) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} is not \`"monorepo": true\`; the back end is a Nest monorepo of be/apps/<app>, even with one service.`));
-  const declared = beApps.map((app) => app.name).sort();
-  const projects = Object.keys(cli.projects ?? {}).sort();
+  const declared = beApps.map((app) => app.name).sort(byCodeUnit);
+  const projects = Object.keys(cli.projects ?? {}).sort(byCodeUnit);
   if (!sameList(projects, declared)) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has projects ${JSON.stringify(projects)}, but hfs.json declares the be apps ${JSON.stringify(declared)}; one project per declared app, no other.`, { projects, declared }));
-  for (const name of projects.filter((project) => declared.includes(project))) {
-    const project = cli.projects[name] ?? {};
-    if (project.type !== 'application' || project.root !== `apps/${name}` || project.sourceRoot !== `apps/${name}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} project ${name} is ${JSON.stringify({ type: project.type, root: project.root, sourceRoot: project.sourceRoot })}; it is {"type":"application","root":"apps/${name}","sourceRoot":"apps/${name}/src"}.`, { project: name }));
-  }
-  const apis = beApps.filter((app) => app.kind === 'api').map((app) => app.name);
-  const rootApp = /^apps\/([^/]+)$/.exec(String(cli.root ?? ''))?.[1];
-  if (!apis.includes(rootApp) || cli.sourceRoot !== `apps/${rootApp}/src`) findings.push(found(MONO_NEST_PROJECTS, NEST_CLI, `${NEST_CLI} has root ${JSON.stringify(cli.root ?? null)} and sourceRoot ${JSON.stringify(cli.sourceRoot ?? null)}; the default project is an api app (${apis.join(', ') || 'none declared'}): root apps/<api>, sourceRoot apps/<api>/src.`, { root: cli.root ?? null }));
+  findings.push(...nestProjectFindings(cli, projects, declared));
+  const rootFinding = nestRootFinding(cli, beApps);
+  if (rootFinding) findings.push(rootFinding);
   return findings;
 }
 
@@ -129,6 +155,40 @@ const packageOf = (specifier) => {
   return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
 };
 
+/** Records the first importing file of every package `file` imports without the workspace declaring it. */
+function collectUndeclaredImports(ts, file, text, isAlias, pkg, declared, missing) {
+  for (const { fileName: specifier } of ts.preProcessFile(text, true, true).importedFiles) {
+    if (specifier.startsWith('.') || specifier.startsWith('/') || isBuiltin(specifier) || isAlias(specifier)) continue;
+    const name = packageOf(specifier);
+    if (declared.has(name) || name === pkg.name) continue;
+    if (!missing.has(name)) missing.set(name, file);
+  }
+}
+
+/** The first importing file of every undeclared package a workspace's sources import, by package name. */
+function undeclaredImports(repoRoot, files, folder, pkg, declared, ts) {
+  const aliases = aliasesOf(ts, path.join(repoRoot, folder));
+  const isAlias = (specifier) => aliases.some((alias) => (alias.exact ? specifier === alias.prefix : specifier.startsWith(alias.prefix)));
+  const missing = new Map();
+  for (const file of files) {
+    if (!file.startsWith(`${folder}/`) || !SOURCE.test(file) || file.endsWith('.d.ts')) continue;
+    const text = readText(repoRoot, file);
+    if (text !== null) collectUndeclaredImports(ts, file, text, isAlias, pkg, declared, missing);
+  }
+  return missing;
+}
+
+function workspaceMissingDependencies(repoRoot, files, folder, names, ts) {
+  const manifest = `${folder}/${MANIFEST}`;
+  const pkg = readJson(repoRoot, manifest);
+  if (!pkg) return [];
+  const missing = undeclaredImports(repoRoot, files, folder, pkg, declaredIn(pkg), ts);
+  return [...missing].sort(byCodeUnit).map(([name, file]) => {
+    const declaration = names.get(name) ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`;
+    return found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${declaration}.`, { dependency: name, importedBy: file });
+  });
+}
+
 /** R146: what each fe workspace imports, it declares; the root declares no workspace package. */
 function workspaceDepFindings(repoRoot, files, workspaces) {
   const findings = [];
@@ -138,30 +198,7 @@ function workspaceDepFindings(repoRoot, files, workspaces) {
   if (!workspaces.length) return findings;
   const ts = typescriptFor(repoRoot);
   if (!ts) return [...findings, found(MONO_WORKSPACE_DEP, MANIFEST, 'the fe workspaces cannot be judged: no TypeScript resolves from the app; install the app\'s dependencies.', { missing: ['typescript'] })];
-  for (const folder of workspaces) {
-    const manifest = `${folder}/${MANIFEST}`;
-    const pkg = readJson(repoRoot, manifest);
-    if (!pkg) continue;
-    const declared = declaredIn(pkg);
-    const aliases = aliasesOf(ts, path.join(repoRoot, folder));
-    const isAlias = (specifier) => aliases.some((alias) => (alias.exact ? specifier === alias.prefix : specifier.startsWith(alias.prefix)));
-    const missing = new Map();
-    for (const file of files) {
-      if (!file.startsWith(`${folder}/`) || !SOURCE.test(file) || file.endsWith('.d.ts')) continue;
-      const text = readText(repoRoot, file);
-      if (text === null) continue;
-      for (const { fileName: specifier } of ts.preProcessFile(text, true, true).importedFiles) {
-        if (specifier.startsWith('.') || specifier.startsWith('/') || isBuiltin(specifier) || isAlias(specifier)) continue;
-        const name = packageOf(specifier);
-        if (declared.has(name) || name === pkg.name) continue;
-        if (!missing.has(name)) missing.set(name, file);
-      }
-    }
-    for (const [name, file] of [...missing].sort()) {
-      const sibling = names.get(name);
-      findings.push(found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${sibling ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`}.`, { dependency: name, importedBy: file }));
-    }
-  }
+  for (const folder of workspaces) findings.push(...workspaceMissingDependencies(repoRoot, files, folder, names, ts));
   return findings;
 }
 

package/runtime/scripts/hfs/rules/peer-integrations.mjs

@@ -11,6 +11,21 @@ import { found, readJson } from './read.mjs';
 const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
 const MANIFEST = 'package.json';
 const CATALOG_FILE = new URL('../../../knowledge/hfs/peer-integrations.yaml', import.meta.url);
+const WHITESPACE = /\s/;
+const isDigit = (char) => char >= '0' && char <= '9';
+
+/** The index of the first non-whitespace character of `text` at or after `from`. */
+function skipWhitespace(text, from) {
+  let index = from;
+  while (index < text.length && WHITESPACE.test(text[index])) index += 1;
+  return index;
+}
+
+/** The index after an optional range operator (`^`, `~`, `>`, `>=`, `=`) at `from`. */
+function skipOperator(text, from) {
+  if (text[from] === '>') return text[from + 1] === '=' ? from + 2 : from + 1;
+  return text[from] === '^' || text[from] === '~' || text[from] === '=' ? from + 1 : from;
+}
 
 /** The pairs of the catalog: [{ id, when: [{ package, major? }], requires, why }]. */
 function peerIntegrationPairs() {
@@ -21,8 +36,14 @@ function peerIntegrationPairs() {
 
 /** The major a dependency spec allows (`11.2.5`, `^11.0.0`, `~11.1`, `>=11 <12`), or null when the spec names none (a tag, a link, `*`). */
 function majorOf(spec) {
-  const match = /^\s*(?:[\^~]|>=?|=)?\s*v?(\d+)(?:\.|\s|$)/.exec(String(spec));
-  return match ? Number(match[1]) : null;
+  const text = String(spec);
+  let index = skipWhitespace(text, skipOperator(text, skipWhitespace(text, 0)));
+  if (text[index] === 'v') index += 1;
+  const digits = index;
+  while (isDigit(text[index] ?? '')) index += 1;
+  if (index === digits) return null;
+  const next = text[index];
+  return next === undefined || next === '.' || WHITESPACE.test(next) ? Number(text.slice(digits, index)) : null;
 }
 
 /** The findings of R111 over the app root package.json of `repoRoot`; `pairs` defaults to the catalog. */
@@ -31,7 +52,7 @@ export function peerIntegrationFindings({ repoRoot, files, pairs = peerIntegrati
   const pkg = readJson(repoRoot, MANIFEST);
   if (!pkg) return [];
   const runtime = pkg.dependencies ?? {};
-  const declared = { ...(pkg.devDependencies ?? {}), ...runtime };
+  const declared = { ...pkg.devDependencies, ...runtime };
   const findings = [];
   for (const pair of pairs) {
     const applies = pair.when.every((entry) => typeof declared[entry.package] === 'string' && (entry.major === undefined || majorOf(declared[entry.package]) === entry.major));

package/runtime/scripts/hfs/rules/pipeline.mjs

@@ -11,16 +11,65 @@ import { found, readJson, readText } from './read.mjs';
 const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
 const CI_FILE = '.github/workflows/ci.yml';
 const hfsPackage = '@starci/cli';
-const RUN_LINE = /^\s*(?:-\s+)?run:\s*(.+?)\s*$/;
-const HFS_LINT = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/cli(?:@(\S+))?|starci)\s+app\s+lint(\s.*)?$/;
-const NPM_RUN = /^npm run ([\w:.-]+)(?:\s+--\s+(.*))?$/;
+const RUN_PREFIX = /^\s*(?:-\s+)?run:/;
+const NPX_PREFIX = /^npx\s+(?:(?:--no-install|-y)\s+)?/;
+const LINT_COMMAND = /^(?:@starci\/cli(?:@(\S+))?|starci)\s+app\s+lint/;
+const NPM_RUN_PREFIX = 'npm run ';
+const SCRIPT_NAME = /^[\w:.-]+/;
+const ARGS_SEPARATOR = /^\s+--\s+/;
+const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
+const WHITESPACE = /\s/;
 
-const commandsOf = (text) => text.split(/\r?\n/).map((line) => RUN_LINE.exec(line)?.[1]).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
+/** The command of a workflow `run:` line (`run: <command>` or `- run: <command>`): the text after `run:` without surrounding whitespace, on one line. */
+function runCommandOf(line) {
+  const prefix = RUN_PREFIX.exec(line);
+  if (!prefix) return undefined;
+  const rest = line.slice(prefix[0].length);
+  const command = rest.trim();
+  if (command) return LINE_TERMINATOR.test(command) ? undefined : command;
+  return [...rest].findLast((character) => !LINE_TERMINATOR.test(character));
+}
+
+const commandsOf = (text) => text.split(/\r?\n/).map(runCommandOf).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
+
+/** The commands of a `a && b` chain: the whitespace around each `&&` belongs to the separator. */
+function chainedCommands(command) {
+  const pieces = command.split('&&');
+  const last = pieces.length - 1;
+  return pieces.map((piece, index) => {
+    const head = index > 0 ? piece.trimStart() : piece;
+    return index < last ? head.trimEnd() : head;
+  });
+}
+
+/** `npm run <script>` or `npm run <script> -- <args>` as { script, args } (args undefined without `--`), else null. */
+function parseNpmRun(command) {
+  if (!command.startsWith(NPM_RUN_PREFIX)) return null;
+  const rest = command.slice(NPM_RUN_PREFIX.length);
+  const script = SCRIPT_NAME.exec(rest)?.[0];
+  if (!script) return null;
+  const tail = rest.slice(script.length);
+  if (!tail) return { script, args: undefined };
+  const separator = ARGS_SEPARATOR.exec(tail);
+  const args = separator ? tail.slice(separator[0].length) : null;
+  return args !== null && !LINE_TERMINATOR.test(args) ? { script, args } : null;
+}
+
+/** { version } of a `starci app lint` command (`version` undefined when no @starci/cli version is named), else null. */
+function lintCommandOf(command) {
+  const rest = command.replace(NPX_PREFIX, '');
+  const match = LINT_COMMAND.exec(rest);
+  if (!match) return null;
+  const tail = rest.slice(match[0].length);
+  if (tail && !(WHITESPACE.test(tail[0]) && !LINE_TERMINATOR.test(tail.slice(1)))) return null;
+  return { version: match[1] };
+}
 
 /** `npm run <script> -- <args>` spelled out as the root package.json script it runs; any other command is itself. */
 function expanded(command, scripts) {
-  const run = NPM_RUN.exec(command);
-  return run && typeof scripts[run[1]] === 'string' ? `${scripts[run[1]]}${run[2] ? ` ${run[2]}` : ''}` : command;
+  const run = parseNpmRun(command);
+  if (!run || typeof scripts[run.script] !== 'string') return command;
+  return run.args ? `${scripts[run.script]} ${run.args}` : scripts[run.script];
 }
 
 /** The findings of R13 over the repository at `repoRoot`; `pins` is the parsed canon-pins.yaml pin map. */
@@ -30,10 +79,10 @@ export function pipelineFindings({ repoRoot, files, pins }) {
   const ci = files.includes(CI_FILE) ? readText(repoRoot, CI_FILE) : null;
   if (ci !== null) {
     const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
-    const lints = commandsOf(ci).flatMap((command) => expanded(command, scripts).split(/\s*&&\s*/)).map((command) => HFS_LINT.exec(command)).filter(Boolean);
+    const lints = commandsOf(ci).flatMap((command) => chainedCommands(expanded(command, scripts))).map(lintCommandOf).filter(Boolean);
     if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app lint\` (directly or through \`npm run lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'starci app lint' }));
-    else if (pinned && !lints.some((match) => match[1] === undefined || match[1] === pinned)) {
-      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));
+    else if (pinned && !lints.some((match) => match.version === undefined || match.version === pinned)) {
+      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0].version}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));
     }
   }
   return findings;

package/runtime/scripts/hfs/rules/proof-commands.mjs

@@ -39,6 +39,19 @@ function proofCommands(record) {
   return Object.entries(demands).flatMap(([kind, demand]) => (typeof demand?.command === 'string' ? [{ kind, command: demand.command }] : []));
 }
 
+function recordProofFindings({ repoRoot, file, record, tracked, resolver }) {
+  const findings = [];
+  for (const { kind, command } of proofCommands(record)) {
+    for (const target of commandFiles(command)) {
+      if (tracked.has(target) || fs.existsSync(path.join(repoRoot, target))) continue;
+      const classified = resolver.classifyPath(target);
+      if (classified.status === 'owned' && classified.tracking === 'ignored') continue;
+      findings.push(found(PROOF_COMMAND_FILE_MISSING, file, `${file} requiresProof.${kind}.command runs ${target}, which the repository does not hold; a proof command is runnable as written: create the file or rewrite the proof plan`, { kind, missing: target }));
+    }
+  }
+  return findings;
+}
+
 /**
  * The findings of R105 over the tracked paths `files` of the app at `repoRoot`; `resolver` names the ignored slots and `sides` the side
  * names of hfs.json (be, fe), the repositories a record of this app names.
@@ -54,14 +67,7 @@ export function proofCommandFindings({ repoRoot, files, resolver, sides }) {
     let record;
     try { record = parseYaml(text); } catch { continue; }
     if (typeof record?.repository === 'string' && !own.has(record.repository)) continue;
-    for (const { kind, command } of proofCommands(record)) {
-      for (const target of commandFiles(command)) {
-        if (tracked.has(target) || fs.existsSync(path.join(repoRoot, target))) continue;
-        const classified = resolver.classifyPath(target);
-        if (classified.status === 'owned' && classified.tracking === 'ignored') continue;
-        findings.push(found(PROOF_COMMAND_FILE_MISSING, file, `${file} requiresProof.${kind}.command runs ${target}, which the repository does not hold; a proof command is runnable as written: create the file or rewrite the proof plan`, { kind, missing: target }));
-      }
-    }
+    findings.push(...recordProofFindings({ repoRoot, file, record, tracked, resolver }));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/repo-local-checks.mjs

@@ -14,6 +14,16 @@ const LOCAL_RULE_FILE = /(?:^|\/)(?:eslint-local-rules|eslint-plugin|eslint-loca
 const CHECK_SCRIPT = /(?:^|\/)(?:scripts|tools)\/check-[^/]+$/;
 const RUNS_CHECK = /(?:^|[\s&|;(])(?:\.\/)?(?:scripts|tools)\/check-[^\s&|;)]+/;
 
+/** The findings of the package.json scripts of `file` that run a repository-local check. */
+function scriptFindings(repoRoot, file) {
+  const findings = [];
+  const pkg = readJson(repoRoot, file);
+  for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
+    if (RUNS_CHECK.test(String(command))) findings.push(found(REPO_LOCAL_CHECK, file, `${file} script ${name} runs a repository-local check (${String(command).slice(0, 80)}); delete the script, the check belongs to the .claude runtime`));
+  }
+  return findings;
+}
+
 /** The findings of R103 over the tracked paths `files` of the repository at `repoRoot`. */
 export function repoLocalCheckFindings({ repoRoot, files }) {
   const findings = [];
@@ -21,12 +31,7 @@ export function repoLocalCheckFindings({ repoRoot, files }) {
     if (file.includes('node_modules/')) continue;
     if (LOCAL_RULE_FILE.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
     else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (starci app check, the canons), so a repository has none to keep`));
-    else if (file === 'package.json' || file.endsWith('/package.json')) {
-      const pkg = readJson(repoRoot, file);
-      for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
-        if (RUNS_CHECK.test(String(command))) findings.push(found(REPO_LOCAL_CHECK, file, `${file} script ${name} runs a repository-local check (${String(command).slice(0, 80)}); delete the script, the check belongs to the .claude runtime`));
-      }
-    }
+    else if (file === 'package.json' || file.endsWith('/package.json')) findings.push(...scriptFindings(repoRoot, file));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/saga.mjs

@@ -19,6 +19,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 import { found, readJson, readText } from './read.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 const SAGA_STEP_COMPENSATION = 'BE_SAGA_STEP_COMPENSATION';
 const SAGA_STATE_VERSIONED = 'BE_SAGA_STATE_VERSIONED';
@@ -70,7 +71,9 @@ function statesVersion(ts, sourceFile) {
   const memberNames = (members) => new Map(members.filter((member) => ts.isPropertySignature(member) && ts.isIdentifier(member.name)).map((member) => [member.name.text, member.type]));
   for (const statement of sourceFile.statements) {
     if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
-    const members = ts.isInterfaceDeclaration(statement) ? statement.members : ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type) ? statement.type.members : null;
+    let members = null;
+    if (ts.isInterfaceDeclaration(statement)) members = statement.members;
+    else if (ts.isTypeAliasDeclaration(statement) && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
     if (members === null) continue;
     const named = memberNames(members);
     if (named.has('status') && named.get('version')?.kind === ts.SyntaxKind.NumberKeyword) versioned = true;
@@ -90,7 +93,125 @@ function readsEventId(ts, sourceFile) {
 }
 
 /** The sagas of the app: every folder of the saga kind (`be/src/features/saga/<saga>/`). */
-const featuresOf = (files) => [...new Set(files.map((file) => SAGA_FILE.exec(file)?.[1]).filter((feature) => feature !== undefined))].sort();
+const featuresOf = (files) => [...new Set(files.map((file) => SAGA_FILE.exec(file)?.[1]).filter((feature) => feature !== undefined))].sort(byCodeUnit);
+
+function filesForFeature(files, pattern, feature) {
+  return files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
+}
+
+function featureParts(files, feature) {
+  const steps = new Map(filesForFeature(files, STEP, feature).map((file) => [STEP.exec(file)[2], file]));
+  const compensations = new Map(filesForFeature(files, COMPENSATION, feature).map((file) => [COMPENSATION.exec(file)[2], file]));
+  const orchestrators = filesForFeature(files, ORCHESTRATOR, feature);
+  const states = new Map(filesForFeature(files, STATE, feature).map((file) => [STATE.exec(file)[2], file]));
+  return { steps, compensations, orchestrators, states };
+}
+
+function stepCompensationFindings(folder, steps, compensations, orchestrators) {
+  const findings = [];
+  for (const [stem, file] of steps) if (!compensations.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a saga step with no compensation: add ${folder}compensations/${stem}.compensation.ts, the command that undoes it; every forward step of a saga has one.`, { step: stem }));
+  for (const [stem, file] of compensations) if (!steps.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a compensation of no step: ${folder}steps/${stem}.saga-step.ts does not exist; a compensation undoes the step of the same name.`, { step: stem }));
+  if (orchestrators.length === 0 && (steps.size > 0 || compensations.size > 0)) findings.push(found(SAGA_STEP_COMPENSATION, folder, `${folder} holds steps or compensations but no orchestrator: add <saga>.saga.service.ts, the list of the steps and their compensations.`));
+  return findings;
+}
+
+function orchestratorFindings(ts, repoRoot, orchestrator, folder, steps, compensations, states) {
+  const text = readText(repoRoot, orchestrator);
+  if (text === null) return [];
+  const findings = [];
+  const sourceFile = parse(ts, text);
+  const imported = new Set(specifiersOf(ts, sourceFile).map((specifier) => path.posix.normalize(path.posix.join(path.posix.dirname(orchestrator), specifier))));
+  for (const file of [...steps.values(), ...compensations.values()]) {
+    if (!imported.has(file.replace(/\.ts$/, ''))) findings.push(found(SAGA_STEP_COMPENSATION, orchestrator, `${orchestrator} does not list ${file}: the orchestrator imports every step and every compensation of its saga, so a step nobody runs cannot hide.`, { step: file }));
+  }
+  const stem = ORCHESTRATOR.exec(orchestrator)[2];
+  const stateFile = states.get(stem);
+  if (stateFile === undefined) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} has no ${folder}${stem}.saga-state.ts: the persisted state of a run is typed there, with its status and its version fence.`, { saga: stem }));
+  if (!specifiersOf(ts, sourceFile).some((specifier) => STORE_MODULE.test(specifier))) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} does not use the fenced store of platform/saga: a run is persisted and moved only through it (every transition names the version it read), never by a write of its own.`, { saga: stem }));
+  return findings;
+}
+
+function stateFindings(ts, repoRoot, states) {
+  const findings = [];
+  for (const [stem, file] of states) {
+    const text = readText(repoRoot, file);
+    if (text !== null && !statesVersion(ts, parse(ts, text))) findings.push(found(SAGA_STATE_VERSIONED, file, `${file} exports no state type with a \`status\` and a \`version: number\`; a saga run is persisted with a version, the fence that stops a zombie delivery from moving it twice.`, { saga: stem }));
+  }
+  return findings;
+}
+
+const STEP_EVENT = { label: 'step', action: 'puts on the wire', key: (stem) => `step:${stem}` };
+const COMPENSATION_EVENT = { label: 'compensation', action: 'answers', key: (stem) => `compensation:${stem}` };
+
+/** Findings for the steps (or compensations) that name no event or an event no vendored contract declares; fills `eventOfFile`. */
+function declaredEventFindings(ts, repoRoot, kind, entries, events, eventOfFile) {
+  const findings = [];
+  for (const [stem, file] of entries) {
+    const text = readText(repoRoot, file);
+    const name = text === null ? null : eventOf(ts, parse(ts, text));
+    eventOfFile.set(kind.key(stem), name);
+    if (name === null) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind.label} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind.action}.`, { step: stem }));
+    else if (!events.has(name)) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names the event "${name}", which no be/contracts/<service>/events.json declares; every event of a saga is in a vendored contract.`, { step: stem, event: name }));
+  }
+  return findings;
+}
+
+/** Findings for compensation events whose contract does not name the step event it undoes, with the compensation paths found. */
+function compensatesFindings(compensations, events, eventOfFile) {
+  const findings = [];
+  const compensationPaths = [];
+  for (const [stem, file] of compensations) {
+    const compensationEvent = eventOfFile.get(COMPENSATION_EVENT.key(stem));
+    const stepEvent = eventOfFile.get(STEP_EVENT.key(stem));
+    if (compensationEvent && stepEvent && events.has(compensationEvent) && events.get(compensationEvent).compensates !== stepEvent) {
+      findings.push(found(SAGA_EVENT_CONTRACT, file, `${file}: the contract of "${compensationEvent}" (${events.get(compensationEvent).contract}) does not declare \`compensates: "${stepEvent}"\`; the failure event of a compensation says which step's event it undoes.`, { step: stem, event: compensationEvent }));
+    }
+    if (compensationEvent) compensationPaths.push({ file, stem, event: compensationEvent });
+  }
+  return { findings, compensationPaths };
+}
+
+function eventFindings(ts, repoRoot, steps, compensations, events) {
+  const eventOfFile = new Map();
+  const findings = [
+    ...declaredEventFindings(ts, repoRoot, STEP_EVENT, steps, events, eventOfFile),
+    ...declaredEventFindings(ts, repoRoot, COMPENSATION_EVENT, compensations, events, eventOfFile),
+  ];
+  const compensated = compensatesFindings(compensations, events, eventOfFile);
+  findings.push(...compensated.findings);
+  return { findings, compensationPaths: compensated.compensationPaths };
+}
+
+function consumerFindings(ts, repoRoot, feature, files) {
+  const findings = [];
+  for (const file of filesForFeature(files, CONSUMER, feature)) {
+    const text = readText(repoRoot, file);
+    if (text !== null && !readsEventId(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but never passes the id of the delivery on (\`message.eventId\`); the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
+  }
+  return findings;
+}
+
+function featureFindings(ts, repoRoot, files, feature, events) {
+  const { steps, compensations, orchestrators, states } = featureParts(files, feature);
+  const folder = `be/src/features/saga/${feature}/`;
+  const findings = stepCompensationFindings(folder, steps, compensations, orchestrators);
+  for (const orchestrator of orchestrators) findings.push(...orchestratorFindings(ts, repoRoot, orchestrator, folder, steps, compensations, states));
+  findings.push(...stateFindings(ts, repoRoot, states));
+  const eventResult = eventFindings(ts, repoRoot, steps, compensations, events);
+  findings.push(...eventResult.findings, ...consumerFindings(ts, repoRoot, feature, files));
+  return { findings, compensationPaths: eventResult.compensationPaths };
+}
+
+function compensationE2eFindings(compensationPaths, specs) {
+  const findings = [];
+  for (const { file, stem, event } of compensationPaths) {
+    const named = specs.filter(({ text }) => text.includes(event));
+    const expected = `be/src/tests/e2e/<area>/<name>.e2e-spec.ts`;
+    if (named.length === 0) findings.push(found(SAGA_E2E_MISSING, file, `${file}: the compensation path of "${event}" has no e2e spec; add ${expected}, which boots the apps with useTestWorld, drives the failure and reads the compensated state back.`, { step: stem, event }));
+    else if (!named.some(({ text }) => INJECTION.test(text))) findings.push(found(SAGA_E2E_MISSING, named[0].file, `${named[0].file} names "${event}" but injects no failure; the compensation path is proven with a fault through the world (an outage of an infra service or an app with \`during\`, \`cut\`, \`latency\`, a fake's \`failNext\`, \`interruptDatabase\`), not only the happy flow.`, { step: stem, event }));
+  }
+  return findings;
+}
 
 /** Findings of R169 to R173 over the tracked paths `files` of the app at `repoRoot`. */
 export function sagaFindings({ repoRoot, files }) {
@@ -98,73 +219,19 @@ export function sagaFindings({ repoRoot, files }) {
   if (features.length === 0) return [];
   const ts = typescriptFor(repoRoot);
   if (ts === null) return [];
-  const findings = [];
   const events = new Map();
   for (const contract of files.filter((file) => CONTRACT.test(file))) {
     for (const [name, event] of Object.entries(readJson(repoRoot, contract)?.events ?? {})) events.set(name, { contract, ...event });
   }
   const specs = files.filter((file) => E2E_SPEC.test(file)).map((file) => ({ file, text: readText(repoRoot, file) ?? '' })).filter(({ text }) => USE_TEST_WORLD.test(text));
+  const findings = [];
   const compensationPaths = [];
   for (const feature of features) {
-    const under = (pattern) => files.filter((file) => pattern.test(file) && pattern.exec(file)[1] === feature);
-    const steps = new Map(under(STEP).map((file) => [STEP.exec(file)[2], file]));
-    const compensations = new Map(under(COMPENSATION).map((file) => [COMPENSATION.exec(file)[2], file]));
-    const orchestrators = under(ORCHESTRATOR);
-    const states = new Map(under(STATE).map((file) => [STATE.exec(file)[2], file]));
-    const folder = `be/src/features/saga/${feature}/`;
-    // R169
-    for (const [stem, file] of steps) if (!compensations.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a saga step with no compensation: add ${folder}compensations/${stem}.compensation.ts, the command that undoes it; every forward step of a saga has one.`, { step: stem }));
-    for (const [stem, file] of compensations) if (!steps.has(stem)) findings.push(found(SAGA_STEP_COMPENSATION, file, `${file} is a compensation of no step: ${folder}steps/${stem}.saga-step.ts does not exist; a compensation undoes the step of the same name.`, { step: stem }));
-    if (orchestrators.length === 0 && (steps.size > 0 || compensations.size > 0)) findings.push(found(SAGA_STEP_COMPENSATION, folder, `${folder} holds steps or compensations but no orchestrator: add <saga>.saga.service.ts, the list of the steps and their compensations.`));
-    for (const orchestrator of orchestrators) {
-      const text = readText(repoRoot, orchestrator);
-      if (text === null) continue;
-      const sourceFile = parse(ts, text);
-      const imported = specifiersOf(ts, sourceFile).map((specifier) => path.posix.normalize(path.posix.join(path.posix.dirname(orchestrator), specifier)));
-      for (const file of [...steps.values(), ...compensations.values()]) {
-        if (!imported.includes(file.replace(/\.ts$/, ''))) findings.push(found(SAGA_STEP_COMPENSATION, orchestrator, `${orchestrator} does not list ${file}: the orchestrator imports every step and every compensation of its saga, so a step nobody runs cannot hide.`, { step: file }));
-      }
-      // R170
-      const stem = ORCHESTRATOR.exec(orchestrator)[2];
-      const stateFile = states.get(stem);
-      if (stateFile === undefined) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} has no ${folder}${stem}.saga-state.ts: the persisted state of a run is typed there, with its status and its version fence.`, { saga: stem }));
-      if (!specifiersOf(ts, sourceFile).some((specifier) => STORE_MODULE.test(specifier))) findings.push(found(SAGA_STATE_VERSIONED, orchestrator, `${orchestrator} does not use the fenced store of platform/saga: a run is persisted and moved only through it (every transition names the version it read), never by a write of its own.`, { saga: stem }));
-    }
-    for (const [stem, file] of states) {
-      const text = readText(repoRoot, file);
-      if (text !== null && !statesVersion(ts, parse(ts, text))) findings.push(found(SAGA_STATE_VERSIONED, file, `${file} exports no state type with a \`status\` and a \`version: number\`; a saga run is persisted with a version, the fence that stops a zombie delivery from moving it twice.`, { saga: stem }));
-    }
-    // R171
-    const eventOfFile = new Map();
-    for (const [kind, map] of [['step', steps], ['compensation', compensations]]) {
-      for (const [stem, file] of map) {
-        const text = readText(repoRoot, file);
-        const name = text === null ? null : eventOf(ts, parse(ts, text));
-        eventOfFile.set(`${kind}:${stem}`, name);
-        if (name === null) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names no event: a ${kind} of a saga declares \`readonly event = "<name>"\`, the event of the contract it ${kind === 'step' ? 'puts on the wire' : 'answers'}.`, { step: stem }));
-        else if (!events.has(name)) findings.push(found(SAGA_EVENT_CONTRACT, file, `${file} names the event "${name}", which no be/contracts/<service>/events.json declares; every event of a saga is in a vendored contract.`, { step: stem, event: name }));
-      }
-    }
-    for (const [stem, file] of compensations) {
-      const compensationEvent = eventOfFile.get(`compensation:${stem}`);
-      const stepEvent = eventOfFile.get(`step:${stem}`);
-      if (compensationEvent && stepEvent && events.has(compensationEvent) && events.get(compensationEvent).compensates !== stepEvent) {
-        findings.push(found(SAGA_EVENT_CONTRACT, file, `${file}: the contract of "${compensationEvent}" (${events.get(compensationEvent).contract}) does not declare \`compensates: "${stepEvent}"\`; the failure event of a compensation says which step's event it undoes.`, { step: stem, event: compensationEvent }));
-      }
-      if (compensationEvent) compensationPaths.push({ file, stem, event: compensationEvent });
-    }
-    // R172
-    for (const file of under(CONSUMER)) {
-      const text = readText(repoRoot, file);
-      if (text !== null && !readsEventId(ts, parse(ts, text))) findings.push(found(SAGA_CONSUMER_DEDUPE, file, `${file} is a consumer of the saga ${feature} but never passes the id of the delivery on (\`message.eventId\`); the saga takes every event through the inbox, so the consumer hands the id to its command.`, { feature }));
-    }
+    const result = featureFindings(ts, repoRoot, files, feature, events);
+    findings.push(...result.findings);
+    compensationPaths.push(...result.compensationPaths);
   }
   // R173
-  for (const { file, stem, event } of compensationPaths) {
-    const named = specs.filter(({ text }) => text.includes(event));
-    const expected = `be/src/tests/e2e/<area>/<name>.e2e-spec.ts`;
-    if (named.length === 0) findings.push(found(SAGA_E2E_MISSING, file, `${file}: the compensation path of "${event}" has no e2e spec; add ${expected}, which boots the apps with useTestWorld, drives the failure and reads the compensated state back.`, { step: stem, event }));
-    else if (!named.some(({ text }) => INJECTION.test(text))) findings.push(found(SAGA_E2E_MISSING, named[0].file, `${named[0].file} names "${event}" but injects no failure; the compensation path is proven with a fault through the world (an outage of an infra service or an app with \`during\`, \`cut\`, \`latency\`, a fake's \`failNext\`, \`interruptDatabase\`), not only the happy flow.`, { step: stem, event }));
-  }
+  findings.push(...compensationE2eFindings(compensationPaths, specs));
   return findings;
 }