@starci/hfs 4.11.22 → 4.12.0

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

@@ -19,14 +19,12 @@ import { propertyText } from '../../lib/ts-ast.mjs';
 import { execForm, parseDockerfile, shellCommands, words } from '../../lib/dockerfile.mjs';
 import { found, readText } from './read.mjs';
 import { healthProbeReachesLive } from './docker-health.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';
 const DOCKER_HEALTHCHECK_FAKE = 'HFS_DOCKER_HEALTHCHECK_FAKE';
-
 /** 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. */
@@ -34,7 +32,6 @@ 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']);
@@ -43,282 +40,311 @@ const SECRET_FOLDERS = new Set(['.starcistacks', '.secrets', '.volume', '.git',
 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 }));
-  });
+    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);
+    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;
+    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;
 }
-
 /** Accept the app command or the equivalent explicit Dockerfile and root context. */
 const statesBuildCommand = (parsed, wanted, app) => 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;
-  if (parts[build - 1] === 'starci') return parts[build + 2] === app;
-  const flag = parts.indexOf('-f', build);
-  return flag > 0 && parts[flag + 1] === wanted && parts.at(-1) === '.';
+    const parts = words(comment.text);
+    const build = parts.findIndex((part, index) => part === 'docker' && parts[index + 1] === 'build');
+    if (build < 0)
+        return false;
+    if (parts[build - 1] === 'starci')
+        return parts[build + 2] === app;
+    const flag = parts.indexOf('-f', build);
+    return flag > 0 && parts[flag + 1] === wanted && parts.at(-1) === '.';
 });
-
 function copySourceFindings(file, item) {
-  const findings = [];
-  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) return findings;
-  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;
+    const findings = [];
+    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)
+        return findings;
+    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;
 }
-
 /** 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);
-  if (!statesBuildCommand(parsed, wanted, app)) findings.push(found(DOCKER_BUILD_CONTEXT, file, `${file} does not state its build command in a header comment: \`starci docker build ${app}\` or \`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')) findings.push(...copySourceFindings(file, item));
-  return findings;
+    const findings = [];
+    const wanted = dockerfilePath(side, app);
+    if (!statesBuildCommand(parsed, wanted, app))
+        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'))
+        findings.push(...copySourceFindings(file, item));
+    return findings;
 }
-
 /** R188: the stages and the install, the user and the build discipline of each. */
 function stageInstallFindings(file, stages) {
-  const 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')) 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 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'))
+                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 }));
+        }
     }
-  }
-  return findings;
+    return findings;
 }
-
 function runtimeStageFindings(file, runtime, side, kind) {
-  const 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;
+    const 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;
 }
-
 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;
-  }
-  findings.push(...stageInstallFindings(file, stages));
-  const runtime = stages.at(-1);
-  if (runtime.name !== RUNTIME_STAGE) return findings;
-  findings.push(...runtimeStageFindings(file, runtime, side, kind));
-  return findings;
+    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;
+    }
+    findings.push(...stageInstallFindings(file, stages));
+    const runtime = stages.at(-1);
+    if (runtime.name !== RUNTIME_STAGE)
+        return findings;
+    findings.push(...runtimeStageFindings(file, runtime, side, 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' });
+    return propertyText(ts, text, { file: 'next.config.ts', key: 'output' });
 }
-
 function listenerHealthFindings(file, runtime, exposes, health, none) {
-  const findings = [];
-  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.`, {}));
-  return findings;
+    const findings = [];
+    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.`, {}));
+    return findings;
 }
-
 function oneShotHealthFindings(file, kind, exposes, none) {
-  const findings = [];
-  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 }));
-  return findings;
+    const findings = [];
+    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 }));
+    return findings;
 }
-
 function processHealthFindings(file, kind, exposes, health, none) {
-  const findings = [];
-  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 }));
-  return findings;
+    const findings = [];
+    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 }));
+    return findings;
 }
-
 function entryHealthFindings(file, runtime, side, kind, exposes, health, none) {
-  if (side === 'fe' || BE_KINDS_WITH_LISTENER.has(kind)) return listenerHealthFindings(file, runtime, exposes, health, none);
-  if (BE_KINDS_ONE_SHOT.has(kind)) return oneShotHealthFindings(file, kind, exposes, none);
-  return processHealthFindings(file, kind, exposes, health, none);
+    if (side === 'fe' || BE_KINDS_WITH_LISTENER.has(kind))
+        return listenerHealthFindings(file, runtime, exposes, health, none);
+    if (BE_KINDS_ONE_SHOT.has(kind))
+        return oneShotHealthFindings(file, kind, exposes, none);
+    return processHealthFindings(file, kind, exposes, health, none);
 }
-
 /** R262 strengthens only API images: a constant success or an absent/local-unreachable live route is refused. */
 function healthReachabilityFindings({ repoRoot, file, parsed, side, app, kind, ts }) {
-  if (side !== 'be' || kind !== 'api' || !ts) return [];
-  const runtime = parsed.stages.at(-1);
-  if (runtime?.name !== RUNTIME_STAGE) return [];
-  const health = instructionsOf(runtime, 'HEALTHCHECK').at(-1);
-  if (!health || /^NONE\b/i.test(health.text)) return [];
-  const body = health.text.replace(/^(?:--\S+\s+)*CMD\s+/i, '');
-  const port = envOf(runtime).get('PORT') ?? DEFAULT_PORT;
-  if (healthProbeReachesLive({ repoRoot, app, ts, body, port })) return [];
-  return [found(DOCKER_HEALTHCHECK_FAKE, file, `${file}:${health.line} the API HEALTHCHECK must request its reachable /health/live route on the runtime's local port and fail when the probe fails; a constant-success command or a URL without a registered live route does not probe this app.`, { line: health.line })];
+    if (side !== 'be' || kind !== 'api' || !ts)
+        return [];
+    const runtime = parsed.stages.at(-1);
+    if (runtime?.name !== RUNTIME_STAGE)
+        return [];
+    const health = instructionsOf(runtime, 'HEALTHCHECK').at(-1);
+    if (!health || /^NONE\b/i.test(health.text))
+        return [];
+    const body = health.text.replace(/^(?:--\S+\s+)*CMD\s+/i, '');
+    const port = envOf(runtime).get('PORT') ?? DEFAULT_PORT;
+    if (healthProbeReachesLive({ repoRoot, app, ts, body, port }))
+        return [];
+    return [found(DOCKER_HEALTHCHECK_FAKE, file, `${file}:${health.line} the API HEALTHCHECK must request its reachable /health/live route on the runtime's local port and fail when the probe fails; a constant-success command or a URL without a registered live route does not probe this app.`, { line: health.line })];
 }
-
 function nextEntryFindings({ repoRoot, file, parsed, app, project, ts }) {
-  const findings = [];
-  const build = parsed.stages.find((stage) => stage.name === BUILD_STAGE);
-  const filter = `--filter=@${project}/${app}`;
-  const builds = build && commandsOf(build).some((command) => command.words.some((word) => word === 'turbo' || word.endsWith('/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;
+    const findings = [];
+    const build = parsed.stages.find((stage) => stage.name === BUILD_STAGE);
+    const filter = `--filter=@${project}/${app}`;
+    const builds = build && commandsOf(build).some((command) => command.words.some((word) => word === 'turbo' || word.endsWith('/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;
 }
-
 /** 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?.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?.[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');
-  findings.push(...entryHealthFindings(file, runtime, side, kind, exposes, health, none));
-  if (side === 'fe') findings.push(...nextEntryFindings({ repoRoot, file, parsed, app, project, ts }));
-  return findings;
+    const findings = [];
+    const runtime = parsed.stages.at(-1);
+    if (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?.[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');
+    findings.push(...entryHealthFindings(file, runtime, side, kind, exposes, health, none));
+    if (side === 'fe')
+        findings.push(...nextEntryFindings({ repoRoot, file, parsed, app, project, ts }));
+    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_]\w*)\}|\$([A-Za-z_]\w*)/g, (whole, braced, bare) => {
-    const value = defaults.get(braced ?? bare);
-    if (value === undefined) unresolved = true;
-    return value ?? whole;
-  });
-  return unresolved ? null : text;
+    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_]\w*)\}|\$([A-Za-z_]\w*)/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 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.startsWith('.env') && base !== '.env.example';
-  return env || segments.some((segment) => SECRET_FOLDERS.has(segment)) || SECRET_SUFFIXES.some((suffix) => base.endsWith(suffix)) || base.startsWith('kubeconfig');
+    const segments = source.split('/').filter((part) => part && part !== '.');
+    const base = segments.at(-1) ?? '';
+    const 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');
 };
-
 function copySecretFindings(file, item) {
-  const findings = [];
-  const parts = words(item.text);
-  if (parts.some((part) => part.startsWith('--from='))) return findings;
-  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 }));
-  }
-  return findings;
+    const findings = [];
+    const parts = words(item.text);
+    if (parts.some((part) => part.startsWith('--from=')))
+        return findings;
+    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 }));
+    }
+    return findings;
 }
-
 function variableSecretFindings(file, item) {
-  const findings = [];
-  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;
+    const findings = [];
+    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;
 }
-
 /** 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') findings.push(...copySecretFindings(file, item));
-    else if (item.keyword === 'ARG' || item.keyword === 'ENV') findings.push(...variableSecretFindings(file, item));
-  }
-  return findings;
+    const findings = [];
+    for (const item of parsed.instructions) {
+        if (item.keyword === 'COPY' || item.keyword === 'ADD')
+            findings.push(...copySecretFindings(file, item));
+        else if (item.keyword === 'ARG' || item.keyword === 'ENV')
+            findings.push(...variableSecretFindings(file, item));
+    }
+    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' || entry.kind === 'api') ? 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 }),
-      ...healthReachabilityFindings({ repoRoot, file, parsed, side, app, kind, ts }),
-      ...pinFindings(file, parsed),
-      ...secretFindings(file, parsed),
+    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' || entry.kind === 'api') ? 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 }),
+            ...healthReachabilityFindings({ repoRoot, file, parsed, side, app, kind, ts }),
+            ...pinFindings(file, parsed),
+            ...secretFindings(file, parsed),
+        ];
+    });
 }

package/runtime/scripts/hfs/rules/edition.d.mts

@@ -0,0 +1,18 @@
+import type { Parsed, Repo, Resolver } from './rule-types.mjs';
+export declare const HFS_EDITION_FORBIDDEN_PRESENT = "HFS_EDITION_FORBIDDEN_PRESENT";
+export declare const HFS_BACKING_UNDECLARED = "HFS_BACKING_UNDECLARED";
+export declare const HFS_BACKING_UNUSED = "HFS_BACKING_UNUSED";
+/**
+ * L01 for one scope (the app root or one side), over `files` (scope-relative). 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.
+ * The package findings read every package.json of the scope under lite.
+ */
+export declare function editionFindings({ repoRoot, files, repo, resolver, manifest, withDeclaration }: {
+    repoRoot: string;
+    files: string[];
+    repo: Repo;
+    resolver: Resolver;
+    manifest: Parsed;
+    withDeclaration?: Parsed;
+}): any[];