@starci/eslint-canon-fe 6.0.2 → 7.1.0

package/runtime/scripts/checks/architecture/unit-spec-providers.mjs

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+import { constructorDependencies } from './constructor-deps.mjs';
+import { treeOf } from './required-files.mjs';
+
+/**
+ * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
+ * subject with `Test.createTestingModule({ providers: [...] })`, and that providers array EQUALS the constructor
+ * dependencies of the service under test: the service class first, then one provider for each constructor parameter.
+ *
+ * The service under test is the sibling `<name>.service.ts` of every `<name>.service.spec.ts` under src/ or apps/ (a spec is
+ * outside the production program, so it is read from disk). A parameter decorated with a custom `Inject<Thing>()` provides
+ * the token that decorator's `injector<T>(TOKEN)` names; an undecorated parameter of a class type provides that class (see
+ * constructor-deps.mjs). Providers are matched by the exported name of the imported binding (`import { CACHE as C }` is
+ * CACHE), never by text. A provider is a class, or `{ provide: TOKEN, useValue: double }` and nothing else.
+ *
+ * Findings: an extra provider, a missing provider, a service that is not the first provider, a dependency whose token cannot
+ * be resolved, a spec with no createTestingModule providers array, and a provider that is neither a class nor
+ * `{ provide, useValue }`. Which double a `useValue` is, and whether other specs exist at all, are other rules' business.
+ */
+export const UNIT_SPEC_PROVIDERS_RULE_IDS = ['BE_SPEC_QUALITY'];
+
+const RULE = 'BE_SPEC_QUALITY';
+const SERVICE_SPEC = /\.service\.spec\.ts$/u;
+const SPEC_ROOT = /^(?:src|apps)\//u;
+
+/** local name -> {name, module} for every named import of a source file. */
+function importsOf(ts, sourceFile) {
+  const imports = new Map();
+  for (const statement of sourceFile.statements) {
+    const bindings = ts.isImportDeclaration(statement) ? statement.importClause?.namedBindings : null;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const element of bindings.elements) imports.set(element.name.text, { name: (element.propertyName ?? element.name).text, module: statement.moduleSpecifier.text });
+  }
+  return imports;
+}
+
+/** The `Test.createTestingModule(...)` calls of a spec. */
+function testingModules(ts, sourceFile) {
+  const calls = [];
+  const visit = node => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'createTestingModule') calls.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return calls;
+}
+
+const literalKey = (ts, property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
+
+export function checkUnitSpecProviders(input) {
+  const { config, graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let specs = 0;
+  const tree = treeOf(config.root);
+  for (const rel of [...tree.files].filter(file => SPEC_ROOT.test(file) && SERVICE_SPEC.test(file)).sort()) {
+    const abs = path.join(config.root, ...rel.split('/'));
+    if (!fs.existsSync(abs)) continue;
+    specs += 1;
+    const sourceFile = ts.createSourceFile(abs, fs.readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true);
+    const report = (node, message) => violations.push({ ruleId: RULE, path: rel, ...kit.at(rel, sourceFile, node), message });
+    const imports = importsOf(ts, sourceFile);
+    const nameOf = identifier => imports.get(identifier.text)?.name ?? identifier.text;
+
+    const serviceRel = rel.replace(/\.spec\.ts$/u, '.ts');
+    const serviceFile = graph.files.get(serviceRel);
+    if (!serviceFile) { report(sourceFile, `${rel} has no ${path.posix.basename(serviceRel)} beside it; a service spec sits next to the service it tests.`); continue; }
+
+    const modules = testingModules(ts, sourceFile);
+    if (!modules.length) { report(sourceFile, `${rel} never calls Test.createTestingModule({ providers: [...] }); build the service from a testing module holding exactly its constructor dependencies.`); continue; }
+
+    for (const call of modules) {
+      const options = call.arguments[0];
+      const property = options && ts.isObjectLiteralExpression(options) ? options.properties.find(item => literalKey(ts, item) === 'providers') : null;
+      const list = property && ts.isPropertyAssignment(property) && ts.isArrayLiteralExpression(property.initializer) ? property.initializer : null;
+      if (!list) { report(call, `${rel}: Test.createTestingModule has no literal \`providers\` array; list the service and each constructor dependency there.`); continue; }
+
+      const provided = []; // [{name, node}]
+      let readable = true;
+      for (const element of list.elements) {
+        if (ts.isIdentifier(element)) { provided.push({ name: nameOf(element), node: element, isClass: true }); continue; }
+        if (ts.isObjectLiteralExpression(element)) {
+          const keys = element.properties.map(item => literalKey(ts, item));
+          const provide = element.properties.find(item => literalKey(ts, item) === 'provide');
+          const value = provide && ts.isPropertyAssignment(provide) ? provide.initializer : null;
+          if (keys.length === 2 && keys.includes('useValue') && value && ts.isIdentifier(value)) { provided.push({ name: nameOf(value), node: element, isClass: false }); continue; }
+        }
+        readable = false;
+        report(element, `${rel}: a provider is a class or \`{ provide: TOKEN, useValue: double }\` and nothing else (no useClass, useFactory, useExisting, spread or computed token).`);
+      }
+      if (!readable) continue;
+
+      const first = list.elements[0];
+      const serviceName = first && ts.isIdentifier(first) ? imports.get(first.text) : null;
+      const target = serviceName ? path.posix.normalize(path.posix.join(path.posix.dirname(rel), serviceName.module)).replace(/\.[cm]?[jt]s$/u, '') : null;
+      const serviceClass = serviceName && target === serviceRel.replace(/\.ts$/u, '')
+        ? serviceFile.sourceFile.statements.find(statement => ts.isClassDeclaration(statement) && statement.name?.text === serviceName.name) : null;
+      if (!serviceClass) { report(first ?? list, `${rel}: the first provider is the service under test, imported from ./${path.posix.basename(serviceRel, '.ts')}.`); continue; }
+
+      const dependencies = constructorDependencies(kit, serviceFile, serviceClass);
+      const expected = [];
+      for (const dependency of dependencies) {
+        if (dependency.kind === 'unresolved') {
+          report(list, `${rel}: a constructor dependency of ${serviceName.name} cannot be resolved to a token (${dependency.reason}), so its provider cannot be checked; inject it through an exported Inject<Thing>() decorator or a class type.`);
+          continue;
+        }
+        expected.push(dependency.name);
+      }
+      const remaining = [...expected];
+      for (const item of provided.slice(1)) {
+        const index = remaining.indexOf(item.name);
+        if (index === -1) report(item.node, `${rel}: ${item.name} is provided but is not a constructor dependency of ${serviceName.name}; a unit spec provides exactly what the constructor needs.`);
+        else remaining.splice(index, 1);
+      }
+      for (const name of remaining) report(list, `${rel}: ${name} is a constructor dependency of ${serviceName.name} but is not provided; add \`{ provide: ${name}, useValue: double }\` (or the class itself) to the providers.`);
+    }
+  }
+  return { violations, coverage: { status: 'checked', specs, files: graph.files.size } };
+}

package/runtime/scripts/checks/common.mjs

@@ -0,0 +1,44 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/** Whether `target` is `root` itself or inside it (filesystem paths, either separator). */
+export function isInside(root, target) {
+  const relative = path.relative(root, target);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/** True when this module is the process entry point (`node file.mjs`, not an import). */
+/** The real path of a file, or its resolved path when it cannot be read (a missing file is never the entry module). */
+const realPathOf = (file) => { try { return fs.realpathSync.native(path.resolve(file)); } catch { return path.resolve(file); } };
+/**
+ * True when the module at `metaUrl` is the process entry point. Both sides are compared as REAL paths: Node gives a module
+ * its symlink-resolved URL, while argv[1] keeps the path it was started with, so an entry reached through a node_modules
+ * junction or symlink (a lane worktree, an npx shim) would otherwise look like an import and silently do nothing.
+ */
+export const isMain = (metaUrl, argv = process.argv) => Boolean(argv[1]) && realPathOf(argv[1]) === realPathOf(fileURLToPath(metaUrl));
+
+/**
+ * Every entry under `dir` that is not a directory, depth-first; `filter` sees the entry name and full
+ * path. `sorted` sorts each directory's entries by name (default: readdir order). `exclude`
+ * applies to files and directories before descent; `maxDepth` counts from the starting dir.
+ */
+export function walkFiles(dir, {filter = () => true, sorted = false, exclude = () => false,
+  maxDepth = Infinity, ignoreReadErrors = false} = {}) {
+  const out = [];
+  const visit = (current, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = fs.readdirSync(current, {withFileTypes: true}); }
+    catch (error) { if (ignoreReadErrors) return; throw error; }
+    if (sorted) entries = entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (exclude(entry.name, full, entry)) continue;
+      if (entry.isDirectory()) visit(full, depth + 1);
+      else if (filter(entry.name, full)) out.push(full);
+    }
+  };
+  visit(dir, 0);
+  return out;
+}

package/runtime/scripts/checks/typescript-programs.mjs

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+// One TypeScript program per (compiler, root names, compiler options, project references) inside a program run, and
+// one value per (kind, compiler, input) for what callers derive from those programs (the architecture context).
+// check-scoped-lint opens one run around its architecture check and its script checkers and releases it before
+// ESLint and the base measurement, so nothing built here outlives the run that built it. Outside a run every call
+// builds afresh.
+const runs = new AsyncLocalStorage();
+
+/** A program run: run(fn) shares what is built inside fn; release() drops it. */
+export function typeScriptProgramRun() {
+  const values = new Map();
+  return {
+    run: fn => runs.run(values, fn),
+    release: () => values.clear(),
+  };
+}
+
+function keyOf(value) {
+  if (value === undefined) return 'u';
+  if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    const items = value.map(keyOf);
+    return items.includes(null) ? null : `[${items.join(',')}]`;
+  }
+  if (typeof value !== 'object' || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) return null;
+  const entries = [];
+  for (const name of Object.keys(value).sort()) {
+    const item = keyOf(value[name]);
+    if (item === null) return null;
+    entries.push(`${JSON.stringify(name)}:${item}`);
+  }
+  return `{${entries.join(',')}}`;
+}
+
+/**
+ * build(), shared inside a program run by every caller that asks for the same kind, compiler and input. An input that
+ * is not plain data (a function, a class instance) is never shared.
+ */
+export function sharedInProgramRun(kind, ts, input, build) {
+  const values = runs.getStore();
+  const key = values ? keyOf(input) : null;
+  if (key === null) return build();
+  let byKey = values.get(ts);
+  if (!byKey) values.set(ts, byKey = new Map());
+  const id = `${kind}\0${key}`;
+  if (!byKey.has(id)) byKey.set(id, build());
+  return byKey.get(id);
+}
+
+/** ts.createProgram, shared inside a program run. */
+export function createTypeScriptProgram(ts, { rootNames, options, projectReferences }) {
+  return sharedInProgramRun('program', ts, { rootNames, options, projectReferences },
+    () => ts.createProgram({ rootNames, options, projectReferences }));
+}
+
+/** Read and expand a tsconfig with the caller's TypeScript compiler and optional tracked file reader. */
+export function readTypeScriptProject(ts, configFile, readFile = ts.sys.readFile) {
+  const read = ts.readConfigFile(configFile, readFile);
+  if (read.error) return { read, parsed: null };
+  const host = readFile === ts.sys.readFile ? ts.sys : { ...ts.sys, readFile };
+  return { read, parsed: ts.parseJsonConfigFileContent(read.config, host, path.dirname(configFile), undefined, configFile) };
+}
+
+/** Resolve a project reference with the compiler's API, including older compiler fallback. */
+export function typeScriptProjectReferencePath(ts, reference) {
+  if (typeof ts.resolveProjectReferencePath === 'function') return ts.resolveProjectReferencePath(reference);
+  return path.extname(reference.path) ? reference.path : path.join(reference.path, 'tsconfig.json');
+}
+
+/** Resolve an import using the selected project's compiler options. */
+export function resolveTypeScriptModule(ts, specifier, from, options, host = ts.sys) {
+  return ts.resolveModuleName(specifier, from, options, host).resolvedModule?.resolvedFileName;
+}
+
+/** Configuration imports prefer Node's package resolution, then the selected TypeScript project. */
+export function resolveNodeOrTypeScriptModule(ts, specifier, from, options, host = ts.sys) {
+  try { return createRequire(from).resolve(specifier); }
+  catch { return resolveTypeScriptModule(ts, specifier, from, options, host); }
+}

package/runtime/scripts/lib/hfs-allows.mjs

@@ -26,6 +26,21 @@ export function relativeToRoot(file, root) {
   return root && file.startsWith(`${root}/`) ? file.slice(root.length + 1) : path.posix.basename(file);
 }
 
+/**
+ * Whether the slot that owns `file` names it in `requires` or `allows` (and does not forbid it); null when no enabled slot
+ * owns it. Unlike allowsFile it judges a slot that lists only `requires` too, so a folder closed by its slot (an app's
+ * src/) is read from the slot and never from a check's own list.
+ */
+export function slotAdmitsFile(resolver, file) {
+  const classified = resolver.classifyPath(file);
+  if (classified.status === 'no-slot' || classified.status === 'ambiguous' || !classified.slot) return null;
+  const slot = resolver.slot(classified.slot);
+  const relative = relativeToRoot(classified.path, classified.root);
+  const hit = matchersOf([...(slot.requires ?? []), ...(slot.allows ?? [])], classified.bindings).find(matcher => matcher.expression.test(relative));
+  const forbidden = matchersOf(slot.forbids, classified.bindings).find(matcher => matcher.expression.test(relative) || matcher.expression.test(`${relative}/`));
+  return Boolean(hit) && !forbidden;
+}
+
 /**
  * {slot, root, relative, allowed, entry?, forbiddenBy?} for a repository-relative file, or null when no enabled slot owns
  * it or the slot names no `allows`. `allowed` is true when the relative path matches a `requires` or `allows` entry.

package/runtime/scripts/lib/hfs-path-findings.mjs

@@ -0,0 +1,84 @@
+// hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `hfs check`
+// (checkRepo) runs it over the tracked tree and keeps the findings that have no TypeScript file to sit on; the lint canon's project graph
+// (scripts/lib/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
+//   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
+//   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
+import path from 'node:path';
+import { allowsFile } from './hfs-allows.mjs';
+import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
+import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
+import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SOURCE_ROOT = /^(?:src|apps)\//;
+const FREE_NAMES = new Set(['index.ts', 'main.ts']);
+const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
+
+/**
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
+ * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
+ * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
+ */
+function sourceFormFindings({ files, resolver }) {
+  const { suffixes, bannedSuffixes } = resolver.ruleParams();
+  // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
+  // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
+  const boundSuffixes = new Map();
+  for (const slot of resolver.slots()) {
+    const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
+    if (bound && suffixes.includes(bound)) boundSuffixes.set(bound, slot);
+  }
+  const findings = [];
+  for (const file of files) {
+    if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) continue;
+    const c = resolver.classifyPath(file);
+    if (c.status !== 'owned' || c.tracking === 'ignored') continue;
+    const base = path.posix.basename(file);
+    if (FREE_NAMES.has(base)) continue;
+    // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
+    const slot = resolver.slot(c.slot);
+    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
+    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
+    const admitted = allowsFile(resolver, file);
+    if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
+    if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
+    const parts = base.slice(0, -'.ts'.length).split('.');
+    const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
+    if (banned) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})` });
+    } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
+    } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` });
+    }
+  }
+  return findings;
+}
+
+/** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
+export function pathFindings({ files, resolver, profile }) {
+  const findings = [];
+  for (const file of files) {
+    if (profile === 'fe' && isFeTestPath(file)) continue;   // a test path of a front end is FE_NO_TESTS's, the one finding of that file
+    const c = resolver.classifyPath(file);
+    if (c.status === 'no-slot') {
+      findings.push({ code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
+    } else if (c.status === 'ambiguous') {
+      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
+    } else if (c.status === 'not-enabled') {
+      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
+    } else if (c.status === 'forbidden') {
+      const slot = resolver.slot(c.slot);
+      if (slotOwnsSecrets(slot)) continue;   // the secret scan reports the file (R06): one finding per file
+      const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
+      findings.push({ code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
+    } else if (c.tracking === 'ignored') {
+      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
+    }
+  }
+
+  if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+  // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
+  return findings.map((finding) => ({ ...finding, origin: 'repo' }));
+}

package/runtime/scripts/lib/hfs-rules/fe-no-tests.mjs

@@ -0,0 +1,47 @@
+// fe-no-tests.mjs - FE_NO_TESTS (R97): a front-end repository has no tests by standard (owner 2026-09-30). There is no exception: a spec
+// anywhere in a front-end repository is a finding, `scripts/` included.
+//   - a tracked test file: `*.spec.*`, `*.test.*`, `*-spec.*` (also `*.e2e-spec.*`);
+//   - a tracked test directory: `e2e/`, `__tests__/`, `__mocks__/` or `test-support/`;
+//   - a tracked test-tool file: `vitest.*`, `jest.*`, `playwright.*` (config, setup, workspace), `cypress.config.*`, `tsconfig.e2e.json`, `e2e.yml`;
+//   - a test script in a package.json: a script named `test`, `test:*` (or with a pre/post prefix), or one that runs a test runner;
+//   - a test dependency in a package.json: a test runner, a test environment, testing-library or an axe package.
+// The check reads the tracked tree and the manifests only. One finding per path (a manifest: one per script or dependency), and it is
+// the only finding of a test file: the slot check leaves these paths to it (isFeTestPath).
+import { found, readJson } from './read.mjs';
+
+export const FE_NO_TESTS = 'FE_NO_TESTS';
+const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
+const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
+const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
+const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
+const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
+const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+/** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
+export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);
+
+/** The findings of R97 over the tracked paths `files` of a front-end repository at `repoRoot`. */
+export function feNoTestsFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const file of files) {
+    if (isFeTestPath(file)) {
+      const what = SPEC_FILE.test(file) ? 'a test file' : TEST_DIRECTORY.test(file) ? 'inside a test directory' : 'test tooling';
+      findings.push(found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`));
+      continue;
+    }
+    if (file !== 'package.json' && !file.endsWith('/package.json')) continue;
+    if (file.includes('node_modules/')) continue;
+    const pkg = readJson(repoRoot, file);
+    if (!pkg || typeof pkg !== 'object') continue;
+    for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+      if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command))) findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
+    }
+    for (const section of DEPENDENCY_SECTIONS) {
+      for (const name of Object.keys(pkg[section] ?? {})) {
+        if (TEST_DEPENDENCY.test(name)) findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/read.mjs

@@ -0,0 +1,28 @@
+// read.mjs - what the tree checks of hfs-check.mjs share: one bounded text read and the shape of a finding.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
+export const MAX_READ_BYTES = 1024 * 1024;
+
+/** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
+export function readText(repoRoot, rel) {
+  try {
+    const target = path.join(repoRoot, rel);
+    if (fs.statSync(target).size > MAX_READ_BYTES) return null;
+    const text = fs.readFileSync(target, 'utf8');
+    return text.includes('\0') ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+/** The JSON of `rel`, or null when it is absent or not JSON. */
+export function readJson(repoRoot, rel) {
+  const text = readText(repoRoot, rel);
+  if (text === null) return null;
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** One error finding of `code` on `file`; `extra` carries the finding's own fields. */
+export const found = (code, file, message, extra = {}) => ({ code, level: 'error', path: file, ...extra, message });

package/runtime/scripts/lib/hfs-rules/secrets.mjs

@@ -0,0 +1,54 @@
+// secrets.mjs - HFS_PLAINTEXT_SECRET (R06): secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc` sops envelopes.
+// It judges the tracked tree with the one list of secret shapes the push scan refuses (scripts/lib/secret-patterns.mjs):
+//   - a tracked file that is a secret by being (an env file, a key file, a credentials file, a plaintext member of a
+//     secrets directory), and every path a forbidden `external` slot names HFS_PLAINTEXT_SECRET for (the slot manifest);
+//   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
+//   - a line of any other tracked text file that matches a secret pattern.
+// A finding names the file, the line and the pattern, never the value.
+import { FORBIDDEN_FILES, secretHits } from '../secret-patterns.mjs';
+import { isSopsEnvelope } from '../test-secrets.mjs';
+import { found, readText } from './read.mjs';
+
+export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
+/** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
+const NOT_SCANNED = /(^|\/)package-lock\.json$/;
+
+/** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
+export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET) === true;
+
+/**
+ * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
+ * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`hfs work-hygiene`) reads the staged blob: one judgement.
+ */
+export function secretFileFindings({ file, text }) {
+  const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
+  if (being) return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
+  if (text === null || text === undefined || NOT_SCANNED.test(file)) return [];
+  if (file.endsWith('.enc')) return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
+  const findings = [];
+  const lines = text.split(/\r?\n/);
+  const seen = new Set();
+  for (let index = 0; index < lines.length; index += 1) {
+    for (const pattern of secretHits(file, lines[index])) {
+      if (seen.has(pattern)) continue;
+      seen.add(pattern);
+      findings.push(found(PLAINTEXT_SECRET, file, `${file}:${index + 1} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line: index + 1, pattern }));
+    }
+  }
+  return findings;
+}
+
+/** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
+export function secretFindings({ repoRoot, files, resolver }) {
+  const findings = [];
+  for (const file of files) {
+    const slot = resolver.classifyPath(file);
+    if (slot.status === 'forbidden' && slotOwnsSecrets(resolver.slot(slot.slot))) {
+      findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${slot.goesTo ? `; it belongs at ${slot.goesTo}` : ''}`, { slot: slot.slot, goesTo: slot.goesTo }));
+      continue;
+    }
+    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file) }));
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/spec-placement.mjs

@@ -0,0 +1,29 @@
+// spec-placement.mjs - BE_SPEC_PLACEMENT (R102): a back-end spec or test file lives in one of the four test layers and nowhere else.
+//   - a unit spec is `<name>.service.spec.ts` beside its service, in a slot whose `tests` is `unit-beside` (the slot and the lint rule
+//     `unit-test-colocated` judge the name);
+//   - integration, e2e and contract specs are `src/tests/{integration,e2e,contract}/...`, the slots whose `tests` is `e2e`;
+// Every other tracked `*.spec.*`, `*.test.*` or `*-spec.*` file is a finding, `scripts/` and `tools/` included: an operational script
+// carries no spec, and a spec that guards one moves into a layer or goes. A file no slot owns (`tools/x.spec.ts`) is judged too, so the
+// finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
+import { found } from './read.mjs';
+
+export const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
+const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
+const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);
+
+/** True for a file name that is a spec or a test. */
+export const isSpecFile = (file) => SPEC_FILE.test(file);
+
+/** The findings of R102 over the tracked paths `files` of a back-end repository; `resolver` names the slots. */
+export function specPlacementFindings({ files, resolver }) {
+  const findings = [];
+  for (const file of files) {
+    if (!isSpecFile(file) || file.includes('node_modules/')) continue;
+    const classified = resolver.classifyPath(file);
+    const slot = classified.status === 'owned' ? resolver.slot(classified.slot) : null;
+    if (slot && TEST_SLOT_TESTS.has(slot.tests)) continue;
+    const where = slot ? `slot ${slot.id}` : 'no slot';
+    findings.push(found(SPEC_PLACEMENT, file, `${file} is a spec outside the test layers (${where}); a unit spec is <name>.service.spec.ts beside its service and an integration, e2e or contract spec sits under src/tests/{integration,e2e,contract}; an operational script or a tool carries no spec`));
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-slots.mjs

@@ -150,7 +150,8 @@ function manifestShapeProblems(m) {
   const rp = m.ruleParams;
   if (!isPlainObject(rp) || Object.keys(rp).some((k) => !PROFILES.includes(k)) || !PROFILES.every((p) => isPlainObject(rp[p]))) bad.push('ruleParams must be a map with be and fe');
   else {
-    if (!fileLinesOk(rp.be.fileLines) || !blockOk(rp.be.duplicateBlock) || Object.keys(rp.be).length !== 5) bad.push('ruleParams.be needs fileLines {soft, hardGrowth}, duplicateBlock {lines >= 2, tokens >= 1}, infraOwners, suffixes and bannedSuffixes');
+    if (!fileLinesOk(rp.be.fileLines) || !blockOk(rp.be.duplicateBlock) || Object.keys(rp.be).length !== 7) bad.push('ruleParams.be needs fileLines {soft, hardGrowth}, duplicateBlock {lines >= 2, tokens >= 1}, infraOwners, specDoubles, suffixes, bannedSuffixes and contractShape {helper}');
+    if (!isPlainObject(rp.be.contractShape) || Object.keys(rp.be.contractShape).length !== 1 || !/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(String(rp.be.contractShape.helper))) bad.push('ruleParams.be.contractShape must be {helper: <identifier>}');
     const owners = rp.be.infraOwners;
     const ownerId = /^(platform|integrations)\/[a-z][a-z0-9-]*$/;
     if (!isPlainObject(owners) || !Object.keys(owners).length || !Object.entries(owners).every(([key, list]) => key && Array.isArray(list) && list.every((o) => ownerId.test(String(o))) && new Set(list).size === list.length)) bad.push('ruleParams.be.infraOwners must map a non-empty specifier to a list of unique platform/<capability> or integrations/<provider> owners ([] means nowhere)');
@@ -158,6 +159,12 @@ function manifestShapeProblems(m) {
     if (!roleList(rp.be.suffixes)) bad.push('ruleParams.be.suffixes must be a non-empty list of unique kebab-case role suffixes');
     if (!roleList(rp.be.bannedSuffixes)) bad.push('ruleParams.be.bannedSuffixes must be a non-empty list of unique kebab-case suffixes');
     else if (roleList(rp.be.suffixes) && rp.be.suffixes.some((x) => rp.be.bannedSuffixes.includes(x))) bad.push('ruleParams.be.suffixes and bannedSuffixes must be disjoint');
+    const formNames = ['call', 'new', 'curried', 'object', 'primitive', 'array'];
+    const formsOk = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => formNames.includes(x)) && new Set(v).size === v.length;
+    const doubleOk = (v) => isPlainObject(v) && /^[A-Za-z][A-Za-z0-9]*$/.test(String(v.double)) && formsOk(v.forms);
+    const regexOk = (v) => { try { return typeof v === 'string' && v.length > 0 && Boolean(new RegExp(v)); } catch { return false; } };
+    const sd = rp.be.specDoubles;
+    if (!isPlainObject(sd) || Object.keys(sd).sort().join() !== 'doubles,fallback,kit' || typeof sd.kit !== 'string' || !sd.kit || !Array.isArray(sd.doubles) || !sd.doubles.length || !sd.doubles.every((e) => doubleOk(e) && regexOk(e.token) && Object.keys(e).length === 3) || !doubleOk(sd.fallback) || Object.keys(sd.fallback).length !== 2) bad.push('ruleParams.be.specDoubles must be {kit, doubles: [{token: regex, double, forms}], fallback: {double, forms}} with forms drawn from call, new, curried, object, primitive, array');
     if (!fileLinesOk(rp.fe.fileLines) || !blockOk(rp.fe.duplicateBlock) || Object.keys(rp.fe).length !== 2) bad.push('ruleParams.fe needs fileLines {soft, hardGrowth} and duplicateBlock {lines >= 2, tokens >= 1}');
   }
   if (!Array.isArray(m.slots) || !m.slots.length) { bad.push('slots must be a non-empty list'); return bad; }
@@ -621,12 +628,12 @@ function ruleCatalogProblems(d) {
     const at = `rules[${index}]`;
     if (!isPlainObject(r)) { bad.push(`${at} is not a map`); return; }
     const label = typeof r.id === 'string' ? r.id : at;
-    for (const key of Object.keys(r)) if (!['id', 'code', 'title_vi', 'law', 'kinds', 'gates', 'failureCodes', 'enforcers'].includes(key)) bad.push(`${label} has unknown key ${key}`);
-    const expectedId = `R${String(index + 1).padStart(2, '0')}`;
-    if (!/^R\d{2}$/.test(String(r.id))) bad.push(`${at}.id must be R<two digits>`);
-    else if (r.id !== expectedId) bad.push(`${label} is out of order: ${at} must be ${expectedId}`);
+    for (const key of Object.keys(r)) if (!['id', 'code', 'law', 'kinds', 'gates', 'failureCodes', 'enforcers'].includes(key)) bad.push(`${label} has unknown key ${key}`);
+    // A retired rule leaves its id unused for good (never reused), so ids only have to increase.
+    if (!/^R\d{2,3}$/.test(String(r.id))) bad.push(`${at}.id must be R<two or three digits>`);
+    else if (index > 0 && typeof d.rules[index - 1]?.id === 'string' && Number(r.id.slice(1)) <= Number(d.rules[index - 1].id.slice(1))) bad.push(`${label} is out of order: ids must increase, and ${d.rules[index - 1].id} comes before it`);
     if (!FINDING_CODE.test(String(r.code))) bad.push(`${label}.code must be an UPPER_SNAKE finding code`);
-    for (const key of ['title_vi', 'law']) if (typeof r[key] !== 'string' || !r[key].trim()) bad.push(`${label}.${key} is missing`);
+    if (typeof r.law !== 'string' || !r.law.trim()) bad.push(`${label}.law is missing`);
     if (typeof r.law === 'string' && r.law.includes('\n')) bad.push(`${label}.law must be one line`);
     const enumList = (key, allowed) => {
       if (!Array.isArray(r[key]) || !r[key].length) { bad.push(`${label}.${key} must be a non-empty list`); return []; }

package/runtime/scripts/lib/json.mjs

@@ -0,0 +1,22 @@
+// json.mjs — the ledger's forgiving JSON read. Every one of these rows may hold text a peer wrote or a
+// truncated payload, so a malformed column is the caller's fallback, never a throw. The parse of the
+// literal 'null' is kept as null (callers that want {} instead write `parseJsonOr`).
+import fs from 'node:fs';
+
+/** `text` as JSON, or `fallback` when it does not parse. */
+export const parseJson = (text, fallback = null) => {
+  try { return JSON.parse(text); } catch { return fallback; }
+};
+
+/** `text` as JSON, or `fallback` when it does not parse OR parses to null/undefined. Rows written
+ * as the literal 'null' read back as the fallback too, so a caller that wants an object gets one. */
+export const parseJsonOr = (text, fallback = {}) => parseJson(text) ?? fallback;
+
+/** A jobs/events row spread with `payload`: the row's payload_json parsed via parseJsonOr
+ * (`fallback` defaults to {}). Pass fallback null to keep a raw parseJson result, nulls included. */
+export const withPayload = (row, fallback = {}) => (row ? { ...row, payload: parseJsonOr(row.payload_json, fallback) } : row);
+
+/** `file` read and parsed as JSON, or `fallback` when the file is missing, unreadable or malformed. */
+export const readJsonFile = (file, fallback = null) => {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return fallback; }
+};