@starci/hfs 4.0.7 → 4.0.9

package/runtime/scripts/hfs/rules/docker.mjs

@@ -0,0 +1,259 @@
+// docker.mjs - every app builds its own image: be/apps/<app>/Dockerfile and fe/apps/<app>/Dockerfile (slot repo.app-image, required per declared
+// app; a Dockerfile anywhere else is owned by no slot) built from the APP ROOT, which holds the one package.json and the managed .dockerignore.
+// The Dockerfile is app-owned (starci app scaffold writes it once from templates/<side>/image) and judged here, structurally, from its parsed
+// instructions (scripts/lib/dockerfile.mjs), never by matching the text:
+//   HFS_DOCKER_BUILD_CONTEXT  the header comment states the app's own build command (`docker build -f <side>/apps/<app>/Dockerfile ... .`, the
+//                             context the app root) and no COPY or ADD source leaves the context (`..`, an absolute path)
+//   HFS_DOCKER_STAGES         a `build` stage and a last `runtime` stage; the runtime is unprivileged (`USER node`) and runs no build; every install
+//                             is `npm ci` (never `npm install`); a back-end runtime installs `--omit=dev --ignore-scripts`, a front-end runtime installs nothing
+//   HFS_DOCKER_ENTRY          the runtime starts the app's own built entry (be: node be/dist/apps/<app>/src/main.js; fe: node fe/apps/<app>/server.js); an api or
+//                             next app EXPOSEs the PORT it serves and carries a HEALTHCHECK, a worker carries a process HEALTHCHECK, the cli app
+//                             says `HEALTHCHECK NONE` and exposes nothing; a Next app builds `output: "standalone"` and its build runs turbo for its own workspace
+//   HFS_DOCKER_BASE_PIN       every FROM is a prior stage, the one node base image of the canon, or an image pinned by digest; never a moving tag
+//   HFS_DOCKER_SECRETS        no secret enters an image: no COPY or ADD of an .env file or of .starcistacks, .secrets, a key or a certificate, no ADD of a
+//                             URL, no ARG or ENV whose name is a credential (NEXT_PUBLIC_* are published by design and are the one exception)
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { propertyText } from '../../lib/ts-ast.mjs';
+import { execForm, parseDockerfile, shellCommands, words } from '../../lib/dockerfile.mjs';
+import { found, readText } from './read.mjs';
+
+const DOCKER_BUILD_CONTEXT = 'HFS_DOCKER_BUILD_CONTEXT';
+const DOCKER_STAGES = 'HFS_DOCKER_STAGES';
+const DOCKER_ENTRY = 'HFS_DOCKER_ENTRY';
+const DOCKER_BASE_PIN = 'HFS_DOCKER_BASE_PIN';
+const DOCKER_SECRETS = 'HFS_DOCKER_SECRETS';
+
+/** The one node base image of every Dockerfile of the canon: an exact node version on an exact alpine release. */
+export const NODE_IMAGE = 'node:22.14.0-alpine3.21';
+/** The two stages every Dockerfile has: the build, then the runtime that ships. */
+const BUILD_STAGE = 'build';
+const RUNTIME_STAGE = 'runtime';
+/** The port a listening app serves unless its environment says otherwise (ENV PORT of the runtime stage). */
+export const DEFAULT_PORT = '3000';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const BE_KINDS_WITH_LISTENER = new Set(['api']);
+const BE_KINDS_ONE_SHOT = new Set(['cli']);
+const CREDENTIAL_PARTS = new Set(['PASSWORD', 'PASSWD', 'SECRET', 'SECRETS', 'TOKEN', 'TOKENS', 'KEY', 'KEYS', 'CREDENTIAL', 'CREDENTIALS', 'PRIVATE']);
+const SECRET_FOLDERS = new Set(['.starcistacks', '.secrets', '.volume', '.git', '.ssh', '.aws']);
+const SECRET_SUFFIXES = ['.key', '.pem', '.p12', '.pfx', '.crt'];
+const BUILD_TOOLS = new Set(['tsc', 'tsc-alias', 'next', 'turbo', 'nest', 'webpack', 'vite', 'esbuild']);
+const DIGEST = /@sha256:[0-9a-f]{64}$/;
+
+/** The path of the Dockerfile of a be or fe app, app-relative. */
+export const dockerfilePath = (side, app) => `${side}/apps/${app}/Dockerfile`;
+/** The entry a built be app starts (from the app root). */
+const beEntry = (app) => `be/dist/apps/${app}/src/main.js`;
+/** The entry a Next standalone fe app starts (from the app root: the standalone tree keeps the workspace layout). */
+const feEntry = (app) => `fe/apps/${app}/server.js`;
+
+const instructionsOf = (stage, keyword) => stage.instructions.filter((item) => item.keyword === keyword);
+/** The commands a stage's RUN instructions run, each as its words (shell form; an exec-form RUN is one command). */
+function commandsOf(stage) {
+  return instructionsOf(stage, 'RUN').flatMap((run) => {
+    const exec = execForm(run.text);
+    if (exec) return [{ words: exec, line: run.line }];
+    return shellCommands(run.text.replace(/^(?:--\S+\s+)+/, '')).map((parts) => ({ words: parts, line: run.line }));
+  });
+}
+/** `npm ci`, `npm install`, `npm run <script>`, ... as { tool, verb, args }. */
+const npmCall = (parts) => (parts[0] === 'npm' ? { verb: parts[1] ?? '', args: parts.slice(2) } : null);
+const isBuildCommand = (parts) => {
+  const call = npmCall(parts);
+  if (call) return call.verb === 'run' && String(call.args[0] ?? '').startsWith('build');
+  const tool = parts[0] === 'npx' ? parts[1] : parts[0];
+  return BUILD_TOOLS.has(tool);
+};
+
+/** The environment `ENV` instructions of a stage set: name -> value (both `ENV A=1 B=2` and `ENV A 1`). */
+function envOf(stage) {
+  const env = new Map();
+  for (const item of instructionsOf(stage, 'ENV')) {
+    const parts = words(item.text);
+    if (parts.length >= 2 && !parts[0].includes('=')) { env.set(parts[0], parts.slice(1).join(' ')); continue; }
+    for (const part of parts) { const at = part.indexOf('='); if (at > 0) env.set(part.slice(0, at), part.slice(at + 1)); }
+  }
+  return env;
+}
+
+/** R187: the header states this app's build command, and the build never reaches outside its context. */
+function contextFindings(file, parsed, side, app) {
+  const findings = [];
+  const wanted = dockerfilePath(side, app);
+  const named = parsed.comments.some((comment) => {
+    const parts = words(comment.text);
+    const build = parts.findIndex((part, index) => part === 'docker' && parts[index + 1] === 'build');
+    if (build < 0) return false;
+    const flag = parts.indexOf('-f', build);
+    return flag > 0 && parts[flag + 1] === wanted && parts.at(-1) === '.';
+  });
+  if (!named) findings.push(found(DOCKER_BUILD_CONTEXT, file, `${file} does not state its build command in a header comment: \`docker build -f ${wanted} -t <image> .\` (the context is the app root, the folder with the one package.json and lockfile).`, { expected: wanted }));
+  for (const item of parsed.instructions.filter((entry) => entry.keyword === 'COPY' || entry.keyword === 'ADD')) {
+    const parts = words(item.text).filter((part) => !part.startsWith('--'));
+    const sources = parts.slice(0, -1);
+    const fromStage = words(item.text).some((part) => part.startsWith('--from='));
+    if (fromStage) continue;
+    for (const source of sources) {
+      if (/^[a-z]+:\/\//i.test(source)) continue;
+      const segments = source.split('/');
+      if (source.startsWith('/') || segments.includes('..')) findings.push(found(DOCKER_BUILD_CONTEXT, file, `${file}:${item.line} ${item.keyword} source ${source} leaves the build context; every source is a path inside the app root.`, { line: item.line, source }));
+    }
+  }
+  return findings;
+}
+
+/** R188: the stages and the install, the user and the build discipline of each. */
+function stageFindings(file, parsed, side, kind) {
+  const findings = [];
+  const { stages } = parsed;
+  const names = stages.map((stage) => stage.name);
+  if (!names.includes(BUILD_STAGE) || stages.at(-1)?.name !== RUNTIME_STAGE || stages.length < 2) {
+    findings.push(found(DOCKER_STAGES, file, `${file} has stages ${JSON.stringify(names)}; an image is multi-stage: a stage named ${BUILD_STAGE} (installs and builds) and a last stage named ${RUNTIME_STAGE} (what ships).`, { stages: names }));
+    if (!stages.length) return findings;
+  }
+  for (const stage of stages) {
+    for (const command of commandsOf(stage)) {
+      const call = npmCall(command.words);
+      if (call && (call.verb === 'install' || call.verb === 'i') && !call.args.some((arg) => arg === '-g' || arg === '--global')) findings.push(found(DOCKER_STAGES, file, `${file}:${command.line} runs \`npm ${call.verb}\`; an image installs with \`npm ci\` from the lockfile.`, { line: command.line }));
+    }
+  }
+  const runtime = stages.at(-1);
+  if (runtime.name !== RUNTIME_STAGE) return findings;
+  for (const command of commandsOf(runtime)) {
+    if (isBuildCommand(command.words)) findings.push(found(DOCKER_STAGES, file, `${file}:${command.line} the ${RUNTIME_STAGE} stage runs the build (\`${command.words.join(' ')}\`); it only receives what the ${BUILD_STAGE} stage built.`, { line: command.line }));
+  }
+  const users = instructionsOf(runtime, 'USER').map((item) => words(item.text)[0]);
+  if (!users.length || users.at(-1) !== 'node') findings.push(found(DOCKER_STAGES, file, `${file} ${RUNTIME_STAGE} stage does not end as \`USER node\` (found ${JSON.stringify(users.at(-1) ?? 'root')}); the process runs unprivileged.`, { user: users.at(-1) ?? 'root' }));
+  const installs = commandsOf(runtime).map((command) => ({ call: npmCall(command.words), line: command.line })).filter((entry) => entry.call?.verb === 'ci');
+  if (side === 'fe' && installs.length) findings.push(found(DOCKER_STAGES, file, `${file}:${installs[0].line} the ${RUNTIME_STAGE} stage of a Next app installs nothing: it copies the standalone output, which carries its own dependencies.`, { line: installs[0].line }));
+  if (side === 'be' && !installs.some((entry) => entry.call.args.includes('--omit=dev') && entry.call.args.includes('--ignore-scripts'))) findings.push(found(DOCKER_STAGES, file, `${file} ${RUNTIME_STAGE} stage does not run \`npm ci --omit=dev --ignore-scripts\`; a back-end runtime holds production dependencies only and runs no lifecycle script.`, { kind }));
+  return findings;
+}
+
+/** The Next config's `output` property, read with TypeScript's parser: the string literal assigned to `output` in an object literal. */
+function nextOutput(ts, text) {
+  return propertyText(ts, text, { file: 'next.config.ts', key: 'output' });
+}
+
+/** R189: the entry, the port and the health of the runtime. */
+function entryFindings({ repoRoot, file, parsed, side, app, kind, project, ts }) {
+  const findings = [];
+  const runtime = parsed.stages.at(-1);
+  if (!runtime || runtime.name !== RUNTIME_STAGE) return findings;
+  const entry = side === 'be' ? beEntry(app) : feEntry(app);
+  const starts = [...instructionsOf(runtime, 'ENTRYPOINT'), ...instructionsOf(runtime, 'CMD')].map((item) => execForm(item.text));
+  if (!starts.some((exec) => exec && exec[0] === 'node' && exec[1] === entry)) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage does not start \`["node", "${entry}"]\` in exec form (CMD or ENTRYPOINT); the app runs its own built entry.`, { expected: entry }));
+  const exposes = instructionsOf(runtime, 'EXPOSE').flatMap((item) => words(item.text).map((port) => port.replace(/\/(tcp|udp)$/i, '')));
+  const health = instructionsOf(runtime, 'HEALTHCHECK').map((item) => words(item.text));
+  const none = health.some((parts) => parts[0]?.toUpperCase() === 'NONE');
+  const listens = side === 'fe' || BE_KINDS_WITH_LISTENER.has(kind);
+  if (listens) {
+    const port = envOf(runtime).get('PORT');
+    if (!port || !exposes.includes(port)) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage must set \`ENV PORT=<port>\` and \`EXPOSE\` the same port (found PORT ${JSON.stringify(port ?? null)}, EXPOSE ${JSON.stringify(exposes)}); a listening app declares the port it serves.`, { port: port ?? null, exposes }));
+    if (!health.length || none) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage has no HEALTHCHECK; an api or Next app answers a health probe the platform can run.`, {}));
+  } else if (BE_KINDS_ONE_SHOT.has(kind)) {
+    if (!none) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage must say \`HEALTHCHECK NONE\`; a ${kind} app is a one-shot command, not a service.`, { kind }));
+    if (exposes.length) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage EXPOSEs ${exposes.join(', ')}; a ${kind} app listens on nothing.`, { exposes }));
+  } else {
+    if (!health.length || none) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage has no process HEALTHCHECK; a ${kind} app serves nothing, so its healthcheck probes its process.`, { kind }));
+    if (exposes.length) findings.push(found(DOCKER_ENTRY, file, `${file} ${RUNTIME_STAGE} stage EXPOSEs ${exposes.join(', ')}; a ${kind} app listens on nothing.`, { exposes }));
+  }
+  if (side === 'fe') {
+    const build = parsed.stages.find((stage) => stage.name === BUILD_STAGE);
+    const filter = `--filter=@${project}/${app}`;
+    const builds = build && commandsOf(build).some((command) => command.words.includes('turbo') && command.words.includes('build') && command.words.includes(filter));
+    if (!builds) findings.push(found(DOCKER_ENTRY, file, `${file} ${BUILD_STAGE} stage does not run \`turbo run build ${filter}\`; a Next image builds its own workspace (and the packages it imports) through turbo.`, { expected: filter }));
+    const config = `fe/apps/${app}/next.config.ts`;
+    const text = readText(repoRoot, config);
+    if (text !== null && ts && nextOutput(ts, text) !== 'standalone') findings.push(found(DOCKER_ENTRY, config, `${config} does not set \`output: "standalone"\`; the runtime stage of ${file} ships the standalone output.`, { expected: 'standalone' }));
+  }
+  return findings;
+}
+
+/** The image reference of a FROM with its build arguments resolved against the ARG defaults before the first FROM; null when one cannot be. */
+function resolvedImage(parsed, image) {
+  const defaults = new Map();
+  for (const item of parsed.preamble.filter((entry) => entry.keyword === 'ARG')) {
+    const [name, ...rest] = words(item.text)[0]?.split('=') ?? [];
+    if (name && rest.length) defaults.set(name, rest.join('='));
+  }
+  let unresolved = false;
+  const text = image.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (whole, braced, bare) => {
+    const value = defaults.get(braced ?? bare);
+    if (value === undefined) unresolved = true;
+    return value ?? whole;
+  });
+  return unresolved ? null : text;
+}
+
+/** R190: every FROM is a prior stage, the canon node image, or an image pinned by digest. */
+function pinFindings(file, parsed) {
+  const findings = [];
+  const earlier = new Set();
+  for (const stage of parsed.stages) {
+    const image = resolvedImage(parsed, stage.image);
+    const ok = image !== null && (earlier.has(image) || image === NODE_IMAGE || DIGEST.test(image));
+    if (!ok) findings.push(found(DOCKER_BASE_PIN, file, `${file}:${stage.line} stage ${stage.name ?? stage.index} starts FROM ${stage.image}; the base is ${NODE_IMAGE} (the one node image of the canon), a prior stage, or an image pinned by @sha256 digest. A moving tag changes the image without a change of this file.`, { line: stage.line, image: stage.image, expected: NODE_IMAGE }));
+    if (stage.name) earlier.add(stage.name);
+  }
+  return findings;
+}
+
+const isCredentialName = (name) => !name.startsWith('NEXT_PUBLIC_') && name.split('_').some((part) => CREDENTIAL_PARTS.has(part.toUpperCase()));
+const isSecretPath = (source) => {
+  const segments = source.split('/').filter((part) => part && part !== '.');
+  const base = segments.at(-1) ?? '';
+  const env = base === '.env' || (base.startsWith('.env.') && base !== '.env.example');
+  return env || segments.some((segment) => SECRET_FOLDERS.has(segment)) || SECRET_SUFFIXES.some((suffix) => base.endsWith(suffix)) || base.startsWith('kubeconfig');
+};
+
+/** R191: no secret enters an image. */
+function secretFindings(file, parsed) {
+  const findings = [];
+  for (const item of parsed.instructions) {
+    if (item.keyword === 'COPY' || item.keyword === 'ADD') {
+      const parts = words(item.text);
+      if (parts.some((part) => part.startsWith('--from='))) continue;
+      const sources = parts.filter((part) => !part.startsWith('--')).slice(0, -1);
+      for (const source of sources) {
+        if (/^https?:\/\//i.test(source)) findings.push(found(DOCKER_SECRETS, file, `${file}:${item.line} ADD of a URL (${source}); a download is a checksum-verified stage, never an ADD.`, { line: item.line, source }));
+        else if (isSecretPath(source)) findings.push(found(DOCKER_SECRETS, file, `${file}:${item.line} ${item.keyword} of ${source}, which holds secret material; credentials are mounted at run time, never copied into an image.`, { line: item.line, source }));
+      }
+    } else if (item.keyword === 'ARG' || item.keyword === 'ENV') {
+      const parts = words(item.text);
+      const names = item.keyword === 'ENV' && parts.length >= 2 && !parts[0].includes('=') ? [parts[0]] : parts.map((part) => part.split('=')[0]);
+      for (const name of names) if (isCredentialName(name)) findings.push(found(DOCKER_SECRETS, file, `${file}:${item.line} ${item.keyword} ${name} names a credential; an image carries none (an ARG or ENV stays in the image history). Mount it at run time; only NEXT_PUBLIC_* values, which are published by design, are build arguments.`, { line: item.line, name }));
+    }
+  }
+  return findings;
+}
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+/** The findings of the docker rules over the tracked paths `files` (app-relative) of the app at `repoRoot`. */
+export function dockerFindings({ repoRoot, files, repo }) {
+  if (!repo?.sides) return [];
+  const tracked = new Set(files);
+  const apps = [
+    ...repo.sides.be.apps.map((entry) => ({ side: 'be', app: entry.name, kind: entry.kind })),
+    ...repo.sides.fe.apps.map((entry) => ({ side: 'fe', app: entry.name, kind: entry.kind })),
+  ];
+  const ts = apps.some((entry) => entry.side === 'fe') ? typescriptFor(repoRoot) : null;
+  return apps.flatMap(({ side, app, kind }) => {
+    const file = dockerfilePath(side, app);
+    if (!tracked.has(file)) return [];
+    const text = readText(repoRoot, file);
+    if (text === null) return [found(DOCKER_STAGES, file, `${file} is not readable text.`)];
+    const parsed = parseDockerfile(text);
+    return [
+      ...contextFindings(file, parsed, side, app),
+      ...stageFindings(file, parsed, side, kind),
+      ...entryFindings({ repoRoot, file, parsed, side, app, kind, project: repo.project, ts }),
+      ...pinFindings(file, parsed),
+      ...secretFindings(file, parsed),
+    ];
+  });
+}

package/runtime/scripts/hfs/rules/edition.mjs

@@ -0,0 +1,111 @@
+// edition.mjs - L01, the edition rule. An hfs.json edition is `full` or `lite` (absent means full); under lite the standard is a
+// filter plus a few additions over the same manifest, never a second engine. The slot layer already answers the paths lite
+// removed (slots lite excludes, or whose litePresence is forbidden, come back HFS_FORBIDDEN_PRESENT with their goesTo); this
+// rule reports what no path can state:
+//   - inside a package.json: a test script (`test`, `test:*`, `typecheck:tests`, a jest/vitest/playwright/mocha/cypress or
+//     `node --test` command) or a jest/vitest/playwright dependency - the same vocabulary FE_NO_TESTS scans on the fe side;
+//   - a test-tool configuration file no more specific slot already forbids;
+//   - a declaration of what lite does not have: a worker app, an event pattern (event-bus, queue, fenced-job, projection,
+//     saga) or its trigger kinds (saga, reactors, jobs, realtime). The forbidden names are DERIVED - a pattern, trigger or
+//     app kind is gone under lite exactly when every slot that carries it is litePresence: forbidden - so adding or
+//     restoring a kind is a manifest edit, not an edit here.
+// The edition is never tested here: a full app's view forbids none of these names and keeps its tests, so the rule answers [].
+import { found, readJson } from './read.mjs';
+import { DEPENDENCY_SECTIONS, TEST_DEPENDENCY, TEST_RUNNER_COMMAND, TEST_SCRIPT_NAME, TEST_TOOL_FILE } from './fe-no-tests.mjs';
+
+export const HFS_EDITION_FORBIDDEN_PRESENT = 'HFS_EDITION_FORBIDDEN_PRESENT';
+
+const PACKAGE_JSON = /(?:^|\/)package\.json$/;
+const TYPECHECK_TESTS = /^(?:pre|post)?typecheck:tests$/;
+
+/**
+ * The names the edition cannot declare: for each of `pattern`, `trigger` and `appKind`, the value is gone when every slot of
+ * the resolver's view that carries it is forbidden there. The view is the edition's own (full forbids none of them), so the
+ * rule needs no edition test: a full app has nothing gone.
+ */
+function editionGone(resolver) {
+  const tally = new Map();
+  for (const slot of resolver.slots()) {
+    const forbidden = slot.presence === 'forbidden';
+    for (const field of ['pattern', 'trigger', 'appKind']) {
+      if (slot[field] === undefined) continue;
+      const key = `${field}:${slot[field]}`;
+      const entry = tally.get(key) ?? { total: 0, forbidden: 0 };
+      entry.total += 1;
+      entry.forbidden += forbidden ? 1 : 0;
+      tally.set(key, entry);
+    }
+  }
+  const gone = { pattern: new Set(), trigger: new Set(), appKind: new Set() };
+  for (const [key, entry] of tally) {
+    if (entry.total !== entry.forbidden) continue;
+    const [field, name] = key.split(':');
+    gone[field].add(name);
+  }
+  return gone;
+}
+
+/** The findings one package.json's scripts and dependencies produce under lite. */
+function packageFindings(repoRoot, rel) {
+  const pkg = readJson(repoRoot, rel);
+  if (pkg === null || typeof pkg !== 'object' || Array.isArray(pkg)) return [];
+  const findings = [];
+  const scripts = typeof pkg.scripts === 'object' && pkg.scripts !== null && !Array.isArray(pkg.scripts) ? pkg.scripts : {};
+  for (const [name, command] of Object.entries(scripts)) {
+    if (TEST_SCRIPT_NAME.test(name) || TYPECHECK_TESTS.test(name) || TEST_RUNNER_COMMAND.test(String(command))) {
+      findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} has script ${JSON.stringify(name)}: the lite edition has no tests - a lite app does not typecheck or run a test world`, { name }));
+    }
+  }
+  for (const section of DEPENDENCY_SECTIONS) {
+    const deps = pkg[section];
+    if (typeof deps !== 'object' || deps === null || Array.isArray(deps)) continue;
+    for (const name of Object.keys(deps)) {
+      if (TEST_DEPENDENCY.test(name)) {
+        findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, rel, `${rel} ${section} has ${name}: the lite edition has no tests - the dependency belongs to the full edition`, { section, name }));
+      }
+    }
+  }
+  return findings;
+}
+
+/** The findings one be-side declaration produces under lite: a worker app, an event pattern or a gone trigger kind. */
+function declarationFindings(repo, gone) {
+  const findings = [];
+  for (const app of repo.apps ?? []) {
+    if (gone.appKind.has(app.kind)) {
+      findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, 'hfs.json', `hfs.json declares the ${app.kind} app ${app.name}: a ${app.kind} belongs to the full edition, a lite app has none`, { app: app.name, kind: app.kind }));
+    }
+  }
+  for (const [field, goneNames] of [['pattern', gone.pattern], ['trigger', gone.trigger]]) {
+    const declared = field === 'pattern' ? (repo.patterns ?? []) : (repo.kinds ?? []);
+    for (const name of declared) {
+      if (goneNames.has(name)) {
+        findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, 'hfs.json', `hfs.json ${field === 'pattern' ? 'declares' : 'names'} the ${name} ${field}: ${name} belongs to the full edition, a lite app has none`, { name }));
+      }
+    }
+  }
+  return findings;
+}
+
+/**
+ * L01 for one scope (the app root or one side), over `files` (scope-relative). Both questions are answered by the
+ * resolver's view of the edition: the names gone from it, and whether any slot of it still has tests. The declaration
+ * findings are judged from the be side (its apps, patterns and kinds): the root scope looks at sides.be, a standalone
+ * be-side check at its own view. `withDeclaration: false` (a side scope of a whole-app check) skips them: the root scope
+ * already reported them on hfs.json, and the side scope would only repeat them on a path that is not this side's.
+ */
+export function editionFindings({ repoRoot, files, repo, resolver, withDeclaration = true }) {
+  const gone = editionGone(resolver);
+  const noTestWorld = resolver.slots().every((slot) => slot.tests === 'none');
+  const beView = !withDeclaration ? null : (repo.profile === 'app' ? repo.sides?.be : (repo.profile === 'be' ? repo : null));
+  const findings = beView ? declarationFindings(beView, gone) : [];
+  for (const file of noTestWorld ? files : []) {
+    if (file.includes('node_modules/')) continue;
+    if (PACKAGE_JSON.test(file)) {
+      findings.push(...packageFindings(repoRoot, file));
+    } else if (TEST_TOOL_FILE.test(file) && resolver.classifyPath(file).status !== 'forbidden') {
+      findings.push(found(HFS_EDITION_FORBIDDEN_PRESENT, file, `${file} is test tooling: the lite edition has no tests - the file belongs to the full edition`));
+    }
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/event-bus.mjs

@@ -0,0 +1,153 @@
+// event-bus.mjs - the tree checks of the declared patterns (hfs.json sides.be.patterns).
+//   BE_EVENT_CLASS_CONTRACT   every typed event class `be/src/modules/events/<service>/<event>.event.ts` equals an entry of the vendored
+//                             contract `be/contracts/<service>/events.json` (the same name and version), every entry of a vendored
+//                             contract has its class, and a class file is named after its event (`order.placed` -> `order-placed.event.ts`);
+//   BE_PATTERN_SPEC_MISSING   a declared pattern has its required scenarios: ruleParams.be.patternScenarios.<pattern> lists scenario ids,
+//                             and an e2e or integration spec of the back end holds a test whose title starts `<pattern>/<scenario>:`.
+// Class members are read with TypeScript's own parser (a `static readonly eventName` and `version` with literal initializers), spec
+// titles are the first argument of `it(` and `test(` calls; no source text is matched by a regular expression.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadSlotManifest, ruleParams } from '../slots.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { literalText } from '../../lib/ts-ast.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const EVENT_CLASS_CONTRACT = 'BE_EVENT_CLASS_CONTRACT';
+const PATTERN_SPEC_MISSING = 'BE_PATTERN_SPEC_MISSING';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const EVENT_FILE_PREFIX = 'be/src/modules/events/';
+const EVENT_SUFFIX = '.event.ts';
+const CONTRACT_PREFIX = 'be/contracts/';
+const CONTRACT_NAME = 'events.json';
+const TEST_FOLDERS = ['be/src/tests/e2e/', 'be/src/tests/integration/'];
+const SPEC_SUFFIXES = ['.e2e-spec.ts', '.integration-spec.ts'];
+const TEST_CALLEES = new Set(['it', 'test']);
+
+/** The TypeScript compiler of the app (else of the runtime), or null. */
+const typescriptFor = (repoRoot) => loadTypescript(repoRoot, HERE);
+
+/** The event-bus pattern file name of an event name: dots become dashes (`order.placed` -> `order-placed`). */
+export const stemOfEvent = (name) => name.split('.').join('-');
+
+/** The `eventName` and `version` literals a class declares as `static readonly` members, with the line of the class. */
+function readEventClass(ts, text, file) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const classes = [];
+  const visit = (node) => {
+    if (ts.isClassDeclaration(node)) {
+      let name = null;
+      let version = null;
+      for (const member of node.members) {
+        if (!ts.isPropertyDeclaration(member) || !member.initializer || !member.name || !ts.isIdentifier(member.name)) continue;
+        const isStatic = member.modifiers?.some((m) => m.kind === ts.SyntaxKind.StaticKeyword);
+        if (!isStatic) continue;
+        let value = member.initializer;
+        while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+        if (member.name.text === 'eventName') name = literalText(ts, value);
+        if (member.name.text === 'version' && ts.isNumericLiteral(value)) version = Number(value.text);
+      }
+      if (name !== null || version !== null || node.name) classes.push({ className: node.name?.text ?? '<anonymous>', name, version });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return classes;
+}
+
+/** Findings of BE_EVENT_CLASS_CONTRACT. */
+export function eventClassContractFindings({ repoRoot, files, repo }) {
+  const patterns = repo.sides?.be?.patterns ?? [];
+  if (!patterns.includes('event-bus')) return [];
+  const ts = typescriptFor(repoRoot);
+  if (!ts) return [];
+  const findings = [];
+  const classesByService = new Map();
+  for (const file of files) {
+    if (!file.startsWith(EVENT_FILE_PREFIX) || !file.endsWith(EVENT_SUFFIX)) continue;
+    const rest = file.slice(EVENT_FILE_PREFIX.length).split('/');
+    if (rest.length !== 2) continue;
+    const [service, base] = rest;
+    const stem = base.slice(0, -EVENT_SUFFIX.length);
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    const classes = readEventClass(ts, text, file).filter((c) => c.name !== null || c.version !== null);
+    if (classes.length !== 1 || classes[0].name === null || classes[0].version === null) {
+      findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} must declare exactly one event class with literal \`static readonly eventName\` and \`static readonly version\` members (the typed event of be/contracts/${service}/${CONTRACT_NAME}); found ${classes.length === 1 ? 'one without both literals' : `${classes.length} candidates`}.`, { service }));
+      continue;
+    }
+    const [event] = classes;
+    if (stemOfEvent(event.name) !== stem) {
+      findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares the event \`${event.name}\`, so the file is \`${stemOfEvent(event.name)}${EVENT_SUFFIX}\`: a class file is named after its event.`, { service, event: event.name }));
+    }
+    if (!classesByService.has(service)) classesByService.set(service, new Map());
+    classesByService.get(service).set(event.name, { file, version: event.version });
+  }
+  const contracts = new Map();
+  for (const file of files) {
+    if (!file.startsWith(CONTRACT_PREFIX) || !file.endsWith(`/${CONTRACT_NAME}`)) continue;
+    const rest = file.slice(CONTRACT_PREFIX.length).split('/');
+    if (rest.length !== 2) continue;
+    contracts.set(rest[0], { file, doc: readJson(repoRoot, file) });
+  }
+  for (const [service, byName] of classesByService) {
+    const contract = contracts.get(service);
+    for (const [name, { file, version }] of byName) {
+      const entry = contract?.doc?.events?.[name];
+      if (!contract) findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares the event \`${name}\` but ${CONTRACT_PREFIX}${service}/${CONTRACT_NAME} is not tracked; every event class is an entry of the vendored contract of its service.`, { service, event: name }));
+      else if (entry === undefined) findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares the event \`${name}\` which ${contract.file} does not list; emit the contract (\`starci app emit\`) so the class and the contract agree.`, { service, event: name }));
+      else if (entry.version !== version) findings.push(found(EVENT_CLASS_CONTRACT, file, `${file} declares \`${name}\` at version ${version} but ${contract.file} lists version ${entry.version}; a version changes in the class and the contract together.`, { service, event: name }));
+    }
+  }
+  for (const [service, contract] of contracts) {
+    const events = contract.doc?.events;
+    if (events === null || typeof events !== 'object') continue;
+    for (const name of Object.keys(events)) {
+      if (!classesByService.get(service)?.has(name)) findings.push(found(EVENT_CLASS_CONTRACT, contract.file, `${contract.file} lists the event \`${name}\` but ${EVENT_FILE_PREFIX}${service}/${stemOfEvent(name)}${EVENT_SUFFIX} declares no such class; every contract entry has its typed event class.`, { service, event: name }));
+    }
+  }
+  return findings;
+}
+
+/** The scenario ids a back end proves: every `<pattern>/<scenario>:` test title of an e2e or integration spec. */
+function provenScenarios(ts, repoRoot, files) {
+  const proven = new Set();
+  for (const file of files) {
+    if (!TEST_FOLDERS.some((folder) => file.startsWith(folder)) || !SPEC_SUFFIXES.some((suffix) => file.endsWith(suffix))) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    const visit = (node) => {
+      if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && TEST_CALLEES.has(node.expression.text)) {
+        const title = literalText(ts, node.arguments[0]);
+        const colon = title === null ? -1 : title.indexOf(':');
+        if (colon > 0) proven.add(title.slice(0, colon));
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+  return proven;
+}
+
+let memoScenarios;
+/** ruleParams.be.patternScenarios of the slot manifest this runtime ships. */
+const scenariosTable = () => (memoScenarios ??= ruleParams(loadSlotManifest(), 'be').patternScenarios ?? {});
+
+/** Findings of BE_PATTERN_SPEC_MISSING: each declared pattern's required scenarios have a test. */
+export function patternSpecFindings({ repoRoot, files, repo, scenarios = scenariosTable() }) {
+  const patterns = (repo.sides?.be?.patterns ?? []).filter((name) => (scenarios[name] ?? []).length > 0);
+  if (patterns.length === 0) return [];
+  const ts = typescriptFor(repoRoot);
+  if (!ts) return [];
+  const proven = provenScenarios(ts, repoRoot, files);
+  const findings = [];
+  for (const pattern of patterns) {
+    for (const scenario of scenarios[pattern]) {
+      const id = `${pattern}/${scenario}`;
+      if (!proven.has(id)) findings.push(found(PATTERN_SPEC_MISSING, 'hfs.json', `The pattern \`${pattern}\` is declared but no e2e or integration spec (be/src/tests/e2e, be/src/tests/integration) holds a test titled \`${id}: ...\`; each scenario of a declared pattern is proven on the test world.`, { pattern, scenario: id }));
+    }
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/fe-contract-documents.mjs

@@ -0,0 +1,66 @@
+// fe-contract-documents.mjs - FE_GRAPHQL_CONTRACT (R113): every GraphQL document a front end sends is one its back end
+// serves. An app keeps the contract of each GraphQL service it runs as a snapshot, `be/contracts/<service>/schema.graphql`
+// (`starci app emit`, HFS_CONTRACT_SNAPSHOT_DRIFT keeps it current), and its front end keeps every operation it sends
+// in a `.graphql` file under `fe/`. Each operation is judged against the contract of the service that serves its first
+// root field (the one snapshot whose root type declares it): a root field no contract declares, a field, argument or input
+// field the contract does not declare, a required argument left out, a variable of another type, a leaf with a selection or
+// an object without one is a finding on the document. The finding names the service and every problem.
+import { operationProblems, parseDocument, parseSchema, rootFieldsOf } from '../../lib/graphql-contract.mjs';
+import { found, readText } from './read.mjs';
+
+export const FE_GRAPHQL_CONTRACT = 'FE_GRAPHQL_CONTRACT';
+
+const CONTRACT = /^be\/contracts\/([^/]+)\/schema\.graphql$/;
+const isDocument = (file) => file.startsWith('fe/') && file.endsWith('.graphql') && !file.includes('/__generated__/') && !file.includes('/node_modules/');
+
+/** The parsed contracts of the app: [{ service, path, schema }], or a finding for a snapshot that does not parse. */
+function contractsOf(repoRoot, files, findings) {
+  const contracts = [];
+  for (const file of files) {
+    const match = CONTRACT.exec(file);
+    if (!match) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    try {
+      contracts.push({ service: match[1], path: file, schema: parseSchema(text) });
+    } catch (error) {
+      findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL schema the front-end documents can be judged against: ${error.message}. Run \`npm run contract:emit\`.`));
+    }
+  }
+  return contracts;
+}
+
+/** The findings of R113 over the tracked paths `files` of the app at `repoRoot`. */
+export function feContractFindings({ repoRoot, files }) {
+  const documents = files.filter(isDocument).sort();
+  if (documents.length === 0) return [];
+  const findings = [];
+  const contracts = contractsOf(repoRoot, files, findings);
+  for (const file of documents) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    let document;
+    try {
+      document = parseDocument(text);
+    } catch (error) {
+      findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`));
+      continue;
+    }
+    for (const operation of document.operations) {
+      const label = operation.name ?? `anonymous ${operation.operation}`;
+      const [first] = rootFieldsOf(operation);
+      const serving = contracts.filter(({ schema }) => schema.types.get(schema.roots[operation.operation])?.fields?.has(first));
+      if (serving.length === 0) {
+        const where = contracts.length === 0 ? 'the app keeps no be/contracts/<service>/schema.graphql' : `no contract of ${contracts.map((c) => c.path).join(', ')} declares ${operation.operation} ${first}`;
+        findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} asks ${operation.operation} ${first}, but ${where}; the front end sends only what a back end serves.`, { operation: label, service: null }));
+        continue;
+      }
+      const [contract] = serving;
+      const problems = operationProblems(contract.schema, document, operation);
+      if (problems.length > 0) {
+        findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}: ${label} does not match the ${contract.service} contract (${contract.path}): ${problems.join('; ')}.`, { operation: label, service: contract.service, problems }));
+      }
+    }
+  }
+  return findings;
+}

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

@@ -12,11 +12,12 @@ import { found, readJson } from './read.mjs';
 export const FE_NO_TESTS = 'FE_NO_TESTS';
 const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
 const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
-const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
-const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
-const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
-const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
-const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+export const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
+// The edition rule (rules/edition.mjs, L01) applies the same lists to the whole app tree in lite: they are the test vocabulary.
+export const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
+export const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
+export const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
+export const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
 
 /** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
 export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);