@starci/hfs 3.0.0 → 4.0.1

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

@@ -1,9 +1,7 @@
-// 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
+// contract.mjs - HFS_CONTRACT_SNAPSHOT_DRIFT (R23): the back end commits its contract.
+//   a be side 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`. The fe side of the same app reads those snapshots where they are (`be/contracts/`, the one
+//   cross-side read of hfs.json sides.fe.reads) for its codegen: there is no copy to keep equal.
 // 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
@@ -17,7 +15,6 @@ 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. */
@@ -25,42 +22,18 @@ 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 }) {
+/** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
+export function contractFindings({ files, repo, resolver }) {
   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 }));
+  if (repo.profile !== 'be') return findings;
+  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 sides.be.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 sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
   }
   return findings;
 }

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

@@ -4,7 +4,9 @@
 //   - 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>`.
+//     `node_modules/<a>/node_modules/<name>` or `apps/<app>/node_modules/<name>` next to the hoisted `node_modules/<name>`. A
+//     bundled copy (`inBundle`: it ships inside its parent's tarball, its bundleDependencies) is not one: no range, override or
+//     dedupe of the workspace can move it, so it is the parent's, not a second copy the workspace keeps.
 import { found, readJson } from './read.mjs';
 
 export const DEP_VERSION_SKEW = 'HFS_DEP_VERSION_SKEW';
@@ -54,7 +56,7 @@ export function depFindings({ repoRoot, files }) {
     }
     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;
+      if (!nested || entry.link || entry.inBundle || 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 }));
     }

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

@@ -1,12 +1,13 @@
-// frontend.mjs - the front-end tree checks of hfs check, per app (`apps/<app>`, kind next):
-//   FE_WIRE_GENERATED (R52)     wire types come from the contract copy: an app that keeps `modules/api/contract/*` declares the
-//                               `codegen` script and runs it before `build` and `typecheck` (prebuild, pretypecheck), and its
-//                               generated types on disk (`modules/api/__generated__/`, never tracked) are not older than the copy
-//   FE_I18N_PLACEMENT (R59)     next-intl with the `[locale]` segment: `next-intl` is a dependency (of the app, the root or the shared
-//                               i18n package under `packages/`), every route file sits under
-//                               `src/app/[locale]/` (the root redirect page, global-error and health probes excepted), locale
-//                               routing is `src/proxy.ts` and never `middleware.ts`, and the default locale's catalog `vi.json` exists
+// frontend.mjs - the front-end tree checks of hfs check. Per app of the fe side (`apps/<app>`, kind next, side-relative paths):
+//   FE_I18N_PLACEMENT (R59)     next-intl with the `[locale]` segment: every route file sits under `src/app/[locale]/` (the root
+//                               redirect page, global-error and health probes excepted), locale routing is `src/proxy.ts` and never
+//                               `middleware.ts`, and the default locale's catalog `vi.json` exists
 //   FE_I18N_CATALOG (R60)       every `modules/i18n/messages/<locale>.json` has the same key set
+// Over the whole app (the root scope, app-relative paths: the one package.json and the be contract snapshots sit outside the fe side):
+//   FE_WIRE_GENERATED (R52)     wire types come from the be contract snapshots the fe side reads in place (its declared reads,
+//                               `be/contracts/`): the root package.json declares the `codegen` script, and each fe app's generated
+//                               types on disk (`modules/api/__generated__/`, never tracked) are not older than any snapshot
+//   FE_I18N_PLACEMENT (R59)     `next-intl` is a dependency of the root package.json or of a shared i18n package under fe/packages/
 // The files each app must hold (routing.ts, navigation.ts, request.ts, messages/, the [locale] layout) are the slot manifest's requires
 // (HFS_SLOT_REQUIRED_MISSING); which source may hold display text and how copy resolves is eslint-fe's.
 import fs from 'node:fs';
@@ -46,42 +47,35 @@ function newestBelow(dir) {
 
 const scriptsOf = (repoRoot, file) => readJson(repoRoot, file)?.scripts ?? {};
 
-function wireFindings({ repoRoot, app, tracked }) {
-  const base = `apps/${app}`;
-  const copies = tracked.filter((file) => file.startsWith(`${base}/src/modules/api/contract/`));
-  if (!copies.length) return [];
+/** R52 over the app: the codegen script of the root and the age of each fe app's generated types against the be snapshots. */
+function wireFindings({ repoRoot, files, apps, reads }) {
+  const snapshots = files.filter((file) => reads.some((read) => file.startsWith(read)));
+  if (!snapshots.length) return [];
   const findings = [];
-  const manifest = `${base}/package.json`;
-  const scripts = scriptsOf(repoRoot, manifest);
-  const rootScripts = scriptsOf(repoRoot, 'package.json');
-  // A root script that only fans out to the workspaces (`npm run x --workspaces`, the managed FE root) is not this app's
-  // script: the app's own manifest must declare it.
-  const delegates = (script) => /(?:^|\s)--workspaces?(?:\s|=|$)/.test(String(script ?? ''));
-  const wired = (name) => scripts[name] ?? (delegates(rootScripts[name]) ? undefined : rootScripts[name]);
-  if (typeof wired('codegen') !== 'string') findings.push(found(WIRE_GENERATED, manifest, `${app} keeps a contract copy but declares no \`codegen\` script; wire types are generated from the copy, never typed by hand`, { app }));
-  else for (const hook of ['prebuild', 'pretypecheck']) {
-    if (!/\bcodegen\b/.test(String(wired(hook) ?? ''))) findings.push(found(WIRE_GENERATED, manifest, `${app} does not run codegen in \`${hook}\`; generate the wire types before build and typecheck`, { app, script: hook }));
-  }
-  const generated = `${base}/src/modules/api/__generated__`;
-  const built = newestBelow(path.join(repoRoot, generated));
-  if (built !== null) {
-    for (const copy of copies) {
+  if (typeof scriptsOf(repoRoot, 'package.json').codegen !== 'string') findings.push(found(WIRE_GENERATED, 'package.json', `the app keeps contract snapshots (${reads.join(', ')}) but its package.json declares no \`codegen\` script; wire types are generated from the snapshots, never typed by hand`));
+  for (const app of apps) {
+    const generated = `fe/apps/${app}/src/modules/api/__generated__`;
+    const built = newestBelow(path.join(repoRoot, generated));
+    if (built === null) continue;
+    for (const snapshot of snapshots) {
       let changed;
-      try { changed = fs.statSync(path.join(repoRoot, copy)).mtimeMs; } catch { continue; }
-      if (built + STALE_MS < changed) findings.push(found(WIRE_GENERATED, generated, `${generated} is older than ${copy}; run \`npm run codegen\` so the wire types match the contract copy`, { app, copy }));
+      try { changed = fs.statSync(path.join(repoRoot, snapshot)).mtimeMs; } catch { continue; }
+      if (built + STALE_MS < changed) findings.push(found(WIRE_GENERATED, generated, `${generated} is older than ${snapshot}; run \`npm run codegen\` so the wire types match the contract snapshot`, { app, snapshot }));
     }
   }
   return findings;
 }
 
+/** R59 over the app: next-intl is a dependency of the one package.json or of a shared fe/packages/* manifest. */
+function intlDependencyFindings({ repoRoot, files }) {
+  const declares = (file) => { const pkg = readJson(repoRoot, file); return pkg ? ['dependencies', 'devDependencies'].some((section) => pkg[section]?.['next-intl'] !== undefined) : false; };
+  const shared = files.filter((file) => /^fe\/packages\/[^/]+\/package\.json$/.test(file));
+  return ['package.json', ...shared].some(declares) ? [] : [found(I18N_PLACEMENT, 'package.json', 'the app does not depend on next-intl (nor does a shared fe package); every fe app uses next-intl with the [locale] segment')];
+}
+
 function placementFindings({ repoRoot, app, tracked }) {
   const base = `apps/${app}`;
   const findings = [];
-  const declares = (file) => { const pkg = readJson(repoRoot, file); return pkg ? ['dependencies', 'devDependencies'].some((section) => pkg[section]?.['next-intl'] !== undefined) : false; };
-  const manifest = `${base}/package.json`;
-  // The next-intl stack is written once per repository: in the app, or in the shared `packages/<family>-i18n` the apps call.
-  const shared = tracked.filter((file) => /^packages\/[^/]+\/package\.json$/.test(file));
-  if (tracked.includes(manifest) && ![manifest, 'package.json', ...shared].some(declares)) findings.push(found(I18N_PLACEMENT, manifest, `${app} does not depend on next-intl (nor does the root or a shared package); every app uses next-intl with the [locale] segment`, { app }));
   if (!tracked.includes(`${base}/src/proxy.ts`)) findings.push(found(I18N_PLACEMENT, `${base}/src/proxy.ts`, `${app} has no src/proxy.ts; locale routing lives in proxy.ts`, { app }));
   for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware\.[cm]?[jt]s$`).test(f))) findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
   const appDir = `${base}/src/app/`;
@@ -118,7 +112,14 @@ function catalogFindings({ repoRoot, app, tracked }) {
   return findings;
 }
 
-/** The front-end tree findings of R52, R59 and R60 for every `next` app of the repository. */
+/** The fe side's tree findings of R59 and R60 for every `next` app; `repoRoot` is the fe side folder, `files` side-relative. */
 export function frontendFindings({ repoRoot, files, repo }) {
-  return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [wireFindings, placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
+  return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
+}
+
+/** The app's front-end findings that read the root (R52, R59's dependency); `repoRoot` is the app root, `files` app-relative. */
+export function appFrontendFindings({ repoRoot, files, repo }) {
+  const apps = repo.sides.fe.apps.filter((a) => a.kind === 'next').map((a) => a.name);
+  // The snapshots are the paths the fe side declares it reads of the be side (hfs.json sides.fe.reads: be/contracts/).
+  return [...wireFindings({ repoRoot, files, apps, reads: repo.sides.fe.reads }), ...intlDependencyFindings({ repoRoot, files })];
 }

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

@@ -0,0 +1,44 @@
+// peer-integrations.mjs - HFS_PEER_INTEGRATION_MISSING (R111): an app declares the runtime peer a driver integration needs.
+// The catalog knowledge/hfs/peer-integrations.yaml says "if the app depends on every package of `when` (at the named major,
+// when one is named), it must declare `requires`". npm does not install such a peer for the integration, the type checker and
+// the unit specs never load it, and the api fails only when it boots (@nestjs/apollo on @nestjs/platform-express 11, Express 5,
+// needs @as-integrations/express5). The app root package.json is the one manifest of both sides: a `when` package counts in its
+// dependencies or devDependencies, the peer counts only in its dependencies (a production install omits devDependencies).
+import fs from 'node:fs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { found, readJson } from './read.mjs';
+
+export const PEER_INTEGRATION_MISSING = 'HFS_PEER_INTEGRATION_MISSING';
+const MANIFEST = 'package.json';
+const CATALOG_FILE = new URL('../../../knowledge/hfs/peer-integrations.yaml', import.meta.url);
+
+/** The pairs of the catalog: [{ id, when: [{ package, major? }], requires, why }]. */
+export function peerIntegrationPairs() {
+  const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
+  if (catalog?.schema !== 'starci/hfs-peer-integrations@1' || !Array.isArray(catalog.pairs)) throw new Error('knowledge/hfs/peer-integrations.yaml is not a starci/hfs-peer-integrations@1 catalog');
+  return catalog.pairs;
+}
+
+/** The major a dependency spec allows (`11.2.5`, `^11.0.0`, `~11.1`, `>=11 <12`), or null when the spec names none (a tag, a link, `*`). */
+export function majorOf(spec) {
+  const match = /^\s*(?:[\^~]|>=?|=)?\s*v?(\d+)(?:\.|\s|$)/.exec(String(spec));
+  return match ? Number(match[1]) : null;
+}
+
+/** The findings of R111 over the app root package.json of `repoRoot`; `pairs` defaults to the catalog. */
+export function peerIntegrationFindings({ repoRoot, files, pairs = peerIntegrationPairs() }) {
+  if (!files.includes(MANIFEST)) return [];
+  const pkg = readJson(repoRoot, MANIFEST);
+  if (!pkg) return [];
+  const runtime = pkg.dependencies ?? {};
+  const declared = { ...(pkg.devDependencies ?? {}), ...runtime };
+  const findings = [];
+  for (const pair of pairs) {
+    const applies = pair.when.every((entry) => typeof declared[entry.package] === 'string' && (entry.major === undefined || majorOf(declared[entry.package]) === entry.major));
+    if (!applies || typeof runtime[pair.requires] === 'string') continue;
+    const because = pair.when.map((entry) => `${entry.package} ${declared[entry.package]}`).join(' with ');
+    const where = typeof declared[pair.requires] === 'string' ? ` (it is only a devDependency, which a production install omits)` : '';
+    findings.push(found(PEER_INTEGRATION_MISSING, MANIFEST, `${MANIFEST} depends on ${because} but does not declare ${pair.requires} in its dependencies${where}: ${pair.why.trim()} Add ${pair.requires} to the dependencies.`, { pair: pair.id, requires: pair.requires }));
+  }
+  return findings;
+}

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

@@ -4,13 +4,13 @@
 // keeps one goes quietly false (nivo-backend, 2026-09-30: `node --test scripts/provision-keycloak.spec.mjs` after the script was deleted).
 // Every argument of the command that is a repository-relative file path (an extension, no glob, no variable, not absolute, not a `..`
 // path into another repository) must be a tracked file or an existing one; a path an ignored slot owns (dist/, coverage/) is a build
-// product and is not judged. One finding per record, kind and missing path. A back end's `.starciwork` also holds the records of the
-// implementations that live in another repository (`repository: nivo-fe`); their commands run there, so only a record of this repository
-// (its `repository` names it, or names none) is judged.
+// product and is not judged. One finding per record, kind and missing path. The `.starciwork` of an app sits at the app root, and a
+// record names the side its implementation lives in (`repository: be` or `repository: fe`, the repositories of workspace.yaml, the
+// sides of hfs.json); a proof command runs from the app root, so every record of a side, or naming none, is judged against the app root.
+// A record naming a repository that is not a side of this app runs elsewhere and is not judged.
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseYaml } from '../../../engine/yaml.mjs';
-import { repositoryName } from '../repo-identity.mjs';
 import { found, readText } from './read.mjs';
 
 export const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
@@ -39,18 +39,21 @@ function proofCommands(record) {
   return Object.entries(demands).flatMap(([kind, demand]) => (typeof demand?.command === 'string' ? [{ kind, command: demand.command }] : []));
 }
 
-/** The findings of R105 over the tracked paths `files` of the repository at `repoRoot`; `resolver` names the ignored slots. */
-export function proofCommandFindings({ repoRoot, files, resolver }) {
+/**
+ * The findings of R105 over the tracked paths `files` of the app at `repoRoot`; `resolver` names the ignored slots and `sides` the side
+ * names of hfs.json (be, fe), the repositories a record of this app names.
+ */
+export function proofCommandFindings({ repoRoot, files, resolver, sides }) {
   const findings = [];
   const tracked = new Set(files);
-  const own = repositoryName(repoRoot);
+  const own = new Set(sides);
   for (const file of files) {
     if (!RECORD.test(file)) continue;
     const text = readText(repoRoot, file);
     if (text === null || !text.includes('requiresProof')) continue;
     let record;
     try { record = parseYaml(text); } catch { continue; }
-    if (typeof record?.repository === 'string' && record.repository !== own) continue;
+    if (typeof record?.repository === 'string' && !own.has(record.repository)) continue;
     for (const { kind, command } of proofCommands(record)) {
       for (const target of commandFiles(command)) {
         if (tracked.has(target) || fs.existsSync(path.join(repoRoot, target))) continue;