@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/rules/doc-fresh.mjs

@@ -0,0 +1,286 @@
+// R270: product documentation cites paths, commands, environment keys and rules that still exist.
+// Paths in links are document-relative; code/prose paths may be repository-relative. Only tracked
+// names are inspected: no environment file, sealed member or secret value is ever read.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CATALOG } from '../../../packages/cli/src/catalog.generated.mjs';
+import { checkCommand, extractCommands } from '../doc-commands.mjs';
+import { globExpression } from '../../lib/glob.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { loadRuleCatalog } from '../rule-catalog.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+const PATH_MISSING = 'HFS_DOC_PATH_MISSING';
+const COMMAND_UNKNOWN = 'HFS_DOC_COMMAND_UNKNOWN';
+const ENV_UNKNOWN = 'HFS_DOC_ENV_UNKNOWN';
+const RULE_UNKNOWN = 'HFS_DOC_RULE_UNKNOWN';
+const DOCUMENT = /(?:^|\/)README\.md$|(?:^|\/)docs\/.+\.mdx?$/i;
+const KEY = /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$/;
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+const PLACEHOLDER = /[<>{}*$]/;
+const PATH_TOKEN = /^(?:\.\.?\/)?[\w@.-]+(?:\/[\w@.()[\]-]+)*\/?$/;
+let runtimeCatalogs;
+
+function catalogs() {
+  runtimeCatalogs ??= {
+    commands: CATALOG,
+    rules: loadRuleCatalog(),
+  };
+  return runtimeCatalogs;
+}
+
+const trackedPath = (target, tracked) => tracked.has(target) || [...tracked].some((file) => file.startsWith(`${target.replace(/\/$/, '')}/`));
+
+function cleanPath(raw) {
+  if (EXTERNAL.test(raw) || PLACEHOLDER.test(raw)) return null;
+  let target;
+  try { target = decodeURIComponent(raw.split(/[?#]/)[0]); } catch { return null; }
+  if (!PATH_TOKEN.test(target) || !target || target === '.' || target === '..') return null;
+  return target.replace(/\/$/, '');
+}
+
+function codePathRoots(file, tracked) {
+  const side = /^(be|fe)\//.exec(file)?.[1] ?? '';
+  return [...new Set(['', side, packageDirectory(file, tracked)])];
+}
+
+function resolvedPath(raw, file, tracked, link, generated, roots) {
+  const target = cleanPath(raw);
+  if (target === null) return true;
+  const relative = path.posix.normalize(path.posix.join(path.posix.dirname(file), target));
+  const candidates = link ? [relative] : [relative, ...roots.map((root) => path.posix.join(root, target))];
+  return candidates.some((candidate) => !candidate.startsWith('../') && (trackedPath(candidate, tracked) || generated.has(candidate)));
+}
+
+function pathReferences(line) {
+  const refs = [];
+  // Markdown inline and reference links, including image links. URLs and anchors are excluded later.
+  for (const match of line.matchAll(/\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+['"][^)]*)?\)|^\s*\[[^\]]+\]:\s*(?:<([^>]+)>|(\S+))/g)) {
+    refs.push({ target: match[1] ?? match[2] ?? match[3] ?? match[4], link: true });
+  }
+  const masked = line.replace(/\]\([^)]*\)/g, ']');
+  for (const match of masked.matchAll(/`([^`]+)`/g)) {
+    const target = match[1];
+    if (target.includes('/') || /\.(?:md|mdx|json|ya?ml|[cm]?[jt]sx?|sh|env|toml|sql|graphql|enc)$/.test(target)) refs.push({ target, link: false });
+  }
+  // Unquoted prose paths need a slash; dotted words and API routes are not file citations.
+  const prose = masked.replace(/`[^`]*`|\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, '');
+  for (const match of prose.matchAll(/(?<![\w@./:-])((?:\.\.?\/)?[\w@.-]+\/(?:[\w@.()[\]-]+\/)*[\w@.()[\]-]*)(?![\w/])/g)) {
+    refs.push({ target: match[1].replace(/[.,;:]$/, ''), link: false });
+  }
+  return refs;
+}
+
+/** A cited host location (the untracked custody file `.claude/secret.env`, `~/...`) or a prose pair (`expand/contract`: no extension and no tracked top-level folder of that name) is no repository path. */
+function hostOrProse(target, tracked, link, roots) {
+  if (!link && (target === 'process.env' || target === 'import.meta.env')) return true;
+  if (target === '.claude/secret.env' || /^(?:~\/|\/)/.test(target)) return true;
+  if (link || /\.[A-Za-z0-9]+$/.test(target) || target.endsWith('/') || target.startsWith('.')) return false;
+  const top = target.split('/')[0];
+  return !roots.some((root) => trackedPath(path.posix.join(root, top), tracked));
+}
+
+function pathFindings(file, lines, tracked, generated) {
+  const findings = [];
+  const roots = codePathRoots(file, tracked);
+  for (const [index, line] of lines.entries()) {
+    for (const { target, link } of pathReferences(line)) {
+      if (hostOrProse(target, tracked, link, roots)) continue;
+      if (!resolvedPath(target, file, tracked, link, generated, roots)) findings.push(found(PATH_MISSING, file, `${file} cites a missing repository path ${target}; update the documentation or restore the path`, { line: index + 1, reference: target }));
+    }
+  }
+  return findings;
+}
+
+/** Tool reports are generated, never tracked; both their consumer and the slot policy must declare them. */
+function generatedReports(repoRoot, tracked, resolver) {
+  const reports = new Set();
+  if (!tracked.has('sonar-project.properties') || !resolver) return reports;
+  const text = readText(repoRoot, 'sonar-project.properties') ?? '';
+  for (const match of text.matchAll(/^sonar\.javascript\.lcov\.reportPaths\s*=\s*([^\r\n]*)/gm)) {
+    for (const report of match[1].split(',').map((entry) => entry.trim())) {
+      const target = cleanPath(report);
+      if (target && resolver.trackingOf(target) === 'ignored') reports.add(target);
+    }
+  }
+  return reports;
+}
+
+function packageDirectory(file, tracked) {
+  let dir = path.posix.dirname(file);
+  while (true) {
+    if (tracked.has(path.posix.join(dir, 'package.json'))) return dir === '.' ? '' : dir;
+    if (dir === '.') return '';
+    dir = path.posix.dirname(dir);
+  }
+}
+
+function workspaceManifests(repoRoot, directory, tracked) {
+  const manifest = readJson(repoRoot, path.posix.join(directory, 'package.json'));
+  const workspaces = Array.isArray(manifest?.workspaces) ? manifest.workspaces : manifest?.workspaces?.packages ?? [];
+  const patterns = workspaces.map((entry) => globExpression(path.posix.join(directory, entry)));
+  return [...tracked].filter((entry) => path.posix.basename(entry) === 'package.json' && patterns.some((pattern) => pattern.test(path.posix.dirname(entry))));
+}
+
+function missingScripts(repoRoot, directory, tracked, name, workspaces) {
+  const manifests = workspaces ? workspaceManifests(repoRoot, directory, tracked) : [path.posix.join(directory, 'package.json')];
+  if (!manifests.length) return [path.posix.join(directory, 'package.json')];
+  return manifests.filter((file) => !Object.hasOwn(readJson(repoRoot, file)?.scripts ?? {}, name));
+}
+
+function scriptFindings(repoRoot, file, lines, tracked) {
+  const findings = [];
+  const initial = packageDirectory(file, tracked);
+  let directory = initial;
+  for (const [index, line] of lines.entries()) {
+    if (/^\s*```/.test(line)) directory = initial;
+    const changed = /(?:^|[;&]\s*|\$\s*)cd\s+([\w./-]+)/.exec(line);
+    if (changed) directory = path.posix.normalize(path.posix.join(directory, changed[1]));
+    for (const match of line.matchAll(/\bnpm\s+(?:--prefix\s+([\w./-]+)\s+)?run\s+(?:--silent\s+)?([\w:.-]+)/g)) {
+      const dir = match[1] ? path.posix.join(directory, match[1]) : directory;
+      const name = match[2];
+      const tail = line.slice(match.index + match[0].length).split(/[`;&|]/)[0];
+      const workspaces = /(?:^|\s)--workspaces(?:\s|$)/.test(tail);
+      const missing = missingScripts(repoRoot, dir, tracked, name, workspaces);
+      for (const manifest of missing) findings.push(found(COMMAND_UNKNOWN, file, `${file} cites npm run ${name}, absent from ${manifest}; update the command or declare the script`, { line: index + 1, reference: `npm run ${name}` }));
+    }
+  }
+  return findings;
+}
+
+function commandFindings(repoRoot, file, text, tracked, commands) {
+  const findings = scriptFindings(repoRoot, file, text.split(/\r?\n/), tracked);
+  for (const occurrence of extractCommands(text)) {
+    if (!/^\s*app\s/.test(occurrence.text)) continue;
+    for (const issue of checkCommand(occurrence, commands, { strictProse: true }).filter((reason) => /^unknown verb\b/.test(reason))) {
+      findings.push(found(COMMAND_UNKNOWN, file, `${file} cites a starci app command that does not resolve: ${issue}; use a verb from the CLI catalog`, { line: occurrence.line }));
+    }
+  }
+  return findings;
+}
+
+function importedFiles(file, text, tracked) {
+  const prefix = /^(be|fe)\//.exec(file)?.[1] ?? '';
+  const imports = [...text.matchAll(/\b(?:from\s*|import\s*|export\s*\*\s*from\s*)['"]([^'"]+)['"]/g)].map((match) => match[1]);
+  return imports.flatMap((specifier) => {
+    let target;
+    if (specifier.startsWith('.')) target = path.posix.normalize(path.posix.join(path.posix.dirname(file), specifier));
+    else if (specifier.startsWith('@modules/')) target = path.posix.join(prefix, 'src/modules', specifier.slice('@modules/'.length));
+    else return [];
+    return [target, `${target}.ts`, `${target}/index.ts`].filter((candidate) => tracked.has(candidate));
+  });
+}
+
+function addReaderKeys(text, keys) {
+  const readers = new Set(['env', 'source', ...[...text.matchAll(/\b(\w+)\s*:\s*EnvSource\b/g)].map((match) => match[1])]);
+  for (const match of text.matchAll(/\b(\w+)\s*\.\s*\w+\s*\(\s*['"]([A-Z][A-Z0-9_]*)['"]|\bprocess\.env\.([A-Z][A-Z0-9_]*)|\bprocess\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/g)) {
+    if (match[3] || match[4]) keys.add(match[3] ?? match[4]);
+    else if (readers.has(match[1])) keys.add(match[2]);
+  }
+}
+
+function addDocumentedKeys(text, keys) {
+  for (const line of text.split(/\r?\n/)) {
+    const cell = /^\s*\|\s*`?([A-Z][A-Z0-9_]*)`?\s*\|/.exec(line);
+    if (cell) keys.add(cell[1]);
+    const bullet = /^\s*[-*]\s*`([A-Z][A-Z0-9_]*)`/.exec(line);
+    if (bullet) keys.add(bullet[1]);
+  }
+}
+
+function environmentKeys(repoRoot, tracked) {
+  const keys = new Set();
+  const pending = [...tracked].filter((file) => /(?:^|\/)[^/]+\.env\.ts$/.test(file));
+  const seen = new Set();
+  while (pending.length) {
+    const file = pending.pop();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    const text = readText(repoRoot, file) ?? '';
+    // Follow the typed reader's local capability parsers and barrel exports, never execute them.
+    pending.push(...importedFiles(file, text, tracked));
+    addReaderKeys(text, keys);
+  }
+  for (const file of [...tracked].filter((entry) => /(?:^|\/)KEYS\.md$/.test(entry))) {
+    const text = readText(repoRoot, file) ?? '';
+    addDocumentedKeys(text, keys);
+  }
+  return keys;
+}
+
+function symbolCall(ts, node) {
+  if (!node || !ts.isCallExpression(node)) return false;
+  const callee = node.expression;
+  if (ts.isIdentifier(callee)) return callee.text === 'Symbol';
+  return ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression) && callee.expression.text === 'Symbol' && callee.name.text === 'for';
+}
+
+function declaredTokens(ts, source, tokens) {
+  const visit = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && KEY.test(node.name.text) && symbolCall(ts, node.initializer)) tokens.add(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+}
+
+function injectionTokens(repoRoot, tracked) {
+  const tokens = new Set();
+  const ts = loadTypescript(repoRoot, path.dirname(fileURLToPath(import.meta.url)));
+  if (!ts) return tokens;
+  for (const file of tracked) {
+    if (!/\.[cm]?[jt]sx?$/.test(file) || /(?:^|\/)(?:tests?|__tests__)\/|(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/.test(file)) continue;
+    const text = readText(repoRoot, file) ?? '';
+    declaredTokens(ts, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true), tokens);
+  }
+  return tokens;
+}
+
+function unknownEnvironmentName(name, line, keys, codes, tokens, explicit) {
+  if (!KEY.test(name) || /^R\d+$/.test(name) || codes.has(name)) return false;
+  if (!explicit && tokens.has(name) && !/\benv(?:ironment)?\b|\bvariable\b/i.test(line)) return false;
+  if (!name.includes('_') && !keys.has(name) && !/\benv(?:ironment)?\b|\b(?:key|variable)s?\b/i.test(line)) return false;
+  return !keys.has(name) && !(name.endsWith('_FILE') && keys.has(name.slice(0, -5)));
+}
+
+function nameFindings(file, lines, keys, rules, tokens) {
+  const findings = [];
+  const codes = new Set(rules.rules.flatMap((rule) => rule.failureCodes));
+  for (const [index, line] of lines.entries()) {
+    for (const match of line.matchAll(/\bR\d+\b/g)) {
+      if (!rules.rule(match[0])) findings.push(found(RULE_UNKNOWN, file, `${file} cites unknown rule ${match[0]}; use an id from the HFS rule catalog`, { line: index + 1, reference: match[0] }));
+    }
+    for (const match of line.matchAll(/`([A-Z][A-Z0-9_]*)`|\b(?:process\.env\.|\$\{?)([A-Z][A-Z0-9_]*)|\b([A-Z][A-Z0-9_]*)\s*=/g)) {
+      const name = match[1] ?? match[2] ?? match[3];
+      if (!unknownEnvironmentName(name, line, keys, codes, tokens, !match[1])) continue;
+      findings.push(found(ENV_UNKNOWN, file, `${file} cites unknown environment key ${name}; declare it in a typed environment reader or KEYS.md, or update the documentation`, { line: index + 1, reference: name }));
+    }
+  }
+  return findings;
+}
+
+/** Findings of R270 over product READMEs and docs, in lite and full; runtime docs retain their own checks. */
+export function docFreshFindings({ repoRoot, files = [], all = files, repo, resolver, appSide = false, inScope = () => true }) {
+  if (appSide || repo?.profile === 'runtime' || !['lite', 'full'].includes(repo?.edition)) return [];
+  const inventory = repo.profile === 'app' ? all : files;
+  const docs = inventory.filter((file) => DOCUMENT.test(file) && path.posix.basename(file) !== 'KEYS.md' && inScope(file));
+  if (!docs.length) return [];
+  const tracked = new Set(all);
+  const { commands, rules } = catalogs();
+  const keys = environmentKeys(repoRoot, tracked);
+  const tokens = injectionTokens(repoRoot, tracked);
+  const generated = generatedReports(repoRoot, tracked, resolver);
+  const findings = [];
+  for (const file of docs) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    const lines = text.split(/\r?\n/);
+    findings.push(...pathFindings(file, lines, tracked, generated), ...commandFindings(repoRoot, file, text, tracked, commands), ...nameFindings(file, lines, keys, rules, tokens));
+  }
+  const seen = new Set();
+  return findings.filter((finding) => {
+    const key = `${finding.code}:${finding.path}:${finding.line}:${finding.reference ?? finding.message}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

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

@@ -0,0 +1,249 @@
+// Docker API liveness reachability through the app module graph and its health probe.
+import path from 'node:path';
+import { literalText as tsLiteral, variableInitializerGroups } from '../../lib/ts-ast.mjs';
+import { execForm, shellCommands } from '../../lib/dockerfile.mjs';
+import { readText } from './read.mjs';
+
+/** Resolve only app-owned source imports; health routes must be reachable from this app's module composition. */
+function healthSourceBase(filename, source) {
+  if (source.startsWith('.')) return path.posix.normalize(path.posix.join(path.posix.dirname(filename), source));
+  if (source.startsWith('@features/')) return `be/src/features/${source.slice(10)}`;
+  if (source.startsWith('@modules/')) return `be/src/modules/${source.slice(9)}`;
+  return null;
+}
+
+function healthSourcePath(repoRoot, filename, source) {
+  const base = healthSourceBase(filename, source);
+  if (!base || base.startsWith('../')) return null;
+  return [base, `${base}.ts`, `${base}/index.ts`].find((candidate) => readText(repoRoot, candidate) !== null) ?? null;
+}
+
+const tsDecorators = (ts, node) => ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : [];
+const tsDecoratorCall = (ts, node, name) => tsDecorators(ts, node).map((entry) => entry.expression).find((entry) => ts.isCallExpression(entry) && ts.isIdentifier(entry.expression) && entry.expression.text === name);
+
+function collectHealthUsage(ts, node, state, seen = new Set()) {
+  if (ts.isIdentifier(node)) {
+    state.used.add(node.text);
+    if (state.bindings.has(node.text) && !seen.has(node.text)) collectHealthUsage(ts, state.bindings.get(node.text), state, new Set(seen).add(node.text));
+  }
+  ts.forEachChild(node, (child) => collectHealthUsage(ts, child, state, seen));
+}
+
+function collectHealthModuleObject(ts, node, state) {
+  if (!node || !ts.isObjectLiteralExpression(node)) return;
+  for (const property of node.properties) {
+    if (!ts.isPropertyAssignment(property)) continue;
+    const name = property.name.getText(state.source).replace(/^['"]|['"]$/g, '');
+    if (['imports', 'controllers'].includes(name)) collectHealthUsage(ts, property.initializer, state);
+  }
+}
+
+function collectHealthReturns(ts, node, state) {
+  const expression = node.expression;
+  if (ts.isReturnStatement(node) && expression && ts.isObjectLiteralExpression(expression)
+      && expression.properties.some((property) => property.name?.getText(state.source) === 'module')) collectHealthModuleObject(ts, expression, state);
+  ts.forEachChild(node, (child) => collectHealthReturns(ts, child, state));
+}
+
+function collectHealthClassWiring(ts, node, state) {
+  collectHealthModuleObject(ts, tsDecoratorCall(ts, node, 'Module')?.arguments[0], state);
+  for (const method of node.members) {
+    if (method.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword)) collectHealthReturns(ts, method, state);
+  }
+}
+
+function collectHealthExportNames(ts, node, state) {
+  if (!ts.isExportDeclaration(node) || node.moduleSpecifier || !node.exportClause || !ts.isNamedExports(node.exportClause)) return;
+  for (const entry of node.exportClause.elements) {
+    if (!state.wanted || state.wanted.includes(entry.name.text)) state.used.add((entry.propertyName ?? entry.name).text);
+  }
+}
+
+function collectHealthWiring(ts, node, state) {
+  const { wanted } = state;
+  if (ts.isClassDeclaration(node) && (!wanted || wanted.includes(node.name?.text))) collectHealthClassWiring(ts, node, state);
+  if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && wanted?.includes(node.name.text) && node.initializer) collectHealthUsage(ts, node.initializer, state);
+  if (ts.isFunctionDeclaration(node) && wanted?.includes(node.name?.text) && node.body) collectHealthUsage(ts, node.body, state);
+  collectHealthExportNames(ts, node, state);
+  ts.forEachChild(node, (child) => collectHealthWiring(ts, child, state));
+}
+
+function healthWiringNames(ts, source, wanted) {
+  const bindings = new Map([...variableInitializerGroups(ts, source)].map(([name, initializers]) => [name, initializers.at(-1)]));
+  const state = { source, wanted, used: new Set(), bindings };
+  collectHealthWiring(ts, source, state);
+  return state.used;
+}
+
+function sourceHasLiveRoute(ts, source, wanted, used) {
+  const isLiveController = (node) => {
+    if (!ts.isClassDeclaration(node)) return false;
+    if (wanted && !wanted.includes(node.name?.text) && !used.has(node.name?.text)) return false;
+    if (tsLiteral(ts, tsDecoratorCall(ts, node, 'Controller')?.arguments[0]) !== 'health') return false;
+    return node.members.some((member) => tsLiteral(ts, tsDecoratorCall(ts, member, 'Get')?.arguments[0]) === 'live');
+  };
+  return source.statements.filter((node) => !ts.isImportDeclaration(node)).some((node) => tsSome(ts, node, isLiveController));
+}
+
+function healthImportNames(ts, clause, used) {
+  const bindings = clause?.namedBindings;
+  if (bindings && ts.isNamedImports(bindings)) {
+    return bindings.elements.filter((entry) => !entry.isTypeOnly && used.has(entry.name.text)).map((entry) => (entry.propertyName ?? entry.name).text);
+  }
+  return [clause?.name?.text].filter((name) => used.has(name));
+}
+
+function healthImportTargets({ repoRoot, filename, ts, source, used }) {
+  const targets = [];
+  for (const statement of source.statements.filter((node) => ts.isImportDeclaration(node))) {
+    const clause = statement.importClause;
+    if (clause?.isTypeOnly) continue;
+    const imported = healthImportNames(ts, clause, used);
+    if (!imported.length) continue;
+    const target = healthSourcePath(repoRoot, filename, statement.moduleSpecifier.text);
+    if (target) targets.push({ filename: target, wanted: imported });
+  }
+  return targets;
+}
+
+function healthExportTargets({ repoRoot, filename, ts, source, wanted }) {
+  const targets = [];
+  for (const statement of source.statements.filter((node) => ts.isExportDeclaration(node) && node.moduleSpecifier && !node.isTypeOnly)) {
+    const target = healthSourcePath(repoRoot, filename, statement.moduleSpecifier.text);
+    let exported = wanted;
+    if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+      exported = statement.exportClause.elements.filter((entry) => !wanted || wanted.includes(entry.name.text)).map((entry) => (entry.propertyName ?? entry.name).text);
+    }
+    if (target && (!exported || exported.length)) targets.push({ filename: target, wanted: exported });
+  }
+  return targets;
+}
+
+/** Find GET /health/live in the local import closure, excluding unused imports and type-only imports. */
+function apiLiveRoute({ repoRoot, app, ts }) {
+  const pending = [{ filename: `be/apps/${app}/src/app.module.ts`, wanted: ['AppModule'] }];
+  const visited = new Set();
+  while (pending.length) {
+    const { filename, wanted } = pending.pop();
+    const identity = `${filename}:${wanted?.join(',') ?? '*'}`;
+    if (visited.has(identity)) continue;
+    visited.add(identity);
+    const text = readText(repoRoot, filename);
+    if (text === null) continue;
+    const source = ts.createSourceFile(filename, text, ts.ScriptTarget.Latest, true);
+    const used = healthWiringNames(ts, source, wanted);
+    if (sourceHasLiveRoute(ts, source, wanted, used)) return true;
+    pending.push(
+      ...healthImportTargets({ repoRoot, filename, ts, source, used }),
+      ...healthExportTargets({ repoRoot, filename, ts, source, wanted }),
+    );
+  }
+  return false;
+}
+
+/** Keep literal URL pieces while substituting the runtime's declared port for a dynamic expression. */
+function probeUrlText(ts, node, port) {
+  if (!node) return null;
+  const literal = tsLiteral(ts, node);
+  if (literal !== null) return literal;
+  if (ts.isParenthesizedExpression(node)) return probeUrlText(ts, node.expression, port);
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+    const left = probeUrlText(ts, node.left, port);
+    const right = probeUrlText(ts, node.right, port);
+    return left === null && right === null ? null : `${left ?? port}${right ?? port}`;
+  }
+  if (ts.isTemplateExpression(node)) return node.head.text + node.templateSpans.map((entry) => `${port}${entry.literal.text}`).join('');
+  return null;
+}
+
+function localLiveUrl(value, port) {
+  try {
+    const url = new URL(value.replace(/\$\{?PORT\}?/g, port));
+    return url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+      && (url.port || '80') === port && url.pathname === '/health/live';
+  } catch { return false; }
+}
+
+function tsSome(ts, node, predicate) {
+  if (!node) return false;
+  if (predicate(node)) return true;
+  let foundNode = false;
+  ts.forEachChild(node, (child) => { if (tsSome(ts, child, predicate)) foundNode = true; });
+  return foundNode;
+}
+
+const failedExit = (ts, node) => ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
+  && node.expression.expression.getText() === 'process' && node.expression.name.text === 'exit'
+  && node.arguments[0] && ts.isNumericLiteral(node.arguments[0]) && Number(node.arguments[0].text) > 0;
+const responseStatus = (ts, node, response) => tsSome(ts, node, (entry) => ts.isPropertyAccessExpression(entry)
+  && ts.isIdentifier(entry.expression) && entry.expression.text === response && ['ok', 'status', 'statusCode'].includes(entry.name.text));
+
+/** The failure exit must belong to the callback consuming this response, and depend on that response's status. */
+function responseFails(ts, callback) {
+  if (!callback || !(ts.isArrowFunction(callback) || ts.isFunctionExpression(callback))) return false;
+  const response = callback.parameters[0]?.name;
+  if (!response || !ts.isIdentifier(response)) return false;
+  return tsSome(ts, callback.body, (node) => {
+    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.expression.getText() === 'process' && node.expression.name.text === 'exit') {
+      const arg = node.arguments[0];
+      return arg && ts.isConditionalExpression(arg) && responseStatus(ts, arg.condition, response.text)
+        && [arg.whenTrue, arg.whenFalse].some((entry) => ts.isNumericLiteral(entry) && Number(entry.text) > 0);
+    }
+    return ts.isIfStatement(node) && responseStatus(ts, node.expression, response.text)
+      && tsSome(ts, node.thenStatement, (entry) => failedExit(ts, entry) || ts.isThrowStatement(entry));
+  });
+}
+
+function chainedCall(ts, node, name) {
+  const member = node.parent;
+  return member && ts.isPropertyAccessExpression(member) && member.expression === node && member.name.text === name
+    && member.parent && ts.isCallExpression(member.parent) ? member.parent : null;
+}
+
+function nodeProbeReachesLive(ts, code, port) {
+  const source = ts.createSourceFile('healthcheck.js', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  return tsSome(ts, source, (node) => {
+    if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression) || node.expression.text !== 'fetch') return false;
+    const url = probeUrlText(ts, node.arguments[0], port);
+    if (!url || !localLiveUrl(url, port)) return false;
+    for (let parent = node.parent; parent && parent !== source; parent = parent.parent) {
+      if (ts.isFunctionDeclaration(parent) || ts.isFunctionExpression(parent) || ts.isArrowFunction(parent) || ts.isIfStatement(parent) || ts.isConditionalExpression(parent)) return false;
+    }
+    const consumed = chainedCall(ts, node, 'then');
+    if (!consumed || !responseFails(ts, consumed.arguments[0])) return false;
+    const rejected = chainedCall(ts, consumed, 'catch')?.arguments[0] ?? consumed.arguments[1];
+    return rejected && (ts.isArrowFunction(rejected) || ts.isFunctionExpression(rejected)) && tsSome(ts, rejected.body, (entry) => failedExit(ts, entry));
+  });
+}
+
+/** A shell health probe cannot erase a failure through a pipeline, fallback, or later independent command. */
+function masksProbeFailure(body) {
+  let quote = null;
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index];
+    if (char === '\\') { index += 1; continue; }
+    if (quote) { if (char === quote) quote = null; continue; }
+    if (char === '"' || char === "'") { quote = char; continue; }
+    if (char === ';' || char === '|') return true;
+  }
+  return false;
+}
+
+function healthCommandReachesLive(ts, body, port) {
+  const exec = execForm(body);
+  if (!exec && masksProbeFailure(body)) return false;
+  const commands = exec ? [exec] : shellCommands(body);
+  if (commands.at(-1)?.[0] === 'true' || commands.at(-1)?.join(' ') === 'exit 0') return false;
+  return commands.some((parts) => {
+    const tool = parts[0];
+    if (['sh', '/bin/sh', 'bash', '/bin/bash'].includes(tool) && parts.includes('-c')) return healthCommandReachesLive(ts, parts[parts.indexOf('-c') + 1] ?? '', port);
+    if (['curl', 'wget'].includes(tool)) return (tool === 'wget' || parts.some((arg) => arg === '--fail' || /^-[^-]*f/.test(arg))) && parts.slice(1).some((arg) => localLiveUrl(arg, port));
+    if (tool !== 'node' || !parts.includes('-e')) return false;
+    return nodeProbeReachesLive(ts, parts[parts.indexOf('-e') + 1] ?? '', port);
+  });
+}
+
+/** Whether the API image probes a registered local liveness route and propagates probe failure. */
+export function healthProbeReachesLive({ repoRoot, app, ts, body, port }) {
+  return healthCommandReachesLive(ts, body, port) && apiLiveRoute({ repoRoot, app, ts });
+}

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

@@ -2,7 +2,7 @@
 // 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
+//   HFS_DOCKER_BUILD_CONTEXT  the header comment states the app's own build command (`starci docker build <app>` or `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
@@ -18,12 +18,14 @@ 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';
+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';
@@ -78,11 +80,12 @@ function envOf(stage) {
   return env;
 }
 
-/** True when a header comment states `docker build -f <wanted> ... .`. */
-const statesBuildCommand = (parsed, wanted) => parsed.comments.some((comment) => {
+/** 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) === '.';
 });
@@ -105,7 +108,7 @@ function copySourceFindings(file, item) {
 function contextFindings(file, parsed, side, app) {
   const findings = [];
   const wanted = dockerfilePath(side, app);
-  if (!statesBuildCommand(parsed, wanted)) 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 }));
+  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;
 }
@@ -116,7 +119,7 @@ function stageInstallFindings(file, stages) {
   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 }));
+      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;
@@ -183,6 +186,19 @@ function entryHealthFindings(file, runtime, side, kind, exposes, health, 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 })];
+}
+
 function nextEntryFindings({ repoRoot, file, parsed, app, project, ts }) {
   const findings = [];
   const build = parsed.stages.find((stage) => stage.name === BUILD_STAGE);
@@ -244,7 +260,7 @@ const isCredentialName = (name) => !name.startsWith('NEXT_PUBLIC_') && name.spli
 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');
+  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');
 };
 
@@ -289,7 +305,7 @@ export function dockerFindings({ repoRoot, files, repo }) {
     ...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;
+  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 [];
@@ -300,6 +316,7 @@ export function dockerFindings({ repoRoot, files, repo }) {
       ...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),
     ];