@starci/hfs 4.0.9 → 4.1.0

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

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { machineKit } from './machine-ast.mjs';
 import { constructorDependencies } from './constructor-deps.mjs';
 import { treeOf } from './required-files.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 
 /**
  * R48 `unit-spec-providers` (BE_SPEC_QUALITY), the unit test standard's rule 3: the unit spec of a service builds its
@@ -22,7 +23,6 @@ import { treeOf } from './required-files.mjs';
 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. */
@@ -49,6 +49,87 @@ function testingModules(ts, sourceFile) {
 
 const literalKey = (ts, property) => (ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) && (ts.isIdentifier(property.name) || ts.isStringLiteralLike(property.name)) ? property.name.text : null;
 
+function providerList(ts, call, rel, report) {
+  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.`);
+  return list;
+}
+
+function readProviders(ts, list, rel, nameOf, report) {
+  const provided = [];
+  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).`);
+  }
+  return { provided, readable };
+}
+
+function serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report) {
+  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')}.`);
+  return serviceClass ? { serviceClass, serviceName } : null;
+}
+
+function checkDependencies(kit, rel, service, serviceFile, list, provided, report) {
+  const { serviceName, serviceClass } = service;
+  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.`);
+}
+
+function checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report }) {
+  const list = providerList(ts, call, rel, report);
+  if (!list) return;
+  const nameOf = identifier => imports.get(identifier.text)?.name ?? identifier.text;
+  const { provided, readable } = readProviders(ts, list, rel, nameOf, report);
+  if (!readable) return;
+  const service = serviceClassFor(ts, rel, serviceRel, serviceFile, imports, list, report);
+  if (!service) return;
+  checkDependencies(kit, rel, service, serviceFile, list, provided, report);
+}
+
+function checkServiceSpec({ config, graph, kit, ts, rel, violations }) {
+  const abs = path.join(config.root, ...rel.split('/'));
+  if (!fs.existsSync(abs)) return false;
+  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 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.`); return true; }
+  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.`); return true; }
+  for (const call of modules) checkTestingModule({ ts, kit, rel, serviceRel, serviceFile, imports, call, report });
+  return true;
+}
+
 export function checkUnitSpecProviders(input) {
   const { config, graph } = input;
   const kit = machineKit(input);
@@ -56,67 +137,8 @@ export function checkUnitSpecProviders(input) {
   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.`);
-    }
+  for (const rel of [...tree.files].filter(file => SPEC_ROOT.test(file) && file.endsWith('.service.spec.ts')).sort(byCodeUnit)) {
+    if (checkServiceSpec({ config, graph, kit, ts, rel, violations })) specs += 1;
   }
   return { violations, coverage: { status: 'checked', specs, files: graph.files.size } };
 }

package/runtime/scripts/hfs/architecture.mjs

@@ -5,7 +5,6 @@
 // Prints one starci/architecture-check@1 record. Exit 0: ok. Exit 1: violations or errors (a check that
 // cannot run is an error, never a pass). Exit 2: bad arguments.
 import path from 'node:path';
-import {fileURLToPath} from 'node:url';
 import {checkArchitecture} from './architecture/index.mjs';
 import { isMain } from '../lib/is-main.mjs';
 
@@ -19,11 +18,11 @@ function parseArchitectureArgs(argv) {
     const value = argv[index];
     if (value === '--base') {
       base = argv[++index];
-      if (!base) throw Error(`--base needs a commit; ${USAGE}`);
-    } else if (value.startsWith('-') || root !== null) throw Error(`unexpected argument ${value}; ${USAGE}`);
+      if (!base) throw new Error(`--base needs a commit; ${USAGE}`);
+    } else if (value.startsWith('-') || root !== null) throw new Error(`unexpected argument ${value}; ${USAGE}`);
     else root = value;
   }
-  if (root === null) throw Error(USAGE);
+  if (root === null) throw new Error(USAGE);
   return {root, base};
 }
 

package/runtime/scripts/hfs/check.mjs

@@ -58,7 +58,6 @@ import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadRuleCatalog, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
-import { allowsFile } from './allows.mjs';
 import { RUNTIME_KIND } from './manifest-shape.mjs';
 import { lsFiles } from '../api/git/ls-files.mjs';
 import { diff as gitDiff } from '../api/git/diff.mjs';
@@ -71,14 +70,15 @@ import { appRootFindings } from './rules/app-root.mjs';
 import { frontendFindings } from './rules/frontend-tree.mjs';
 import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
 import { repoLocalCheckFindings } from './rules/repo-local-checks.mjs';
-import { readJson } from './rules/read.mjs';
 import { supabaseSecretFindings } from './rules/supabase-secrets.mjs';
 import { pathFindings } from './path-findings.mjs';
 import { onLintSurface } from './architecture/surface.mjs';
 import { checkAppRoot, trackedTreeView } from './architecture/hfs.mjs';
 import { testTopologyFindings } from './rules/test-topology.mjs';
-import { feNoTestsFindings, isFeTestPath } from './rules/fe-no-tests.mjs';
+import { feNoTestsFindings } from './rules/fe-no-tests.mjs';
 import { editionFindings } from './rules/edition.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+import { pinFindings } from './pin-findings.mjs';
 // The database rules (R213-R216) read SQL through a WASM parser, so they are async: `starci app check` calls them beside the other emitters and passes the findings in as `extraFindings`.
 export { checkDatabase } from './rules/database.mjs';
 
@@ -106,10 +106,9 @@ export const CHECK_CODES = Object.freeze([
   ...REFUSAL_CODES,
 ]);
 /** Every code `starci app 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());
+export const ALL_CHECK_CODES = Object.freeze([...new Set([...CHECK_CODES, ...ARCHITECTURE_RULE_IDS])].sort(byCodeUnit));
 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); };
 
@@ -138,30 +137,9 @@ export function trackedFiles(repoRoot) {
 
 const fill = (text, bindings) => String(text).replace(VAR, (whole, name) => bindings[name] ?? whole);
 
-const pinnedSpec = (spec, pin) => (spec === pin.version ? null : `declared ${spec}, pinned ${pin.version}`);
-
 /** 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')) && (!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)) {
-      // The app root's one package.json carries the pins of both sides.
-      if (profile !== APP_SCOPE && pin.side !== 'both' && pin.side !== profile) continue;
-      for (const section of DEP_SECTIONS) {
-        const spec = pkg[section]?.[name];
-        if (spec === undefined) continue;
-        const drift = pinnedSpec(spec, pin);
-        if (drift) findings.push({ code: 'HFS_CANON_PIN_DRIFT', level: 'error', path: file, dependency: name, section, pinned: pin.version, declared: spec, message: `${name} in ${file} ${section}: ${drift}` });
-      }
-    }
-  }
-  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();
@@ -221,7 +199,7 @@ function treeFindings({ repoRoot, resolver }) {
   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` });
+    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` });
@@ -237,77 +215,90 @@ function treeFindings({ repoRoot, resolver }) {
 /** A side-relative path (or null) as an app-relative one. */
 const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
 
-/**
- * The findings of one scope: the app root (profile app; its own files, and the rules of the files only the root holds: the one
- * package.json and lockfile, CI, hooks, .starciwork, .starcistacks) or one side (profile be or fe; the side folder is `repoRoot` and every path is
- * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
- * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
- */
-function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, editionDeclaration = true }) {
-  const inScope = (file) => !scoped || scoped.has(file);
-  // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
-  const trackedSet = new Set(all);
-  const present = (p) => (p.endsWith('/') ? all.some((f) => f.startsWith(p)) : trackedSet.has(p));
-  const findings = [];
-  const isRoot = repo.profile === APP_SCOPE;
-
-  findings.push(...pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile }));
-
-  const required = resolver.requiredPaths();
+function appendRequiredPathFindings(findings, resolver, files, required, present) {
   const missing = new Set();
   const missingFile = (slot, p, via) => {
     const key = `${slot}|${p}`;
     if (missing.has(key) || present(p)) return;
     missing.add(key);
     const app = appOf(p);
-    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` });
+    const appNote = app ? ` (app ${app})` : '';
+    findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${appNote}, which is not tracked` });
   };
-  // The app's own required paths; each side reports its own (the resolver of the app lists them too, with their side).
   for (const entry of required.paths) if (!entry.side) missingFile(entry.slot, entry.path, entry.via);
   const instances = instancesOf(resolver, files);
   for (const instance of instances) for (const p of requiredOf(resolver.slot(instance.slot), instance)) missingFile(instance.slot, p, 'requires');
+  return instances;
+}
+
+function minimumInstanceFindings(resolver, required, instances) {
+  const findings = [];
   for (const { slot, min, appKind, side } of required.minimums) {
     if (appKind !== undefined || side) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
-    const count = instances.filter((i) => i.slot === slot).length;
+    const count = instances.filter((instance) => instance.slot === slot).length;
     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}` });
   }
-  // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
-  if (repo.kind === RUNTIME_KIND) return findings;
-
-  const pins = readPins(root);
-  findings.push(...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }));
+  return findings;
+}
 
-  // The tree checks of the rules that read file content or configuration (rules/*): whole-scope, cheap, no tool run.
-  findings.push(
-    ...supabaseSecretFindings({ repoRoot, files: files.filter(inScope), resolver, repo }),
-    ...editionFindings({ repoRoot, files: files.filter(inScope), repo, resolver, withDeclaration: editionDeclaration }),
+function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, editionDeclaration }) {
+  const findings = [
+    ...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }),
+    ...supabaseSecretFindings({ repoRoot, files: files.filter((file) => inScope(file)), resolver, repo }),
+    ...editionFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, resolver, withDeclaration: editionDeclaration }),
     ...repoLocalCheckFindings({ repoRoot, files }),
     ...lintSuppressionFindings({ repoRoot, files }),
-  );
+  ];
   if (isRoot) {
     findings.push(
       ...appRootFindings({ repoRoot, files, all, repo, resolver, pins }),
-      // The tree check of the app root the machine runs per side for a side folder: README, root entries, automatic gates, hooks path.
       ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
     );
   } else if (repo.profile === 'be') {
     findings.push(...contractFindings({ repoRoot, files, repo, resolver }), ...testTopologyFindings({ repoRoot, files }));
   } else {
-    findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter(inScope) }));
+    findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter((file) => inScope(file)) }));
   }
+  return findings;
+}
 
-  if (!isRoot) {
-    const soft = resolver.ruleParams().fileLines.soft;
-    for (const file of files) {
-      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` });
-    }
+function sizeSoftFindings({ repoRoot, resolver, files, inScope }) {
+  const findings = [];
+  const soft = resolver.ruleParams().fileLines.soft;
+  for (const file of files) {
+    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` });
   }
   return findings;
 }
 
+/**
+ * The findings of one scope: the app root (profile app; its own files, and the rules of the files only the root holds: the one
+ * package.json and lockfile, CI, hooks, .starciwork, .starcistacks) or one side (profile be or fe; the side folder is `repoRoot` and every path is
+ * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
+ * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
+ */
+function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, editionDeclaration = true }) {
+  const inScope = (file) => !scoped || scoped.has(file);
+  // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
+  const trackedSet = new Set(all);
+  const present = (p) => (p.endsWith('/') ? all.some((f) => f.startsWith(p)) : trackedSet.has(p));
+  const isRoot = repo.profile === APP_SCOPE;
+  const findings = pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile });
+  const required = resolver.requiredPaths();
+  const instances = appendRequiredPathFindings(findings, resolver, files, required, present);
+  findings.push(...minimumInstanceFindings(resolver, required, instances));
+  // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
+  if (repo.kind === RUNTIME_KIND) return findings;
+
+  const pins = readPins(root);
+  findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, editionDeclaration }));
+  if (!isRoot) findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
+  return findings;
+}
+
 /**
  * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `declaration` overrides hfs.json
  * (a dry run over an app that has none); `files` overrides git ls-files (specs), app-relative. `only` (a list of app-relative paths)
@@ -386,7 +377,7 @@ function changedSince(repoRoot, base) {
 
 /** 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}` });
+  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)];
 }
 
@@ -438,7 +429,7 @@ function machineOver({ scope, manifest, machine, changed }) {
   if (changed) {
     const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, scope.repoRoot));
     const mine = changed.files.filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length));
-    paths = [...new Set(mine.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
+    paths = [...new Set(mine.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort(byCodeUnit);
     if (!paths.length) return { info: { side, status: 'skipped', reason: `no changed source file in ${label}` }, findings: [] };
   }
   let report;
@@ -485,7 +476,7 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
     tier: tier ?? 'none',
     owner: owner ? { slot: owner.slot, root: owner.root } : null,
     allowedImports: mayImport,
-    importRule: mayImport ? manifest.crossOwner : (tier === 'none' ? 'the slot takes no part in import checks' : null),
+    importRule: mayImport ? manifest.crossOwner : (tier === 'none' && 'the slot takes no part in import checks' || null),
     tests: slot.tests,
     testsMeaning: TEST_KIND[slot.tests],
     requiredFiles: resolver.requiredFiles(c.path),

package/runtime/scripts/hfs/coverage-scope.mjs

@@ -13,18 +13,38 @@
 // and `starci app check` compares the files with this derivation. Nothing here lists a path of a product: it all comes from slots.yaml.
 import { braceVariants, globExpression } from '../lib/glob.mjs';
 import { logicRolesOf } from './manifest-shape.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+import { trimTrailingSlashes } from './trailing-slashes.mjs';
 
 /** The component that holds the shared infrastructure: the platform tier and every capability more than one service app composes. */
 export const PLATFORM_COMPONENT = 'platform';
 const SERVICE_APP_KINDS = new Set(['api', 'worker']);
-const star = (text) => String(text).replace(/<[^>]+>/g, '*');
-const segments = (dir) => dir.replace(/\/+$/, '').split('/').filter(Boolean);
+/** `text` with every `<placeholder>` (a `<`, at least one character, the next `>`) replaced by `*`; a `<` with no closing `>` stays. */
+export const star = (text) => {
+  const source = String(text);
+  let result = '';
+  let copied = 0;
+  let open = source.indexOf('<');
+  while (open !== -1) {
+    const close = source.indexOf('>', open + 1);
+    if (close === -1) break;
+    if (close === open + 1) {
+      open = source.indexOf('<', close);
+      continue;
+    }
+    result += `${source.slice(copied, open)}*`;
+    copied = close + 1;
+    open = source.indexOf('<', copied);
+  }
+  return result + source.slice(copied);
+};
+export const segments = (dir, trimSlashes = false) => (trimSlashes ? trimTrailingSlashes(dir) : dir).split('/').filter(Boolean);
 const isDir = (path) => path.endsWith('/');
 
 /** True when directory pattern `inner` lies inside `outer` (an outer `*` segment matches any one inner segment) or is the same. */
-function nested(inner, outer) {
-  const a = segments(inner);
-  const b = segments(outer);
+export function nested(inner, outer) {
+  const a = segments(inner, true);
+  const b = segments(outer, true);
   return a.length >= b.length && b.every((segment, index) => segment === '*' ? true : segment === a[index]);
 }
 
@@ -37,6 +57,24 @@ const variantsOf = (slot) => braceVariants(slot.path).map(star);
  */
 const beSlots = (manifest, providers) => manifest.slots.filter((slot) => slot.profiles.includes('be') && slot.tracked === 'tracked' && (slot.provider === undefined || providers.includes(slot.provider)));
 
+function addRequiredPatterns(sonar, required, suffixes) {
+  const escapedSuffixes = suffixes.map((suffix) => suffix.replaceAll('-', String.raw`\-`)).join('|');
+  const isRole = new RegExp(String.raw`\.(?:${escapedSuffixes})\.ts$`);
+  for (const slot of required) {
+    for (const entry of [...(slot.requires ?? []), ...(slot.allows ?? [])]) {
+      addEntryPatterns(sonar, slot, entry, isRole);
+    }
+  }
+}
+
+function addEntryPatterns(sonar, slot, entry, isRole) {
+  if (!entry.endsWith('.ts') || entry.includes('<role>')) return;
+  for (const name of braceVariants(entry)) {
+    if (isRole.test(star(name).replaceAll('*', 'x'))) continue;
+    for (const dir of variantsOf(slot)) sonar.add(`be/${dir}${star(name)}`.replace(/\/\/+/g, '/'));
+  }
+}
+
 /** The directory a path pattern lives in (itself when it is one). */
 const dirOf = (path) => (isDir(path) ? path : path.slice(0, path.lastIndexOf('/') + 1));
 
@@ -64,31 +102,26 @@ export function coverageScope(manifest, providers = []) {
     if (!isDir(dir)) throw new Error(`slot ${slot.id} is coverage: required but its path ${slot.path} is not a directory`);
     return dir;
   }));
-  const roots = minimal(requiredDirs).sort();
+  const roots = minimal(requiredDirs).sort(byCodeUnit);
   const nonePaths = none.flatMap((slot) => variantsOf(slot));
   for (const dir of nonePaths.filter(isDir)) if (requiredDirs.some((other) => nested(other, dir))) throw new Error(`a coverage: none directory ${dir} contains a coverage: required slot`);
   const noneUnique = [...new Set(nonePaths)];
   const noneMinimal = noneUnique.filter((path) => !noneUnique.some((other) => other !== path && isDir(other) && nested(dirOf(path), other)));
-  const excludes = noneMinimal.filter((path) => isDir(path) && roots.some((root) => nested(path, root))).sort();
+  const excludes = noneMinimal.filter((path) => isDir(path) && roots.some((root) => nested(path, root))).sort(byCodeUnit);
   const suffixes = manifest.ruleParams.be.suffixes;
-  const isRole = new RegExp(`\\.(?:${suffixes.map((s) => s.replace(/-/g, '\\-')).join('|')})\\.ts$`);
   const sonar = new Set(noneMinimal.map((path) => `be/${path}${isDir(path) ? '**' : ''}`));
   for (const role of suffixes.filter((suffix) => !roles.includes(suffix))) sonar.add(`be/**/*.${role}.ts`);
-  for (const slot of required) {
-    for (const entry of [...(slot.requires ?? []), ...(slot.allows ?? [])]) {
-      if (!/\.ts$/.test(entry) || entry.includes('<role>')) continue;
-      for (const name of braceVariants(entry)) {
-        if (isRole.test(star(name).replace(/\*/g, 'x'))) continue;
-        for (const dir of variantsOf(slot)) sonar.add(`be/${dir}${star(name)}`.replace(/\/\/+/g, '/'));
-      }
-    }
-  }
+  addRequiredPatterns(sonar, required, suffixes);
   sonar.add('fe/**');
-  return { roles, roots, excludes, none: noneMinimal.sort(), sonar: [...sonar].sort(), codecovPaths: roots.map((root) => `be/${root}**`) };
+  noneMinimal.sort(byCodeUnit);
+  return { roles, roots, excludes, none: noneMinimal, sonar: [...sonar].sort(byCodeUnit), codecovPaths: roots.map((root) => `be/${root}**`) };
 }
 
 /** The glob a root measures: every file of a logic role below it (`src/modules/domain/*\/**\/*.{service,policy}.ts`). */
-export const rootGlob = (root, roles) => `${root}**/*.${roles.length === 1 ? roles[0] : `{${roles.join(',')}}`}.ts`;
+export const rootGlob = (root, roles) => {
+  const roleGlob = roles.length === 1 ? roles[0] : `{${roles.join(',')}}`;
+  return `${root}**/*.${roleGlob}.ts`;
+};
 
 /** The jest coverage options of the rendered be/jest.config.js: { roots, roles, excludes }. */
 export function jestCoverage(manifest, providers = []) {
@@ -107,13 +140,17 @@ export const codecovPaths = (manifest, providers = []) => coverageScope(manifest
  * (`src/modules/domain/*\/` and `src/modules/domain/order/order.service.ts` give `order`).
  */
 function capabilityOf(root, file) {
-  const parts = segments(root);
+  const parts = segments(root, true);
   const at = parts.length - 1;
   if (parts[at] !== '*') return null;
   const own = file.split('/');
   return parts.slice(0, at).every((part, index) => part === own[index]) && own.length > at + 1 ? own[at] : null;
 }
 
+function escapeImportPart(part) {
+  return part.replace(/[/.]/g, String.raw`\$&`);
+}
+
 /**
  * The Codecov components of an app, [{ id, name, paths }] (paths repository-relative from the app root): one per service app (api or worker)
  * that composes the capabilities nothing else composes, then `platform`. A capability of a root whose last segment is a placeholder
@@ -130,28 +167,37 @@ export function coverageComponents(manifest, { files, read, apps, providers = []
   const imports = new Map(services.map((app) => [app.name, files.filter((file) => file.startsWith(`apps/${app.name}/`) && /\.[cm]?ts$/.test(file)).map((file) => read(file)).join('\n')]));
   const platformPaths = [];
   const ownedBy = new Map(services.map((app) => [app.name, []]));
-  for (const root of roots) {
-    const module = /^src\/modules\/(.+)\/\*\/$/.exec(root)?.[1] ?? null;
-    const capabilities = [...new Set(files.map((file) => capabilityOf(root, file)).filter(Boolean))].sort();
-    const base = root.slice(0, -2);
-    if (module === null || module === 'platform' || !capabilities.length) {
-      platformPaths.push(`be/${root}**`);
-      continue;
-    }
-    for (const capability of capabilities) {
-      const spec = new RegExp(`from\\s+["']@modules/${module.replace(/[/.]/g, '\\$&')}/${capability.replace(/[/.]/g, '\\$&')}["']`);
-      const importers = services.filter((app) => spec.test(imports.get(app.name)));
-      const owners = importers.length === 1 ? importers : importers.filter((app) => app.name === capability);
-      if (owners.length === 1) ownedBy.get(owners[0].name).push(`be/${base}${capability}/**`);
-      else platformPaths.push(`be/${base}${capability}/**`);
-    }
-  }
+  for (const root of roots) assignRoot({ root, files, services, imports, platformPaths, ownedBy });
+  const components = services.filter((app) => ownedBy.get(app.name).length).map((app) => {
+    const paths = ownedBy.get(app.name);
+    paths.sort(byCodeUnit);
+    return { id: app.name, name: app.name, paths };
+  });
+  if (platformPaths.length) platformPaths.sort(byCodeUnit);
   return [
-    ...services.filter((app) => ownedBy.get(app.name).length).map((app) => ({ id: app.name, name: app.name, paths: ownedBy.get(app.name).sort() })),
-    ...(platformPaths.length ? [{ id: PLATFORM_COMPONENT, name: PLATFORM_COMPONENT, paths: platformPaths.sort() }] : []),
+    ...components,
+    ...(platformPaths.length ? [{ id: PLATFORM_COMPONENT, name: PLATFORM_COMPONENT, paths: platformPaths }] : []),
   ];
 }
 
+/** Puts the measured root, or each capability below it, into the platform paths or the paths of the one service app that composes it. */
+function assignRoot({ root, files, services, imports, platformPaths, ownedBy }) {
+  const module = /^src\/modules\/(.+)\/\*\/$/.exec(root)?.[1] ?? null;
+  const capabilities = [...new Set(files.map((file) => capabilityOf(root, file)).filter(Boolean))].sort(byCodeUnit);
+  const base = root.slice(0, -2);
+  if (module === null || module === 'platform' || !capabilities.length) {
+    platformPaths.push(`be/${root}**`);
+    return;
+  }
+  for (const capability of capabilities) {
+    const spec = new RegExp(String.raw`from\s+["']@modules/${escapeImportPart(module)}/${escapeImportPart(capability)}["']`);
+    const importers = services.filter((app) => spec.test(imports.get(app.name)));
+    const owners = importers.length === 1 ? importers : importers.filter((app) => app.name === capability);
+    if (owners.length === 1) ownedBy.get(owners[0].name).push(`be/${base}${capability}/**`);
+    else platformPaths.push(`be/${base}${capability}/**`);
+  }
+}
+
 /** True when the be-relative `file` is measured: it is `<name>.<role>.ts` of a logic role below a measured root and inside no none directory of it. */
 export function isMeasured(manifest, file) {
   const { roots, roles, excludes } = coverageScope(manifest);