@starci/hfs 1.0.1 → 2.0.0

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

@@ -4,48 +4,104 @@
 // writes to the repository it inspects.
 //
 // checkRepo() answers, for the tracked paths of one repository (git ls-files):
-//   HFS_PATH_NO_SLOT              a tracked path no slot owns (the nearest slot is named)
+//   HFS_SLOT_UNDECLARED              a tracked path no slot owns (the nearest slot is named)
 //   HFS_SLOT_NOT_ENABLED          a tracked path in an opt-in slot the repository did not declare
 //   HFS_SLOT_AMBIGUOUS            two slots of equal specificity own the path (a manifest gap, reported not guessed)
 //   HFS_TRACKED_MUST_BE_IGNORED   a tracked path in an `ignored` slot (build output, generated files)
-//   HFS_FORBIDDEN_PRESENT         a tracked path in a forbidden / `external` slot
-//   HFS_REQUIRED_MISSING          a file or directory a required slot (or an instance of one) must contain
+//   HFS_FORBIDDEN_PRESENT         a tracked path in a forbidden / `external` slot; in the slot be.tool-config-local (.eslintrc*,
+//                                 .eslintignore, a second eslint.config.*, another prettier or jest config) the code is HFS_TOOL_CONFIG_LOCAL instead
+//   HFS_MANAGED_FILE_DRIFT, HFS_TOOL_CONFIG_LOCAL (content), HFS_TS_STRICT
+//                                 the managed files: produced by packages/hfs/sync/managed.mjs, which renders the templates,
+//                                 and passed in as `extraFindings` (this module does not read the templates)
+//   HFS_SLOT_REQUIRED_MISSING     a file or directory a required slot (or an instance of one) must contain
 //   HFS_MIN_INSTANCES             fewer instances of a slot than minInstances
+//   HFS_PLAINTEXT_SECRET          (R06, hfs-rules/secrets.mjs) a plaintext secret file or value in a tracked file; a `.enc` that is no sops envelope
+//   HFS_STACKS_SHAPE              (R10, hfs-rules/stacks.mjs) a `.starcistacks` path outside the standard shape, or a Sonar owner that is not the host
+//   HFS_CI_MISSING_CANON          (R13, hfs-rules/pipeline.mjs) CI without the pinned `hfs check`, pre-push without typecheck or lint
+//   HFS_DEP_VERSION_SKEW          (R14, hfs-rules/deps.mjs) a dependency at two versions in the workspace, or a nested copy in the lockfile
+//   HFS_CONTRACT_SNAPSHOT_DRIFT   (R23, hfs-rules/contract.mjs) an uncommitted back-end snapshot, or a front-end copy that differs from it
+//   BE_TEST_TOPOLOGY              (R47, hfs-rules/test-topology.mjs) a `.test` file, a testing/ folder, a second jest configuration
+//   FE_NO_TESTS                   (R97, hfs-rules/fe-no-tests.mjs) a front end holds a spec, e2e or test-tool file, a test script or a test dependency; no exception
+//   BE_SPEC_PLACEMENT             (R102, hfs-rules/spec-placement.mjs) a spec or test file outside the four test layers, scripts/ and tools/ included
+//   HFS_REPO_LOCAL_CHECK          (R103, hfs-rules/repo-local-checks.mjs) a local eslint rule or plugin, a `check-*` script, a relative import in eslint.config
+//   HFS_LINT_SUPPRESSION_FILE     (R104, hfs-rules/lint-suppression.mjs) an eslint suppressions file, script or option
+//   HFS_PROOF_COMMAND_FILE_MISSING (R105, hfs-rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
+//   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, hfs-rules/frontend.mjs) the front-end tree of each app
+//   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG   (R04, R11) produced by packages/hfs/sync/managed.mjs, which renders the templates
+//   HFS_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
+//                                 both are passed in as `extraFindings`: this module reads no template and starts no tool
 //   HFS_CANON_PIN_DRIFT           a dependency whose declared version is not the pinned one
+//   BE_SOURCE_FORM                (be) a tracked src/apps .ts file whose name is not index.ts, main.ts, a migration or <kebab>.<suffix>.ts with a suffix of ruleParams.be.suffixes
 //   HFS_SIZE_SOFT_BACKLOG         (info, report-only, never fails) a source file above ruleParams fileLines.soft
-// Every finding carries its code and the Vietnamese why text of modules/kernel/failure-codes.yaml. Only `error`
+//   HFS_EMPTY_DIR                 a directory with no file below it (git never tracks one), outside .git, node_modules and ignored slots
+//   HFS_GHOST_TREE                an empty directory beside a sibling within two edits of its name (business / bussiness)
+//   HFS_UNTRACKED_ROOT_ENTRY      an entry git neither tracks nor ignores, outside an `ignored` slot (R03)
+// checkRepository() is the whole `hfs check`: checkRepo() plus the architecture machine (scripts/checks/architecture.mjs, one
+// implementation; the published bundle carries a byte copy), its violations and errors reported as findings under their own
+// codes; `fast` limits both to the owners changed since the merge-base. Every finding carries its code and the Vietnamese why text of modules/kernel/failure-codes.yaml. Only `error`
 // findings fail the check.
 import fs from 'node:fs';
 import path from 'node:path';
-import { execFileSync } from 'node:child_process';
 import { skillRoot } from '../../engine/runtime-root.mjs';
+import { ARCHITECTURE_RULE_IDS, checkArchitecture } from '../checks/architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { HFS_DECLARATION_FILE, HfsSlotsError, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
+import { allowsFile } from './hfs-allows.mjs';
+import { isDir } from './fs-kind.mjs';
+import { gitOutput } from './git.mjs';
 import { posixPath } from './path-key.mjs';
+import { readTree, treeFacts, untrackedEntries } from './hfs-tree.mjs';
+import { contractFindings } from './hfs-rules/contract.mjs';
+import { depFindings } from './hfs-rules/deps.mjs';
+import { frontendFindings } from './hfs-rules/frontend.mjs';
+import { lintSuppressionFindings } from './hfs-rules/lint-suppression.mjs';
+import { pipelineFindings } from './hfs-rules/pipeline.mjs';
+import { proofCommandFindings } from './hfs-rules/proof-commands.mjs';
+import { repoLocalCheckFindings } from './hfs-rules/repo-local-checks.mjs';
+import { readJson } from './hfs-rules/read.mjs';
+import { secretFindings, slotOwnsSecrets } from './hfs-rules/secrets.mjs';
+import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+import { stacksFindings } from './hfs-rules/stacks.mjs';
+import { testTopologyFindings } from './hfs-rules/test-topology.mjs';
+import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
 
 export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
+/**
+ * The codes `hfs check` and `hfs init` report when they cannot judge (an unreadable repository, a refused declaration or
+ * manifest, an init that cannot proceed): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
+ */
+export const REFUSAL_CODES = Object.freeze([
+  'HFS_INIT_EXISTS', 'HFS_INIT_UNDETECTED', 'HFS_REPO_UNREADABLE',
+  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING',
+]);
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
 export const CHECK_CODES = Object.freeze([
-  'HFS_PATH_NO_SLOT', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
-  'HFS_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG',
-  'HFS_INIT_EXISTS', 'HFS_INIT_UNDETECTED', 'HFS_REPO_UNREADABLE',
-  'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID',
+  'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
+  'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
+  'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
+  'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT',
+  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
+  'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
+  'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
+  ...REFUSAL_CODES,
 ]);
+/** Every code `hfs check` can report: its own and every code the architecture machine can emit (derived from the machine's rule id lists). */
+export const ALL_CHECK_CODES = Object.freeze([...new Set([...CHECK_CODES, ...ARCHITECTURE_RULE_IDS])].sort());
 const SOURCE_EXT = /\.(?:[cm]?[jt]sx?)$/;
 const VAR = /<([a-z][a-z0-9-]*)>/g;
 const DEP_SECTIONS = ['dependencies', 'devDependencies'];
 
 const refuse = (code, message, details = {}) => { throw new HfsSlotsError(code, message, details); };
 
-/** {code: {title_vi, meaning_vi, nextStep_vi}} for the codes asked for, read from the failure-code catalog under `root`. */
+/** {code: {title, title_vi, meaning_vi, nextStep_vi}} for the codes asked for, read from the failure-code catalog under `root`. */
 export function readWhy(root = skillRoot, codes = CHECK_CODES) {
   const catalog = parseYaml(fs.readFileSync(path.join(root, FAILURE_CODES_FILE), 'utf8'));
   const why = {};
   for (const code of codes) {
     const entry = catalog?.[code];
     if (!entry) refuse('HFS_MANIFEST_INVALID', `${FAILURE_CODES_FILE} has no entry for ${code}`, { code });
-    why[code] = { titleVi: entry.title_vi, whyVi: entry.meaning_vi, nextStepVi: entry.nextStep_vi };
+    why[code] = { title: entry.title, titleVi: entry.title_vi, whyVi: entry.meaning_vi, nextStepVi: entry.nextStep_vi };
   }
   return why;
 }
@@ -54,7 +110,7 @@ export function readWhy(root = skillRoot, codes = CHECK_CODES) {
 export function trackedFiles(repoRoot) {
   let out;
   try {
-    out = execFileSync('git', ['-C', repoRoot, 'ls-files', '-z', '--cached', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+    out = gitOutput(['ls-files', '-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 });
   } catch (error) {
     refuse('HFS_REPO_UNREADABLE', `${repoRoot} is not a readable Git work tree (${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]})`, { repoRoot });
   }
@@ -71,10 +127,12 @@ export function openRepo({ repoRoot, root = skillRoot, manifest = loadSlotManife
 
 const pinnedSpec = (spec, pin) => (spec === pin.version ? null : `declared ${spec}, pinned ${pin.version}`);
 
-function pinFindings({ repoRoot, files, profile, root }) {
-  const pins = parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
+/** The pin map of knowledge/hfs/canon-pins.yaml under `root`. */
+const readPins = (root) => parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
+
+function pinFindings({ repoRoot, files, profile, pins, only }) {
   const findings = [];
-  for (const file of files.filter((f) => f === 'package.json' || f.endsWith('/package.json'))) {
+  for (const file of files.filter((f) => (f === 'package.json' || f.endsWith('/package.json')) && (!only || only.has(f)))) {
     let pkg;
     try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8')); } catch { continue; }
     for (const [name, pin] of Object.entries(pins)) {
@@ -90,6 +148,53 @@ function pinFindings({ repoRoot, files, profile, root }) {
   return findings;
 }
 
+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 api.composition.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;
+}
+
 /** Instances (slot, root, bindings) present in the tracked tree, for every slot that names required files or a minimum. */
 function instancesOf(resolver, files) {
   const found = new Map();
@@ -117,7 +222,7 @@ const requiredOf = (slot, instance) => (slot.requires ?? []).map((entry) => {
 const appOf = (p) => /^apps\/([^/]+)\//.exec(p)?.[1];
 
 function withWhy(findings, why) {
-  return findings.map((f) => ({ ...f, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
+  return findings.map((f) => ({ ...f, title: why[f.code].title, titleVi: why[f.code].titleVi, whyVi: why[f.code].whyVi, nextStepVi: why[f.code].nextStepVi }));
 }
 
 function summarize(findings) {
@@ -133,12 +238,36 @@ function summarize(findings) {
   };
 }
 
+/** The tree findings of R03: empty directories, ghost siblings, untracked entries outside an ignored slot. */
+function treeFindings({ repoRoot, resolver }) {
+  const inIgnoredSlot = (rel) => resolver.classifyPath(`${rel}/.probe`).tracking === 'ignored';
+  const findings = [];
+  const facts = treeFacts(readTree(repoRoot, { isIgnored: inIgnoredSlot }));
+  for (const { path: dir, below } of facts.empty) {
+    findings.push({ code: 'HFS_EMPTY_DIR', level: 'error', path: dir, below, message: `${dir} has no file below it${below ? ` (nor in its ${below} sub-director${below === 1 ? 'y' : 'ies'})` : ''}; git tracks no empty directory, so it is a leftover` });
+  }
+  for (const { path: dir, of, distance } of facts.ghosts) {
+    findings.push({ code: 'HFS_GHOST_TREE', level: 'error', path: dir, of, distance, message: `${dir} is empty and ${distance} edit${distance === 1 ? '' : 's'} from its sibling ${of}: a renamed or misspelt structure that was never removed` });
+  }
+  for (const entry of untrackedEntries(repoRoot)) {
+    const bare = entry.replace(/\/$/, '');
+    const ignored = entry.endsWith('/') ? inIgnoredSlot(bare) : resolver.classifyPath(bare).tracking === 'ignored';
+    if (!ignored) findings.push({ code: 'HFS_UNTRACKED_ROOT_ENTRY', level: 'error', path: bare, message: `${entry} is neither tracked nor git-ignored, and no ignored slot owns it` });
+  }
+  return findings;
+}
+
 /**
  * The check of one repository. `declaration` overrides hfs.json (a dry run over a repository that has none); `files`
- * overrides git ls-files (specs). Returns {ok, profile, apps, manifest, tracked, findings, counts}; a missing or invalid
- * hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never an exception.
+ * overrides git ls-files (specs). `only` (a list of paths) limits the per-path checks (slot, pin, size) to those paths; the
+ * checks of the tree as a whole (required files, minimum instances, empty directories, untracked entries) are not
+ * per-path. `tree: false` skips the file-system checks (empty directories, ghosts, untracked); they also do not run
+ * over `files`, which is a dry run. `extraFindings` are findings another emitter produced for the same repository (the
+ * managed files), judged and counted with this module's own. Returns {ok, profile, apps, manifest, tracked, findings,
+ * counts}; a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never
+ * an exception.
  */
-export function checkRepo({ repoRoot, root = skillRoot, declaration, files, manifest = loadSlotManifest({ root }) }) {
+export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }) }) {
   const why = readWhy(root);
   let repo;
   try {
@@ -153,17 +282,24 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, mani
   const trackedSet = new Set(tracked);
   const present = (p) => (p.endsWith('/') ? tracked.some((f) => f.startsWith(p)) : trackedSet.has(p));
   const findings = [];
+  const scoped = only ? new Set(only) : null;
+  const inScope = (file) => !scoped || scoped.has(file);
 
   for (const file of tracked) {
+    if (!inScope(file)) continue;
+    if (repo.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_PATH_NO_SLOT', 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'}` : ''}` });
+      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') {
-      findings.push({ code: 'HFS_FORBIDDEN_PRESENT', 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}` : ''}` });
+      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` });
     }
@@ -176,7 +312,7 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, mani
     if (missing.has(key) || present(p)) return;
     missing.add(key);
     const app = appOf(p);
-    findings.push({ code: 'HFS_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${app ? ` (app ${app})` : ''}, which is not tracked` });
+    findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${app ? ` (app ${app})` : ''}, which is not tracked` });
   };
   for (const entry of required.paths) missingFile(entry.slot, entry.path, entry.via);
   const instances = instancesOf(resolver, tracked);
@@ -187,26 +323,117 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, mani
     if (count < min) findings.push({ code: 'HFS_MIN_INSTANCES', level: 'error', path: resolver.slot(slot).path, slot, min, count, message: `${slot} needs at least ${min} instance${min === 1 ? '' : 's'} (${resolver.slot(slot).path}), found ${count}` });
   }
 
-  findings.push(...pinFindings({ repoRoot, files: tracked, profile: repo.profile, root }));
+  const pins = readPins(root);
+  findings.push(...pinFindings({ repoRoot, files: tracked, profile: repo.profile, pins, only: scoped }));
+
+  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-repository, cheap, no tool run.
+  const secrets = secretFindings({ repoRoot, files: tracked.filter(inScope), resolver });
+  const declared = declaration === undefined ? readJson(repoRoot, 'hfs.json') : declaration;
+  if (repo.profile === 'be') findings.push(...sourceFormFindings({ files: tracked.filter(inScope), resolver }));
+  findings.push(
+    ...secrets,
+    ...depFindings({ repoRoot, files: tracked }),
+    ...pipelineFindings({ repoRoot, files: tracked, pins }),
+    ...contractFindings({ repoRoot, files: tracked, repo, resolver, stacks: declared?.stacks }),
+    ...repoLocalCheckFindings({ repoRoot, files: tracked }),
+    ...lintSuppressionFindings({ repoRoot, files: tracked }),
+    ...(repo.profile === 'be' ? [...stacksFindings({ repoRoot, files: tracked, resolver }), ...testTopologyFindings({ repoRoot, files: tracked }), ...specPlacementFindings({ files: tracked, resolver }), ...proofCommandFindings({ repoRoot, files: tracked, resolver })] : [...frontendFindings({ repoRoot, files: tracked, repo }), ...feNoTestsFindings({ repoRoot, files: tracked.filter(inScope) })]),
+    ...extraFindings,
+  );
 
   const soft = resolver.ruleParams().fileLines.soft;
   for (const file of tracked) {
-    if (!SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
+    if (!inScope(file) || !SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
     let lines;
     try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
     if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
   }
 
+  if (tree) findings.push(...treeFindings({ repoRoot, resolver }));
+
   const finished = withWhy(findings, why);
   const counts = summarize(finished);
   return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps: repo.apps, tracked: tracked.length, findings: finished, counts };
 }
 
+// ------------------------------------------------------------------------------------------ the whole check
+
+const gitOut = (repoRoot, args) => gitOutput(args, { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 });
+
+/** The merge-base of HEAD with `base`, else with origin/main, else with main; null when none resolves. */
+function mergeBaseOf(repoRoot, base) {
+  for (const ref of base ? [base] : ['origin/main', 'main']) {
+    try {
+      const sha = gitOut(repoRoot, ['merge-base', 'HEAD', ref]).trim();
+      if (sha) return sha;
+    } catch { /* this ref has no merge-base with HEAD; try the next */ }
+  }
+  return null;
+}
+
+/** Tracked paths that differ from the merge-base (commits, staged and unstaged edits; deletions are not paths to judge). */
+export function changedSince(repoRoot, base) {
+  const sha = mergeBaseOf(repoRoot, base);
+  if (!sha) {
+    throw new Error(base
+      ? `--base ${base} has no merge-base with HEAD; pass a ref this branch descends from`
+      : '--fast needs a merge-base with origin/main or main and found none; run `git fetch origin main` or pass --base <ref>');
+  }
+  const files = gitOut(repoRoot, ['diff', '--name-only', '--diff-filter=ACMRT', '-z', sha]).split('\0').filter(Boolean).map(posixPath);
+  return { base: sha, files };
+}
+
+/** The machine's violations and errors as findings: each keeps the machine's rule id as its code. */
+function machineFindings(report) {
+  const of = (item) => ({ code: item.ruleId, level: 'error', ...(item.path ? { path: item.path } : {}), ...(item.line ? { line: item.line, column: item.column } : {}), source: 'machine', message: `${item.path ? `${item.path}${item.line ? `:${item.line}` : ''}: ` : ''}${item.message}` });
+  return [...report.errors.map(of), ...report.violations.map(of)];
+}
+
+/**
+ * The whole `hfs check` of one repository: checkRepo() (slots, pins, size, tree) and then the architecture machine over the
+ * same work tree, its violations and errors merged in as findings with the Vietnamese why of their codes. `fast` judges
+ * only what changed since the merge-base (`base` names another ref): the per-path slot and pin checks on the changed
+ * paths, the machine on the owners of the changed source files without clones and dead exports, and no file-system tree
+ * checks. `extraFindings` are the findings of the emitters that render templates or run the repository's formatter
+ * (packages/hfs/sync), judged with checkRepo's own. `machine` is injectable for specs. A missing merge-base under `fast` is an Error, never a silent full pass.
+ */
+export function checkRepository({ repoRoot, root = skillRoot, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture }) {
+  const changed = fast ? changedSince(repoRoot, base) : null;
+  const baseSha = changed ? changed.base : (base ? (mergeBaseOf(repoRoot, base) ?? refuse('HFS_REPO_UNREADABLE', `--base ${base} has no merge-base with HEAD`, { repoRoot, base })) : undefined);
+  const slotResult = checkRepo({ repoRoot, root, manifest, extraFindings, ...(changed ? { only: changed.files, tree: false } : {}) });
+  if (slotResult.profile === null) return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
+
+  let paths;
+  if (changed) {
+    const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, repoRoot));
+    paths = [...new Set(changed.files.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
+    if (!paths.length) return { ...slotResult, machine: { status: 'skipped', reason: 'no changed source file', base: changed.base }, fast: { base: changed.base, changed: changed.files.length } };
+  }
+  let report;
+  try {
+    report = machine({ repositoryRoot: repoRoot, base: baseSha, ...(changed ? { paths, fast: true } : {}) });
+  } catch (error) {
+    report = { ok: false, files: 0, kinds: [], violations: [], errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+  }
+  const found = machineFindings(report);
+  const why = readWhy(root, [...new Set(found.map((f) => f.code))]);
+  const findings = [...slotResult.findings, ...withWhy(found, why)];
+  const counts = summarize(findings);
+  return {
+    ...slotResult,
+    ok: counts.error === 0,
+    findings,
+    counts,
+    machine: { status: 'ran', files: report.files, kinds: report.kinds, ...(changed ? { paths, base: changed.base } : {}) },
+    ...(changed ? { fast: { base: changed.base, changed: changed.files.length } } : {}),
+  };
+}
+
 // --------------------------------------------------------------------------------------------------- explain
 
 const TEST_KIND = {
-  'unit-beside': 'a unit spec beside each source file (<name>.spec.ts / .spec.tsx) in this slot',
-  e2e: 'an e2e spec (*.e2e-spec.ts or a Playwright spec) covering the flow; no unit spec is required',
+  'unit-beside': 'a <name>.service.spec.ts beside each <name>.service.ts in this slot (only services are unit-tested)',
+  e2e: 'an integration, e2e or contract spec covering the flow; no unit spec is required',
   none: 'no test is required for files in this slot',
 };
 
@@ -217,7 +444,7 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
   const why = readWhy(root);
   const c = resolver.classifyPath(input);
   if (c.status === 'no-slot') {
-    return { path: c.path, status: 'no-slot', code: 'HFS_PATH_NO_SLOT', nearest: c.nearest, titleVi: why.HFS_PATH_NO_SLOT.titleVi, whyVi: why.HFS_PATH_NO_SLOT.whyVi };
+    return { path: c.path, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: c.nearest, titleVi: why.HFS_SLOT_UNDECLARED.titleVi, whyVi: why.HFS_SLOT_UNDECLARED.whyVi };
   }
   if (c.status === 'ambiguous') return { path: c.path, status: 'ambiguous', code: 'HFS_SLOT_AMBIGUOUS', candidates: c.candidates, titleVi: why.HFS_SLOT_AMBIGUOUS.titleVi, whyVi: why.HFS_SLOT_AMBIGUOUS.whyVi };
   const slot = resolver.slot(c.slot);
@@ -248,7 +475,6 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
 // ------------------------------------------------------------------------------------------------- init
 
 const SLUG_SUFFIX = /-(backend|be|frontend|fe|api|web|app)$/;
-const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
 const exists = (p) => fs.existsSync(p);
 const readPackage = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return null; } };
 const depsOf = (pkg) => ({ ...pkg?.devDependencies, ...pkg?.dependencies });

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

@@ -0,0 +1,126 @@
+// contract.mjs - HFS_CONTRACT_SNAPSHOT_DRIFT (R23): the contract is committed and the front-end copy equals the back end's.
+//   back end   a repository with a GraphQL transport commits `contracts/<app>/schema.graphql` for each api app, and an api app with
+//              an operation table commits `contracts/<app>/openapi.json`
+//   front end  every `apps/<app>/src/modules/api/contract/<be-app>.{graphql,json}` is hash-equal to the sibling back end's
+//              `contracts/<be-app>/schema.graphql` (openapi.json for .json); hfs.json `stacks` names the sibling
+//              repository, and a sibling that is not checked out is reported (info), not compared
+// The snapshots are generated by `npm run contract:emit` (`hfs emit-contracts`, packages/hfs/emit/contracts.mjs): printSchema of the
+// resolvers the app root composes, and the OpenAPI 3.1 document of the typed operation table `apps/<app>/src/operations.ts`.
+// That the committed snapshot equals what the app emits now is contractEmitFindings (full pass only, never --fast): it emits every
+// api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { found } from './read.mjs';
+import { safeRemoveTree } from '../safe-remove.mjs';
+
+export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
+export const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
+const COPY = /^apps\/([^/]+)\/src\/modules\/api\/contract\/([^/]+)\.(graphql|json)$/;
+const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
+
+/** sha256 of a file's text with line endings folded, or null when it cannot be read. */
+export function contractHash(file) {
+  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex'); } catch { return null; }
+}
+
+/** The findings of R23 for the repository at `repoRoot`. `stacks` is hfs.json's sibling back-end path (front end only). */
+export function contractFindings({ repoRoot, files, repo, resolver, stacks }) {
+  const findings = [];
+  if (repo.profile === 'be') {
+    const serves = files.some((file) => resolver.classifyPath(file).slot === GRAPHQL_TRANSPORT_SLOT);
+    const tracked = new Set(files);
+    for (const app of repo.apps.filter((a) => a.kind === 'api')) {
+      const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
+      if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
+      if (!serves) continue;
+      const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+      if (!tracked.has(snapshot)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
+    }
+    return findings;
+  }
+  for (const file of files) {
+    const match = COPY.exec(file);
+    if (!match) continue;
+    const [, app, beApp, ext] = match;
+    if (!stacks) {
+      findings.push(found(CONTRACT_SNAPSHOT_DRIFT, file, `${file} is a contract copy but hfs.json names no sibling back end (stacks), so it cannot be compared with the back end's snapshot`, { app }));
+      continue;
+    }
+    const sibling = path.resolve(repoRoot, stacks);
+    if (!fs.existsSync(sibling)) {
+      findings.push(found(CONTRACT_SNAPSHOT_DRIFT, file, `${file} was not compared: the sibling back end ${stacks} is not checked out here`, { app, level: 'info' }));
+      continue;
+    }
+    const snapshot = `contracts/${beApp}/${SNAPSHOT_OF[ext]}`;
+    const theirs = contractHash(path.join(sibling, snapshot));
+    if (theirs === null) {
+      findings.push(found(CONTRACT_SNAPSHOT_DRIFT, file, `${stacks}/${snapshot} does not exist, so ${file} copies nothing; the back end commits its contract first`, { app, snapshot }));
+      continue;
+    }
+    const ours = contractHash(path.join(repoRoot, file));
+    if (ours !== theirs) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, file, `${file} (${String(ours).slice(0, 12)}) differs from ${stacks}/${snapshot} (${theirs.slice(0, 12)}); run \`npm run contract:pull\``, { app, snapshot }));
+  }
+  return findings;
+}
+
+/** The first lines of an error, enough to act on. */
+const errorText = (error) => String(error?.message ?? error).split(/\r?\n/).filter(Boolean).slice(0, 4).join(' | ');
+
+/**
+ * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
+ * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
+ * it is injected because the runtime scripts do not import the hfs package. Every api app is emitted on its own into a temp
+ * directory, so one app that cannot emit does not hide the others; an uncommitted snapshot is contractFindings' finding. Answers
+ * `{ findings, apps }`, `apps` being what was judged: `[{ app, artifact, status }]`, `artifact` being `schema.graphql` or
+ * `openapi.json` and `status` one of `fresh`, `stale`, `not-committed`, `none` (nothing emitted, nothing committed; GraphQL only),
+ * `left-behind` (committed, nothing emitted) or `emit-failed`.
+ */
+export function contractEmitFindings({ repoRoot, files, repo, emit }) {
+  const findings = [];
+  const apps = [];
+  if (repo.profile !== 'be') return { findings, apps };
+  const tracked = new Set(files);
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'hfs-contracts-'));
+  try {
+    for (const app of repo.apps.filter((a) => a.kind === 'api')) {
+      const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
+      let emitted;
+      try {
+        emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
+      } catch (error) {
+        for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
+        const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`hfs emit-contracts\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+        continue;
+      }
+      for (const { artifact, what } of artifacts) {
+        const snapshot = `contracts/${app.name}/${artifact}`;
+        const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
+        if (!emitted.written.includes(snapshot)) {
+          if (committed === null) {
+            if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
+            continue;
+          }
+          apps.push({ app: app.name, artifact, status: 'left-behind' });
+          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
+          continue;
+        }
+        const fresh = contractHash(path.join(scratch, snapshot));
+        if (committed === null) {
+          // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
+          apps.push({ app: app.name, artifact, status: 'not-committed' });
+        } else if (committed === fresh) {
+          apps.push({ app: app.name, artifact, status: 'fresh' });
+        } else {
+          apps.push({ app: app.name, artifact, status: 'stale' });
+          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
+        }
+      }
+    }
+  } finally {
+    safeRemoveTree(scratch);
+  }
+  return { findings, apps };
+}

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

@@ -0,0 +1,63 @@
+// deps.mjs - HFS_DEP_VERSION_SKEW (R14): one version per dependency in the workspace.
+//   - the root and every workspace package.json declare a dependency at one spec (a `file:`, `link:` or `workspace:` spec is
+//     a workspace link, not a version);
+//   - a dependency the root `overrides` pins to a version (a string that is not a `$name` reference) is declared at that version everywhere
+//     it is declared: an override the manifests disagree with is a second version in disguise;
+//   - the lockfile (package-lock.json, read, never installed) holds no nested copy of a dependency the workspace declares:
+//     `node_modules/<a>/node_modules/<name>` or `apps/<app>/node_modules/<name>` next to the hoisted `node_modules/<name>`.
+import { found, readJson } from './read.mjs';
+
+export const DEP_VERSION_SKEW = 'HFS_DEP_VERSION_SKEW';
+const SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies'];
+const LINK = /^(?:file|link|workspace|portal):/;
+const NESTED = /(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)$/;
+const HOISTED = /^node_modules\/((?:@[^/]+\/)?[^/]+)$/;
+
+/** Every package.json a repository tracks: the root and each workspace's. */
+const manifestsOf = (files) => files.filter((file) => file === 'package.json' || (file.endsWith('/package.json') && !file.includes('node_modules/')));
+
+/** The findings of R14 over the tracked paths `files` of `repoRoot`. */
+export function depFindings({ repoRoot, files }) {
+  const findings = [];
+  const specs = new Map();
+  for (const file of manifestsOf(files)) {
+    const pkg = readJson(repoRoot, file);
+    if (!pkg) continue;
+    for (const section of SECTIONS) {
+      for (const [name, spec] of Object.entries(pkg[section] ?? {})) {
+        if (typeof spec !== 'string' || LINK.test(spec)) continue;
+        if (!specs.has(name)) specs.set(name, new Map());
+        const at = specs.get(name);
+        if (!at.has(spec)) at.set(spec, []);
+        at.get(spec).push(file);
+      }
+    }
+  }
+  for (const [name, bySpec] of specs) {
+    if (bySpec.size < 2) continue;
+    const list = [...bySpec].map(([spec, where]) => `${spec} (${where.join(', ')})`);
+    findings.push(found(DEP_VERSION_SKEW, [...bySpec.values()][0][0], `${name} is declared at ${bySpec.size} versions in the workspace: ${list.join('; ')}; keep one`, { dependency: name, versions: [...bySpec.keys()] }));
+  }
+  const overrides = readJson(repoRoot, 'package.json')?.overrides;
+  for (const [name, pin] of Object.entries(overrides && typeof overrides === 'object' ? overrides : {})) {
+    if (typeof pin !== 'string' || pin.startsWith('$') || !specs.has(name)) continue;
+    const off = [...specs.get(name)].filter(([spec]) => spec !== pin);
+    if (off.length) findings.push(found(DEP_VERSION_SKEW, off[0][1][0], `${name} is pinned to ${pin} by the root overrides but declared at ${off.map(([spec, where]) => `${spec} (${where.join(', ')})`).join('; ')}; declare the pinned version`, { dependency: name, versions: off.map(([spec]) => spec), pinned: pin }));
+  }
+  const lock = files.includes('package-lock.json') ? readJson(repoRoot, 'package-lock.json') : null;
+  if (lock?.packages) {
+    const declared = new Set(specs.keys());
+    const hoisted = new Map();
+    for (const [key, entry] of Object.entries(lock.packages)) {
+      const top = HOISTED.exec(key);
+      if (top && !entry.link) hoisted.set(top[1], entry.version);
+    }
+    for (const [key, entry] of Object.entries(lock.packages)) {
+      const nested = NESTED.exec(key);
+      if (!nested || entry.link || HOISTED.test(key) || !declared.has(nested[1])) continue;
+      const name = nested[1];
+      findings.push(found(DEP_VERSION_SKEW, 'package-lock.json', `${key} is a nested copy of ${name}${entry.version ? ` ${entry.version}` : ''}${hoisted.has(name) ? ` next to the hoisted ${hoisted.get(name)}` : ''}; the workspace keeps one copy (align the ranges or add a root override)`, { dependency: name, lockPath: key, version: entry.version }));
+    }
+  }
+  return findings;
+}