@starci/hfs 1.0.1 → 2.0.1

package/sync/index.mjs

@@ -1,16 +1,21 @@
 // hfs sync: render, verify and write the files a product repository cannot `extends`.
 //
-// The generated set (target table below) is husky, both GitHub workflows, .gitignore, sonar-project.properties,
-// codecov.yml and, for a back end, .starciwork/.gitignore. Every file is rendered from templates/ with the
-// repository's hfs.json (profile and apps) and, for the coverage denominators, the same jest/vitest preset the
+// The managed set is read from the slot manifest (knowledge/hfs/slots.yaml): every slot that names `managedBy` lists,
+// in its `path`, the whole files sync renders, and `managedBy` names the template directory they are rendered from:
+// templates/<profile or common>/<managedBy>/<file path with each leading dot dropped>. Two targets are not whole files
+// of a managedBy slot and are listed in this module: the marked block of the shared .gitignore, and
+// .starciwork/.gitignore, which lives inside the .starciwork directory slot. Every file is rendered with the
+// repository's hfs.json (profile and apps) and, for the Sonar exclusions, the same jest preset a back end
 // repository installs. `--check` compares the sha256 of the rendered content with the file on disk and fails on any
 // drift; `--write` rewrites the drifted files. `.gitignore` is the one shared file: only the marked block is managed
-// and the repository's own lines around it are left alone.
+// and the repository's own lines around it are left alone. A back end's package.json is managed by its `scripts`
+// block only (mode scripts, compared as parsed JSON): the rest of the file is the repository's.
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
+import { loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/lib/hfs-slots.mjs';
 import { readDeclaredSonarKey } from './sonar-key.mjs';
 
 export const TEMPLATES_DIR = path.join(import.meta.dirname, '..', 'templates');
@@ -18,7 +23,7 @@ export const NODE_MAJOR = 22;
 export const PROFILES = Object.freeze(['be', 'fe']);
 export const BLOCK_BEGIN = '# >>> hfs sync (managed block; do not edit) >>>';
 export const BLOCK_END = '# <<< hfs sync <<<';
-const HEADER = profile => `# Generated by hfs sync (profile ${profile}). Do not edit: run "npx hfs sync --write".\n`;
+const HEADER = profile => `# Generated by hfs sync (profile ${profile}). Do not edit: run "npx hfs sync --write".`;
 
 export class SyncError extends Error {
   constructor(code, message) {
@@ -27,28 +32,47 @@ export class SyncError extends Error {
   }
 }
 
-// mode: file = whole file, block = the marked block inside a file the repository also writes to.
-// header: whether the generated-by comment leads the content (.starciwork/.gitignore is byte-exact instead).
-export const TARGETS = Object.freeze([
-  { path: '.husky/pre-commit', template: { be: 'be/pre-commit', fe: 'fe/pre-commit' }, mode: 'file', header: true },
-  { path: '.husky/pre-push', template: { be: 'common/pre-push', fe: 'common/pre-push' }, mode: 'file', header: true },
-  { path: '.github/workflows/ci.yml', template: { be: 'common/ci.yml', fe: 'common/ci.yml' }, mode: 'file', header: true },
-  { path: '.github/workflows/e2e.yml', template: { be: 'be/e2e.yml', fe: 'fe/e2e.yml' }, mode: 'file', header: true },
-  { path: '.gitignore', template: { be: 'be/gitignore', fe: 'fe/gitignore' }, mode: 'block', header: false },
-  { path: 'sonar-project.properties', template: { be: 'be/sonar-project.properties', fe: 'fe/sonar-project.properties' }, mode: 'file', header: true },
-  { path: 'codecov.yml', template: { be: 'common/codecov.yml', fe: 'common/codecov.yml' }, mode: 'file', header: true },
-  { path: '.starciwork/.gitignore', template: { be: 'be/starciwork.gitignore' }, mode: 'file', header: false },
+// mode: file = whole file, block = the marked block inside a file the repository also writes to, scripts = the `scripts`
+// block of package.json. A template that can hold a comment opens with {{header}}; a file whose exact content is
+// specified (JSON, the eslint one-liner) has no header.
+const MODE_OF_GROUP = Object.freeze({ 'package-scripts': 'scripts' });
+const LITERAL_FILE = /^[^*?<>{}[\]]+[^/*?<>{}[\]]$/;
+
+/** The targets no managedBy slot lists as a whole file (see the header of this module). */
+export const UNLISTED_TARGETS = Object.freeze([
+  { path: '.gitignore', template: { be: 'be/gitignore', fe: 'fe/gitignore' }, mode: 'block' },
+  { path: '.starciwork/.gitignore', template: { be: 'be/starciwork.gitignore' }, mode: 'file' },
 ].map(Object.freeze));
 
+const templateName = (profile, group, file) => `${profile}/${group}/${file.split('/').map(segment => segment.replace(/^\./, '')).join('/')}`;
+
+/**
+ * Every target of `profile`: the files the manifest's managedBy slots list, then the unlisted ones. A slot that names
+ * managedBy lists literal files only, and each has a template under its profile or under common.
+ */
+export function targetsOf(profile, { manifest = loadSlotManifest(), readTemplate = readBundled, hasTemplate = name => fs.existsSync(path.join(TEMPLATES_DIR, name)) } = {}) {
+  const listed = [];
+  for (const slot of manifest.slots) {
+    if (slot.managedBy === undefined || !slot.profiles.includes(profile)) continue;
+    for (const file of braceVariants(slot.path)) {
+      if (!LITERAL_FILE.test(file)) throw new SyncError('HFS_SYNC_MANIFEST_MANAGED', `slot ${slot.id} names managedBy but its path ${slot.path} is not a list of literal files (${file})`);
+      const template = [profile, 'common'].map(dir => templateName(dir, slot.managedBy, file)).find(hasTemplate);
+      if (!template) throw new SyncError('HFS_SYNC_TEMPLATE_MISSING', `slot ${slot.id} manages ${file} for ${profile}, but templates/{${profile},common}/${slot.managedBy} has no template for it`);
+      listed.push({ path: file, template, mode: MODE_OF_GROUP[slot.managedBy] ?? 'file', slot: slot.id });
+    }
+  }
+  return [...listed, ...UNLISTED_TARGETS.filter(target => target.template[profile]).map(target => ({ path: target.path, template: target.template[profile], mode: target.mode }))];
+}
+
 const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const lf = text => text.replace(/\r\n/g, '\n');
 export const hashOf = text => createHash('sha256').update(lf(text)).digest('hex');
 
-/** The hfs.json shape sync reads: hfs 2, profile, project and a non-empty apps list. */
-export function validateHfs(hfs) {
+/** The hfs.json shape sync reads: the manifest major, profile, project and a non-empty apps list (a back end names each app's kind). */
+export function validateHfs(hfs, manifest = loadSlotManifest()) {
   const bad = message => { throw new SyncError('HFS_SYNC_HFS_INVALID', message); };
   if (!hfs || typeof hfs !== 'object') bad('hfs.json is not an object');
-  if (hfs.hfs !== 2) bad('hfs must be 2');
+  if (hfs.hfs !== manifest.major) bad(`hfs must be ${manifest.major}, the major of the slot manifest`);
   if (!PROFILES.includes(hfs.profile)) bad(`profile must be one of ${PROFILES.join(', ')}`);
   if (typeof hfs.project !== 'string' || !KEBAB.test(hfs.project)) bad('project must be a kebab-case name');
   if (!Array.isArray(hfs.apps) || hfs.apps.length === 0) bad('apps must list at least one app');
@@ -60,8 +84,16 @@ export function validateHfs(hfs) {
   for (const app of hfs.apps) {
     if (!app || typeof app.name !== 'string' || !KEBAB.test(app.name)) bad('every app needs a kebab-case name');
     if (seen.has(app.name)) bad(`app ${app.name} is listed twice`);
+    if (hfs.profile === 'be' && !manifest.appKinds.be.includes(app.kind)) bad(`app ${app.name} needs a kind, one of ${manifest.appKinds.be.join(', ')}`);
     seen.add(app.name);
   }
+  // The whole declaration must be valid for the manifest it pins (connections, optional slots, ...): sync never renders
+  // configs for a declaration the eslint canons and hfs check would refuse, so a pin bump cannot leave lint unable to start.
+  try {
+    resolveRepoDeclaration(manifest, hfs);
+  } catch (error) {
+    bad(`hfs.json is not a valid declaration for manifest ${manifest.version}: ${error.message}`);
+  }
   return hfs;
 }
 
@@ -78,9 +110,10 @@ export function render(text, vars, readTemplate = readBundled) {
   });
 }
 
-/** Coverage denominators from the preset the repository installs: { sonarExclusions, sonarCoverageExclusions }. */
+/** The Sonar exclusions from the jest preset a back end installs: { sonarExclusions }; a front end has no test runner and no preset: null. */
 export async function loadPresets(root, profile) {
-  const name = profile === 'be' ? '@starci/jest-preset' : '@starci/vitest-preset';
+  if (profile === 'fe') return null;
+  const name = '@starci/jest-preset';
   const require = createRequire(path.join(root, 'package.json'));
   let resolved;
   try {
@@ -88,40 +121,87 @@ export async function loadPresets(root, profile) {
   } catch {
     throw new SyncError('HFS_SYNC_PRESET_MISSING', `${name} is not installed under ${root}; set it to the exact version in knowledge/hfs/canon-pins.yaml and reinstall`);
   }
-  const preset = profile === 'be' ? require(resolved) : await import(pathToFileURL(resolved).href);
-  return { sonarExclusions: preset.sonarExclusions(), sonarCoverageExclusions: preset.sonarCoverageExclusions() };
+  const preset = require(resolved);
+  return { sonarExclusions: preset.sonarExclusions() };
 }
 
+/**
+ * The package.json script lines the apps add, each ending with a comma (the template puts them mid-object). A back end:
+ * `start:<app>` runs a built api, worker or cli app, `migrate` the migrate app. A front end: `dev:<app>` and `start:<app>`
+ * run the app's own script through its workspace path (the npm workspace of apps/<app>).
+ */
+export function appScripts(profile, apps) {
+  const line = (name, command) => `${JSON.stringify(name)}: ${JSON.stringify(command)},`;
+  if (profile === 'fe') return apps.flatMap(app => [line(`dev:${app.name}`, `npm run dev --workspace apps/${app.name}`), line(`start:${app.name}`, `npm run start --workspace apps/${app.name}`)]).join('\n    ');
+  const migrates = apps.filter(app => app.kind === 'migrate');
+  return apps.map(app => {
+    const name = app.kind === 'migrate' ? (migrates.length === 1 ? 'migrate' : `migrate:${app.name}`) : `start:${app.name}`;
+    return line(name, `node dist/apps/${app.name}/src/main.js`);
+  }).join('\n    ');
+}
+
+/** True when hfs.json opts into a workspace package (repo.packages or any fe.package.* slot): the sources then include packages/. */
+export const opensPackages = hfs => (hfs.optionalSlots ?? []).some(id => id === 'repo.packages' || String(id).startsWith('fe.package.'));
+
+/** The stylesheets of a front end the CSS canon judges: every app and every workspace package (slot fe.route, fe.package.*). */
+export const STYLE_GLOB = '{apps,packages}/*/src/**/*.css';
+
 /** Every value a template can name, derived from hfs.json and the presets. */
 export function variables(hfs, presets, sonarKey) {
-  const globs = [...presets.sonarExclusions.split(','), ...presets.sonarCoverageExclusions.split(',')];
+  const packages = hfs.profile === 'fe' && opensPackages(hfs);
   return {
+    header: HEADER(hfs.profile),
+    appScripts: appScripts(hfs.profile, hfs.apps),
     profile: hfs.profile,
     nodeMajor: String(NODE_MAJOR),
     sonarKey: sonarKey ?? `${hfs.project}-${hfs.profile === 'be' ? 'backend' : 'fe'}`,
-    sonarExclusions: presets.sonarExclusions,
-    sonarCoverageExclusions: presets.sonarCoverageExclusions,
-    codecovIgnore: globs.map(glob => JSON.stringify(glob)).join('\n  - '),
-    tsconfigPaths: hfs.apps.map(app => `apps/${app.name}/tsconfig.json`).join(','),
+    sonarExclusions: presets?.sonarExclusions ?? '',
+    tsconfigPaths: [...hfs.apps.map(app => `apps/${app.name}/tsconfig.json`), ...(packages ? ['packages/*/tsconfig.json'] : [])].join(','),
+    sonarRoots: packages ? 'apps,packages' : 'apps',
+    styleGlob: STYLE_GLOB,
   };
 }
 
-/** The managed content of every target this profile owns: [{ path, mode, content, hash }]. */
-/** `sonarKey` is the key the repository's stack declaration names; without one the key is derived from hfs.json. */
-export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled } = {}) {
-  validateHfs(hfs);
+// The scripts of a package.json as one comparable text: a line per script, sorted by name (order is not drift).
+const scriptsText = scripts => `${Object.keys(scripts).sort().map(name => `${name}: ${typeof scripts[name] === 'string' ? scripts[name] : JSON.stringify(scripts[name])}`).join('\n')}\n`;
+
+function parseScripts(text) {
+  try {
+    const { scripts } = JSON.parse(text);
+    return scripts && typeof scripts === 'object' && !Array.isArray(scripts) ? scripts : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The managed content of every target this profile owns: [{ path, mode, content, hash }] (a scripts target also carries
+ * `scripts`, the parsed block). `sonarKey` is the key the repository's stack declaration names; without one the key is
+ * derived from hfs.json.
+ */
+export function renderTargets(hfs, presets, { sonarKey, readTemplate = readBundled, manifest = loadSlotManifest() } = {}) {
+  validateHfs(hfs, manifest);
   const vars = variables(hfs, presets, sonarKey);
-  return TARGETS.filter(target => target.template[hfs.profile]).map(target => {
-    const body = render(readTemplate(target.template[hfs.profile]), vars, readTemplate);
-    const content = target.header ? HEADER(hfs.profile) + body : body;
-    const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${content.replace(/\n*$/, '\n')}${BLOCK_END}\n` : content;
+  return targetsOf(hfs.profile, { manifest, readTemplate, hasTemplate: name => { try { return readTemplate(name) !== undefined; } catch { return false; } } }).map(target => {
+    const body = render(readTemplate(target.template), vars, readTemplate);
+    if (target.mode === 'scripts') {
+      const scripts = parseScripts(body);
+      if (!scripts) throw new SyncError('HFS_SYNC_TEMPLATE_VARIABLE', `the rendered ${target.template} has no scripts object`);
+      const content = scriptsText(scripts);
+      return { path: target.path, mode: 'scripts', content, hash: hashOf(content), scripts };
+    }
+    const managed = target.mode === 'block' ? `${BLOCK_BEGIN}\n${body.replace(/\n*$/, '\n')}${BLOCK_END}\n` : body;
     return { path: target.path, mode: target.mode, content: managed, hash: hashOf(managed) };
   });
 }
 
-// The part of a file sync manages: all of it, or the marked block.
+// The part of a file sync manages: all of it, the marked block, or the scripts block as text.
 function managedPart(mode, text) {
   if (mode === 'file') return text;
+  if (mode === 'scripts') {
+    const scripts = parseScripts(text);
+    return scripts ? scriptsText(scripts) : null;
+  }
   const start = text.indexOf(BLOCK_BEGIN);
   const end = text.indexOf(BLOCK_END);
   if (start < 0 || end < start) return null;
@@ -159,7 +239,13 @@ export function writeTargets(root, targets) {
     const file = path.join(root, target.path);
     const existing = fs.existsSync(file) ? lf(fs.readFileSync(file, 'utf8')) : '';
     let next = target.content;
-    if (target.mode === 'block' && existing) {
+    if (target.mode === 'scripts') {
+      let pkg = {};
+      if (existing) {
+        try { pkg = JSON.parse(existing); } catch { throw new SyncError('HFS_SYNC_HFS_INVALID', `${target.path} is not valid JSON; fix it by hand before sync can set its scripts`); }
+      }
+      next = `${JSON.stringify({ ...pkg, scripts: target.scripts }, null, 2)}\n`;
+    } else if (target.mode === 'block' && existing) {
       const current = managedPart('block', existing);
       next = current === null ? `${target.content}\n${existing}` : existing.replace(current, () => target.content);
     }
@@ -181,6 +267,13 @@ export function loadHfs(root) {
   }
 }
 
+/** The rendered targets of the repository at `root`: its hfs.json, the Sonar key its stack declaration names, the presets it installs. */
+export async function renderRepo(root, { presets, parseYaml } = {}) {
+  const hfs = loadHfs(root);
+  const sonarKey = await readDeclaredSonarKey(root, { parseYaml, stacks: hfs.stacks, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
+  return { hfs, targets: renderTargets(hfs, presets ?? await loadPresets(root, hfs.profile), { sonarKey }) };
+}
+
 /** `hfs sync --check | --write [--root <dir>]`; returns the exit code (0 clean, 1 drift or error, 2 usage). */
 export async function runSync(argv, { cwd = process.cwd(), out = line => process.stdout.write(`${line}\n`), presets, parseYaml } = {}) {
   const check = argv.includes('--check'), write = argv.includes('--write'), init = argv.includes('--init');
@@ -199,8 +292,7 @@ export async function runSync(argv, { cwd = process.cwd(), out = line => process
       out(`hfs sync --init: ${created.length} created, ${skipped.length} already exist and were left alone`);
       return 0;
     }
-    const sonarKey = await readDeclaredSonarKey(root, { parseYaml, stacks: hfs.stacks, fail: message => { throw new SyncError('HFS_SYNC_SONAR_KEY', message); } });
-    const targets = renderTargets(hfs, presets ?? await loadPresets(root, hfs.profile), { sonarKey });
+    const { targets } = await renderRepo(root, { presets, parseYaml });
     if (write) {
       const written = writeTargets(root, targets);
       for (const file of written) out(`wrote ${file}`);

package/sync/managed.mjs

@@ -0,0 +1,170 @@
+// The managed-file findings of `hfs check` (BE-CONVENTION 1.17, 3.1 principle 4): the rendered set of `hfs sync`, compared
+// with the tracked repository, and the tool configuration nothing may add to it.
+//   HFS_MANAGED_FILE_DRIFT (R05)  a managed file that exists but differs from its render: tsconfig*.json (but see R22),
+//                                 jest.config.js (back end), .prettierrc, .prettierignore, husky hooks, both workflows and sonar
+//                                 files, and the `scripts` block of package.json (compared as parsed JSON, so key order is
+//                                 not drift). A file that is absent is the slot manifest's finding (HFS_SLOT_REQUIRED_MISSING);
+//                                 the `.gitignore` block is R04's.
+//   HFS_GITIGNORE_BLOCK_DRIFT (R04)
+//                                 the managed block of `.gitignore` differs from the rendered block, or is not there; the
+//                                 repository's own lines around the block are not judged.
+//   HFS_RULE_OFF_WITHOUT_REPLACEMENT (R17)
+//                                 eslint.config.mjs (either profile) or stylelint.config.mjs (front end) differs from its render.
+//                                 The render is the one-liner that calls the canon factory, and the factory takes no override, so a rule can be off, warned or redefined
+//                                 in a repository only through a difference from the render: R17's proof is the comparison.
+//                                 The file is judged here and not under R05, so one edit is one finding.
+//   HFS_TOOL_CONFIG_LOCAL (R16)   what the render does not cover and could still weaken the canon: a tracked file that defines
+//                                 an ESLint rule (`meta.type` plus `create(context)`) or a stylelint plugin (`createPlugin`), a script or
+//                                 nested package.json that runs eslint, stylelint or prettier with a flag that swaps or switches off the
+//                                 configuration, and a package.json that carries a tool configuration key (`eslintConfig`, `stylelint`,
+//                                 `prettier`, `lint-staged`, `jest`). Forbidden tool-config files (.eslintrc*, .eslintignore, a second
+//                                 eslint.config.*) are refused by hfs-check through the slot manifest under the same code.
+//   HFS_SONAR_CONFIG (R11)        sonar-project.properties differs from its render (the render names no host URL, sources and tests that
+//                                 do not overlap, the `sonar.exclusions` of the jest preset (a back end), no coverage import, the ESLint report and the
+//                                 HFS import files Sonar reads), or the stack declaration names a quality gate other than the one
+//                                 gate of knowledge/sonar-gate.yaml (bundled in the runtime copy). One edit is one finding.
+//   HFS_TS_STRICT (R22)           the root tsconfig.json drift (either profile), named by flag (ts-strict.mjs) instead of by hash.
+import fs from 'node:fs';
+import path from 'node:path';
+import { SyncError, checkTargets, renderRepo } from './index.mjs';
+import { parseYaml as bundledParseYaml } from '../runtime/engine/yaml.mjs';
+import { readDeclaredSonarGate } from './sonar-key.mjs';
+import { TS_STRICT_FILE, tsStrictFindings } from './ts-strict.mjs';
+
+// The managed one-liners whose difference from the render is the proof that no rule is off, warned or redefined (R17).
+const ONE_LINER_FILES = new Set(['eslint.config.mjs', 'stylelint.config.mjs']);
+const SONAR_PROPERTIES_FILE = 'sonar-project.properties';
+const SONAR_GATE_FILE = new URL('../runtime/knowledge/sonar-gate.yaml', import.meta.url);
+const MAX_SCANNED_BYTES = 1024 * 1024;
+const RULE_FILE = /\.[cm]?[jt]s$/;
+// The places a command line can still live: the repository's scripts (repo.scripts) and its nested package.json files. The
+// root package.json, the hooks and the workflows are managed files, and no other hook, workflow or shell script has a slot.
+const SCRIPT_FILE = /^scripts\/[^/]+\.mjs$/;
+// An ESLint rule module: `meta` with an ESLint rule type, and a `create` that takes the rule context.
+const RULE_META = /\bmeta\s*:\s*\{[^}]*\btype\s*:\s*["'`](?:problem|suggestion|layout)["'`]/s;
+const RULE_CREATE = /\bcreate\s*(?:\(|:\s*(?:async\s+)?(?:function\s*)?\()\s*\w+/;
+// A stylelint plugin: `stylelint.createPlugin(ruleName, rule)` in a file that imports stylelint, the only way a repository adds a CSS rule.
+const STYLELINT_CREATE_PLUGIN = /\bcreatePlugin\s*\(/;
+const STYLELINT_IMPORT = /["']stylelint["']/;
+// Keys of package.json that are a second home for a tool's configuration.
+const TOOL_CONFIG_KEYS = ['eslintConfig', 'stylelint', 'prettier', 'lint-staged', 'jest'];
+// Flags that swap the configuration or switch a rule or a directive off. Only a line that runs the tool is judged.
+const TOOL_FLAGS = [
+  { tool: /\beslint\b/, flag: /(?<![\w-])(--rule|--no-inline-config|--no-eslintrc|--no-config-lookup|--config|-c|--ignore-pattern|--ignore-path|--no-ignore|--rulesdir|--plugin|--parser|--parser-options|--env|--global)(?![\w-])/ },
+  { tool: /\bstylelint\b/, flag: /(?<![\w-])(--config|--config-basedir|--ignore-path|--ignore-pattern|--custom-syntax|--disable-default-ignores)(?![\w-])/ },
+  { tool: /\bprettier\b/, flag: /(?<![\w-])(--config|--no-config|--ignore-path|--no-editorconfig|--plugin)(?![\w-])/ },
+];
+
+const readText = (root, file) => {
+  try {
+    const target = path.join(root, file);
+    return fs.statSync(target).size > MAX_SCANNED_BYTES ? null : fs.readFileSync(target, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const local = (file, message) => ({ code: 'HFS_TOOL_CONFIG_LOCAL', level: 'error', path: file, message });
+
+/** Every managed target that exists on disk but differs from its render, as one finding each. */
+function driftFindings(repoRoot, targets) {
+  const findings = [];
+  for (const result of checkTargets(repoRoot, targets)) {
+    const target = targets.find(candidate => candidate.path === result.path);
+    if (!fs.existsSync(path.join(repoRoot, result.path)) || result.status === 'ok') continue;
+    if (result.path === TS_STRICT_FILE) {
+      const flags = tsStrictFindings(fs.readFileSync(path.join(repoRoot, result.path), 'utf8'), target.content);
+      if (flags.length) {
+        findings.push(...flags);
+        continue;
+      }
+    }
+    const code = target.mode === 'block' ? 'HFS_GITIGNORE_BLOCK_DRIFT' : ONE_LINER_FILES.has(result.path) ? 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' : result.path === SONAR_PROPERTIES_FILE ? 'HFS_SONAR_CONFIG' : 'HFS_MANAGED_FILE_DRIFT';
+    const where = result.difference ? `; line ${result.difference.line} expected ${JSON.stringify(result.difference.expected)}, found ${JSON.stringify(result.difference.actual)}` : '';
+    const what = target.mode === 'block' ? `the managed block of ${result.path} is ${result.status === 'missing' ? 'missing' : 'not its render'}` : target.mode === 'scripts' ? 'the scripts block of package.json is not the rendered one' : `${result.path} is not its render${code === 'HFS_RULE_OFF_WITHOUT_REPLACEMENT' ? ', so a rule can be off or redefined in it' : ''}`;
+    findings.push({ code, level: 'error', path: result.path, mode: target.mode, expectedHash: result.expectedHash, ...(result.actualHash ? { actualHash: result.actualHash } : {}), message: `${what} (expected sha256 ${result.expectedHash.slice(0, 12)}${result.actualHash ? `, found ${result.actualHash.slice(0, 12)}` : ''}${where}); run "npx hfs sync --write"` });
+  }
+  return findings;
+}
+
+/** R11: the quality gate the stack declaration names is the one gate of the bundled knowledge/sonar-gate.yaml. */
+function sonarGateFindings(repoRoot, hfs, parseYaml) {
+  const declared = readDeclaredSonarGate(repoRoot, { parseYaml, stacks: hfs.stacks });
+  if (declared === null) return [];
+  const gate = (parseYaml ?? bundledParseYaml)(fs.readFileSync(SONAR_GATE_FILE, 'utf8'))?.gate?.name;
+  if (declared.qualityGate === gate) return [];
+  return [{ code: 'HFS_SONAR_CONFIG', level: 'error', path: declared.file, message: `${declared.file} services.sonar.qualityGate is ${declared.qualityGate ?? 'absent'}; every product names the one gate ${gate} of knowledge/sonar-gate.yaml and states no threshold of its own` }];
+}
+
+function ruleFileFindings(repoRoot, tracked) {
+  const findings = [];
+  for (const file of tracked.filter(candidate => RULE_FILE.test(candidate))) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    if (RULE_META.test(text) && RULE_CREATE.test(text)) findings.push(local(file, `${file} defines an ESLint rule; a repository defines no rule, the canon plugin is the only source`));
+    else if (STYLELINT_CREATE_PLUGIN.test(text) && STYLELINT_IMPORT.test(text)) findings.push(local(file, `${file} defines a stylelint plugin; a repository defines no rule, @starci/stylelint-canon is the only source`));
+  }
+  return findings;
+}
+
+/** A package.json that keeps a tool's configuration under a key: a second source beside the managed file. */
+function toolKeyFindings(repoRoot, tracked) {
+  const findings = [];
+  for (const file of tracked.filter(candidate => candidate === 'package.json' || candidate.endsWith('/package.json'))) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    let manifest;
+    try { manifest = JSON.parse(text); } catch { continue; }
+    for (const key of TOOL_CONFIG_KEYS) {
+      if (manifest && typeof manifest === 'object' && Object.hasOwn(manifest, key)) findings.push(local(file, `${file} carries a "${key}" configuration; the tool's configuration is the managed file and nothing else`));
+    }
+  }
+  return findings;
+}
+
+function flagFindings(repoRoot, tracked, managed) {
+  const findings = [];
+  const commandLines = (file, text) => {
+    if (file.endsWith('package.json')) {
+      try {
+        return Object.entries(JSON.parse(text).scripts ?? {}).map(([name, command]) => [`script ${name}`, String(command)]);
+      } catch {
+        return [];
+      }
+    }
+    return text.split('\n').map((line, index) => [`line ${index + 1}`, line]);
+  };
+  for (const file of tracked.filter(candidate => !managed.has(candidate) && (SCRIPT_FILE.test(candidate) || candidate.endsWith('/package.json')))) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    for (const [where, line] of commandLines(file, text)) {
+      for (const { tool, flag } of TOOL_FLAGS) {
+        const hit = tool.test(line) && flag.exec(line);
+        if (hit) findings.push(local(file, `${file} (${where}) runs ${tool.source.replace(/\\b/g, '')} with ${hit[1]}, which swaps or switches off the canon configuration; run the tool with no such flag`));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * The managed-file findings of the repository at `repoRoot` whose tracked paths are `tracked`. A repository whose hfs.json
+ * is unreadable has none: the slot check reports the declaration. A missing preset or an unreadable stack declaration is
+ * a SyncError the caller reports as a refusal.
+ */
+export async function managedFindings({ repoRoot, tracked, presets, parseYaml }) {
+  let rendered;
+  try {
+    rendered = await renderRepo(repoRoot, { presets, parseYaml });
+  } catch (error) {
+    if (error instanceof SyncError && error.code === 'HFS_SYNC_HFS_INVALID') return [];
+    throw error;
+  }
+  const { hfs, targets } = rendered;
+  const findings = driftFindings(repoRoot, targets);
+  findings.push(...sonarGateFindings(repoRoot, hfs, parseYaml));
+  findings.push(...ruleFileFindings(repoRoot, tracked));
+  findings.push(...toolKeyFindings(repoRoot, tracked));
+  findings.push(...flagFindings(repoRoot, tracked, new Set(targets.map(target => target.path))));
+  return findings;
+}

package/sync/skeleton.mjs

@@ -2,11 +2,20 @@
 // endpoint; for a front end the next-intl [locale] shell with vi default, as-needed prefix and proxy.ts).
 // Unlike the managed files it is written once and never overwritten: an existing file is skipped, so re-running --init
 // on a repository that already grew its own source changes nothing.
+//
+// A front end's skeleton is the templates/fe/skeleton tree (the app shell, common to every repository) plus ONE of two
+// trees for what a repository writes once: with one app the app keeps its own i18n stack and its own API client
+// (templates/fe/skeleton-app); with two or more apps the stack and the client are written once, as the packages
+// `packages/<project>-i18n` and `packages/<project>-api`, and each app keeps a thin adapter over them
+// (templates/fe/skeleton-shared). The choice is the number of apps in hfs.json, nothing else.
 import fs from 'node:fs';
 import path from 'node:path';
 import { TEMPLATES_DIR, SyncError, render, validateHfs } from './index.mjs';
 
 const APP_DIR = '__app__';
+const FAMILY_DIR = '__family__';
+/** The slots a multi-app front end must opt into in hfs.json before its shared packages are written. */
+export const SHARED_PACKAGE_SLOTS = Object.freeze(['fe.package.i18n', 'fe.package.api']);
 const pascal = name => name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('');
 
 function listFiles(dir, base = dir) {
@@ -19,19 +28,32 @@ function listFiles(dir, base = dir) {
 /** The apps that get a skeleton: a back end's `api` apps, every front-end app. */
 export const skeletonApps = hfs => hfs.apps.filter(app => hfs.profile === 'fe' || app.kind === 'api');
 
+/** True when the repository writes its i18n stack and API client once, as packages: a front end with two or more apps. */
+export const sharesPackages = hfs => hfs.profile === 'fe' && hfs.apps.length > 1;
+
+/** The template directories of a repository, in order: the profile's skeleton, then (front end) the one-app or the shared-package tree. */
+export const skeletonDirs = hfs => [path.join(TEMPLATES_DIR, hfs.profile, 'skeleton'), ...(hfs.profile === 'fe' ? [path.join(TEMPLATES_DIR, 'fe', sharesPackages(hfs) ? 'skeleton-shared' : 'skeleton-app')] : [])];
+
 /** Every skeleton file for this repository: [{ path, content }], the shared ones once and the per-app ones per app. */
-export function skeletonFiles(hfs, dir = path.join(TEMPLATES_DIR, hfs.profile, 'skeleton')) {
+export function skeletonFiles(hfs, dirs = skeletonDirs(hfs)) {
   validateHfs(hfs);
-  if (!fs.existsSync(dir)) throw new SyncError('HFS_SYNC_SKELETON_MISSING', `no skeleton templates for profile ${hfs.profile}`);
+  if (sharesPackages(hfs)) {
+    const missing = SHARED_PACKAGE_SLOTS.filter(id => !(hfs.optionalSlots ?? []).includes(id));
+    if (missing.length) throw new SyncError('HFS_SYNC_HFS_INVALID', `a front end with ${hfs.apps.length} apps writes its i18n stack and its API client once, as packages: list ${missing.join(' and ')} in hfs.json optionalSlots before hfs sync --init`);
+  }
   const files = [];
-  for (const rel of listFiles(dir)) {
-    const source = fs.readFileSync(path.join(dir, rel), 'utf8').replace(/\r\n/g, '\n');
-    if (!rel.includes(APP_DIR)) {
-      files.push({ path: rel, content: render(source, {}) });
-      continue;
-    }
-    for (const app of skeletonApps(hfs)) {
-      files.push({ path: rel.split(APP_DIR).join(app.name), content: render(source, { app: app.name, appPascal: pascal(app.name) }) });
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) throw new SyncError('HFS_SYNC_SKELETON_MISSING', `no skeleton templates in ${path.relative(TEMPLATES_DIR, dir)}`);
+    for (const rel of listFiles(dir)) {
+      const source = fs.readFileSync(path.join(dir, rel), 'utf8').replace(/\r\n/g, '\n');
+      const once = { family: hfs.project, project: hfs.project };
+      if (!rel.includes(APP_DIR)) {
+        files.push({ path: rel.split(FAMILY_DIR).join(hfs.project), content: render(source, once) });
+        continue;
+      }
+      for (const app of skeletonApps(hfs)) {
+        files.push({ path: rel.split(APP_DIR).join(app.name), content: render(source, { ...once, app: app.name, appPascal: pascal(app.name) }) });
+      }
     }
   }
   return files;

package/sync/sonar-key.mjs

@@ -43,3 +43,16 @@ export async function readDeclaredSonarKey(root, { parseYaml, fail, stacks }) {
   if (keys.length > 1) fail(`${DECLARATION} declares ${keys.length} Sonar projects for ${repositoryName(root)} (${keys.join(', ')}); one repository has one key`);
   return keys[0] ?? null;
 }
+
+/**
+ * The quality gate the declaration names for Sonar: `{ file, qualityGate }`, or null when there is no declaration, Sonar is
+ * disabled in it, or it declares no Sonar service. The one gate is knowledge/sonar-gate.yaml; a repository names it and
+ * never states thresholds of its own.
+ */
+export function readDeclaredSonarGate(root, { parseYaml, stacks } = {}) {
+  const file = path.join(stacks === undefined ? root : path.resolve(root, stacks), DECLARATION);
+  if (!fs.existsSync(file)) return null;
+  const sonar = (parseYaml ?? bundledParseYaml)(fs.readFileSync(file, 'utf8'))?.services?.sonar;
+  if (!sonar || sonar.mode === 'disabled') return null;
+  return { file: path.relative(root, file).split(path.sep).join('/'), qualityGate: typeof sonar.qualityGate === 'string' ? sonar.qualityGate : null };
+}

package/sync/ts-strict.mjs

@@ -0,0 +1,48 @@
+// HFS_TS_STRICT (R22): a repository's root tsconfig.json extends the canon preset (be.json for a back end, next.json for a
+// front end), adds `paths` when the template has them and the template's `exclude` (the world, integration, e2e and contract trees of a back end, which src/tests/tsconfig.json checks; the e2e tree of a front end),
+// and nothing else. Every strict flag lives in @starci/tsconfig; a repository that sets, lowers or adds any compiler option, or changes the program with
+// include/exclude/files/references, has left the preset. The expected shape is read from the rendered
+// template (templates/<profile>/tool-config/tsconfig.json), so the preset name and the aliases exist in one place only.
+export const TS_STRICT_FILE = 'tsconfig.json';
+
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const describe = (value) => (value === undefined ? 'unset' : JSON.stringify(value));
+
+/**
+ * The HFS_TS_STRICT findings of one tsconfig.json text against the rendered one: [{ code, level, path, flag, message }].
+ * `flag` names the offending key (`extends`, `paths`, a compiler option, or a top-level key).
+ */
+export function tsStrictFindings(actualText, expectedText, file = TS_STRICT_FILE) {
+  const expected = JSON.parse(expectedText);
+  const finding = (flag, message) => ({ code: 'HFS_TS_STRICT', level: 'error', path: file, flag, message: `${file}: ${message}` });
+  let actual;
+  try {
+    actual = JSON.parse(actualText);
+  } catch (error) {
+    return [finding('parse', `is not valid JSON (${String(error.message).split('\n')[0]}); it must be the rendered file, which extends ${expected.extends}`)];
+  }
+  if (!actual || typeof actual !== 'object' || Array.isArray(actual)) return [finding('parse', `is not a JSON object; it must extend ${expected.extends}`)];
+  const findings = [];
+  if (actual.extends !== expected.extends) findings.push(finding('extends', `extends ${describe(actual.extends)}, but the only preset is ${expected.extends}`));
+  for (const key of Object.keys(actual)) {
+    if (key === 'extends' || key === 'compilerOptions') continue;
+    if (key in expected && same(actual[key], expected[key])) continue;
+    findings.push(finding(key, key in expected ? `${key} must be ${describe(expected[key])}, found ${describe(actual[key])}` : `sets ${key}: the program is the template's, narrowed by nothing else`));
+  }
+  for (const key of Object.keys(expected)) {
+    if (key !== 'extends' && key !== 'compilerOptions' && !(key in actual)) findings.push(finding(key, `${key} is missing; it must be ${describe(expected[key])}`));
+  }
+  const options = actual.compilerOptions && typeof actual.compilerOptions === 'object' && !Array.isArray(actual.compilerOptions) ? actual.compilerOptions : {};
+  for (const [flag, value] of Object.entries(options)) {
+    if (flag === 'paths') continue;
+    findings.push(finding(flag, `${value === false ? 'lowers' : 'sets'} ${flag} (${describe(value)}); every compiler option comes from the preset`));
+  }
+  const aliases = expected.compilerOptions?.paths ?? {};
+  for (const alias of Object.keys(aliases)) {
+    if (!same(options.paths?.[alias], aliases[alias])) findings.push(finding('paths', `paths must map ${alias} to ${describe(aliases[alias])}, found ${describe(options.paths?.[alias])}`));
+  }
+  for (const alias of Object.keys(options.paths ?? {})) {
+    if (!(alias in aliases)) findings.push(finding('paths', `paths adds the alias ${alias}; the aliases of the template are the only ones`));
+  }
+  return findings;
+}

package/templates/{common → be/ci-workflows/github/workflows}/ci.yml

@@ -1,3 +1,4 @@
+{{header}}
 name: ci
 
 on:
@@ -7,7 +8,6 @@ on:
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
   ci:
@@ -21,30 +21,30 @@ jobs:
           node-version: {{nodeMajor}}
           cache: npm
       - run: npm ci
-      - name: hfs sync
-        run: npx hfs sync --check
       - name: hfs check
-        run: npx hfs check
+        run: npm run hfs:report
       - name: lint
         run: npm run lint:check
+      - name: lint report
+        if: ${{ !cancelled() }}
+        run: npm run lint:report
+      - name: eslint sonar import
+        if: ${{ !cancelled() }}
+        run: npx hfs report eslint reports/eslint.json reports/eslint.sonar.json
+      - name: format
+        run: npm run format:check
       - name: typecheck
         run: npm run typecheck
       - name: unit
-        run: npm run test:ci
+        run: npm test -- --ci
       - name: build
         run: npm run build
-      - uses: codecov/codecov-action@v5
-        with:
-          files: coverage/lcov.info
-          disable_search: true
-          fail_ci_if_error: true
-          use_oidc: true
       - uses: SonarSource/sonarqube-scan-action@v7
-        if: env.SONAR_TOKEN != ''
+        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
         env:
           SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
       - uses: SonarSource/sonarqube-quality-gate-action@v1
-        if: env.SONAR_TOKEN != ''
+        if: ${{ !cancelled() && env.SONAR_TOKEN != '' }}
         timeout-minutes: 10
         env:
           SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}