@starci/hfs 4.2.17 → 4.4.0

package/runtime/scripts/hfs/rules/unused-symbol.mjs

@@ -0,0 +1,320 @@
+// R280: declarations are not consumers. Error-kind maps, message catalogs, imports,
+// re-exports and tests do not keep an otherwise unused value alive.
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { found, readText } from './read.mjs';
+import { nameText } from '../../lib/ts-ast.mjs';
+import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
+import { argumentBindings, callable, jsonCatalogBindings, jsonCatalogRead, staticStrings } from './unused-symbol-values.mjs';
+import { catalogNamespace, translationBindings } from './unused-symbol-translators.mjs';
+import { applyDynamicKeysLedger } from './unused-symbol-ledger.mjs';
+import { returnedExpressions, valuesOf } from './unused-symbol-flow.mjs';
+
+export const HFS_UNUSED_SYMBOL = 'HFS_UNUSED_SYMBOL';
+const SOURCE = /\.[cm]?[jt]sx?$/u;
+const EXCLUDED = /(?:^|\/)(?:node_modules|__generated__|_generated|dist|tests?|__tests__|test-support)\/|(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$|\.d\.[cm]?ts$/u;
+const CATALOG = /(?:\.messages|\.catalog)\.[cm]?[jt]s$/u;
+const JSON_CATALOG = /(?:^|\/)(?:messages|locales)\/[^/]+\.json$|\.catalog\.json$/u;
+const QUEUE_NAME = /(?:^QUEUE(?:_NAME)?$|_QUEUE(?:_NAME)?$)/u;
+const ERROR_NAME = /(?:^ERROR_CODE$|_ERROR_CODE$)/u;
+const slash = value => value.replaceAll('\\', '/');
+
+function compilerAt(repoRoot, supplied) {
+  if (supplied) return supplied;
+  // TypeScript belongs to the checked product, just as in the architecture machine.
+  // Its missing-compiler refusal is reported there, rather than mislabeled as dead code.
+  try { return createRequire(path.join(repoRoot, 'package.json'))('typescript'); } catch { return null; }
+}
+
+function sourceFiles(ts, repoRoot, files) {
+  const sources = new Map();
+  for (const file of files) {
+    if (!SOURCE.test(file) || EXCLUDED.test(file) || !/(?:^|\/)src\//u.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text !== null) sources.set(slash(path.resolve(repoRoot, file)), ts.createSourceFile(path.resolve(repoRoot, file), text, ts.ScriptTarget.Latest, true));
+  }
+  return sources;
+}
+
+function projectOptions(ts, repoRoot, files) {
+  const projects = [];
+  for (const file of files.filter(file => /(?:^|\/)tsconfig\.json$/u.test(file))) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    const absolute = path.resolve(repoRoot, file);
+    const config = ts.parseConfigFileTextToJson(absolute, text);
+    if (config.error) continue;
+    const host = { ...ts.sys, readFile: target => {
+      const rel = slash(path.relative(repoRoot, target));
+      return rel.startsWith('../') ? undefined : readText(repoRoot, rel) ?? undefined;
+    } };
+    const parsed = ts.parseJsonConfigFileContent(config.config, host, path.dirname(absolute), {}, absolute);
+    projects.push({ directory: `${slash(path.dirname(absolute))}/`, options: parsed.options });
+  }
+  return projects.sort((a, b) => b.directory.length - a.directory.length);
+}
+
+function trackedProgram(ts, repoRoot, files, sources) {
+  const options = { noLib: true, types: [], allowJs: true, resolveJsonModule: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, module: ts.ModuleKind.ESNext, moduleResolution: ts.ModuleResolutionKind.Bundler };
+  const projects = projectOptions(ts, repoRoot, files);
+  const catalogs = new Set(files.filter(file => JSON_CATALOG.test(file)).map(file => slash(path.resolve(repoRoot, file))));
+  const host = {
+    getSourceFile: file => sources.get(slash(path.resolve(file))),
+    getDefaultLibFileName: () => '', writeFile: () => {},
+    getCurrentDirectory: () => repoRoot, getDirectories: () => [],
+    fileExists: file => sources.has(slash(path.resolve(file))) || catalogs.has(slash(path.resolve(file))),
+    readFile: file => sources.get(slash(path.resolve(file)))?.text,
+    getCanonicalFileName: slash, useCaseSensitiveFileNames: () => true,
+    getNewLine: () => '\n',
+  };
+  const resolveModule = (name, containing) => {
+    const project = projects.find(project => slash(containing).startsWith(project.directory));
+    return ts.resolveModuleName(name, containing, { ...options, ...project?.options }, host).resolvedModule;
+  };
+  host.resolveModuleNames = (names, containing) => names.map(name => resolveModule(name, containing));
+  return { program: ts.createProgram([...sources.keys()], options, host), resolveModule };
+}
+
+const symbolOf = (ts, checker, node) => {
+  const shorthand = ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node;
+  const symbol = shorthand ? checker.getShorthandAssignmentValueSymbol(node.parent) : checker.getSymbolAtLocation(node);
+  return symbol?.flags === ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+};
+
+function addCandidate(state, source, node, kind, name, value, symbol) {
+  const at = source.getLineAndCharacterOfPosition(node.getStart(source));
+  const candidate = { path: slash(path.relative(state.repoRoot, source.fileName)), line: at.line + 1, column: at.character + 1, kind, name, value, used: false };
+  state.candidates.push(candidate);
+  if (symbol) state.symbols.set(symbol, candidate);
+  if (symbol?.valueDeclaration) state.decls.set(symbol.valueDeclaration, candidate);
+  return candidate;
+}
+
+function enumCandidates(state, source, declaration) {
+  const members = [];
+  for (const member of declaration.members) {
+    const name = nameText(state.ts, member.name, { numbers: true });
+    if (name === null) continue;
+    const kind = declaration.name.text.endsWith('ErrorCode') ? 'error code' : 'enum member';
+    const value = state.checker.getConstantValue(member) ?? null;
+    members.push(addCandidate(state, source, member, kind, `${declaration.name.text}.${name}`, value, state.checker.getSymbolAtLocation(member.name)));
+  }
+  state.containers.set(state.checker.getSymbolAtLocation(declaration.name), members);
+}
+
+function catalogProperties(state, source, object, prefix = '') {
+  for (const property of object.properties) {
+    if (!state.ts.isPropertyAssignment(property)) continue;
+    const name = nameText(state.ts, property.name, { numbers: true });
+    if (name === null) continue;
+    const child = unwrap(state.ts, property.initializer);
+    if (state.ts.isObjectLiteralExpression(child) && !child.properties.some(item => ['vi', 'en'].includes(nameText(state.ts, item.name, { numbers: true })))) {
+      catalogProperties(state, source, child, ['vi', 'en'].includes(name) ? prefix : `${prefix}${name}.`);
+    } else {
+      const key = `${prefix}${name}`;
+      addCandidate(state, source, property, 'catalog key', key, key, state.checker.getSymbolAtLocation(property.name));
+    }
+  }
+}
+
+function variableCandidates(state, source, declaration) {
+  const { ts, checker } = state;
+  if (!ts.isIdentifier(declaration.name) || !declaration.initializer) return;
+  const value = unwrap(ts, declaration.initializer);
+  const name = declaration.name.text;
+  if (CATALOG.test(source.fileName) && ts.isObjectLiteralExpression(value)) {
+    catalogProperties(state, source, value);
+    return;
+  }
+  if (ts.isStringLiteralLike(value) && (QUEUE_NAME.test(name) || ERROR_NAME.test(name))) {
+    addCandidate(state, source, declaration, QUEUE_NAME.test(name) ? 'queue constant' : 'error code', name, value.text, checker.getSymbolAtLocation(declaration.name));
+  } else if (/(?:ErrorCodes|ERROR_CODES)$/u.test(name) && ts.isObjectLiteralExpression(value)) {
+    const members = value.properties.filter(property => ts.isPropertyAssignment(property) && ts.isStringLiteralLike(unwrap(ts, property.initializer))).map(property =>
+      addCandidate(state, source, property, 'error code', `${name}.${nameText(ts, property.name, { numbers: true })}`, unwrap(ts, property.initializer).text, checker.getSymbolAtLocation(property.name)));
+    state.containers.set(checker.getSymbolAtLocation(declaration.name), members);
+  }
+}
+
+function collectCandidates(state, sources) {
+  for (const source of sources.values()) {
+    const visit = node => {
+      if (state.ts.isEnumDeclaration(node)) enumCandidates(state, source, node);
+      else if (state.ts.isVariableDeclaration(node)) variableCandidates(state, source, node);
+      state.ts.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+}
+
+function metadataDeclaration(ts, node, source) {
+  if (!ts.isVariableDeclaration(node)) return false;
+  if (CATALOG.test(source.fileName)) return true;
+  const name = nameText(ts, node.name, { numbers: true }) ?? '';
+  return /(?:ERROR_KINDS|ERROR_MESSAGES|ERROR_CODES|errorKinds|errorMessages)$/u.test(name) && ts.isObjectLiteralExpression(unwrap(ts, node.initializer) ?? node);
+}
+
+function declarationName(ts, node) {
+  const parent = node.parent;
+  return parent?.name === node && (ts.isVariableDeclaration(parent) || ts.isParameter(parent) || ts.isBindingElement(parent) || ts.isPropertyAssignment(parent)
+    || ts.isPropertyDeclaration(parent) || ts.isMethodDeclaration(parent) || ts.isFunctionDeclaration(parent) || ts.isClassDeclaration(parent));
+}
+
+const matchesMember = (member, key) => key === null || member.name.endsWith(`.${key}`) || typeof member.value === 'number' && String(member.value) === key;
+const markMembers = (members, key) => { for (const member of members) if (matchesMember(member, key)) member.used = true; };
+
+function markContainerRead(ts, members, node) {
+  const receiver = ts.isPropertyAccessExpression(node.parent) && node.parent.name === node ? node.parent : node;
+  const parent = receiver.parent;
+  if (ts.isPropertyAccessExpression(parent) && parent.expression === receiver) {
+    markMembers(members, parent.name.text);
+    return;
+  }
+  if (ts.isElementAccessExpression(parent) && parent.expression === receiver) {
+    const key = nameText(ts, parent.argumentExpression, { identifiers: false, numbers: true });
+    markMembers(members, key);
+    return;
+  }
+  // An enum handed to a consumer or enumerated dynamically can read any member.
+  for (const member of members) member.used = true;
+}
+
+function markReference(state, node) {
+  const { ts, checker } = state;
+  if (declarationName(ts, node)) return;
+  const symbol = symbolOf(ts, checker, node);
+  // A property read through an imported object resolves to a transient widened symbol; its declaration is the candidate's.
+  const candidate = state.symbols.get(symbol) ?? state.decls.get(symbol?.valueDeclaration);
+  if (candidate) candidate.used = true;
+  const members = state.containers.get(symbol);
+  if (members) markContainerRead(ts, members, node);
+}
+
+function ignoredRead(state, node, source) {
+  const { ts } = state;
+  if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node) || ts.isEnumDeclaration(node) || ts.isTypeNode(node) || metadataDeclaration(ts, node, source)) return true;
+  return ts.isVariableDeclaration(node) && (state.symbols.has(state.checker.getSymbolAtLocation(node.name)) || state.containers.has(state.checker.getSymbolAtLocation(node.name)));
+}
+
+const readKey = (state, prefix, value) => (prefix === null ? state.looseReads : state.catalogReads).add(prefix === null ? value : `${prefix}${value}`);
+
+const hasLiteral = template => Boolean(template.head.text) || template.templateSpans.some(span => span.literal.text);
+
+/** The function a call runs, when it is a local or imported arrow or declaration. */
+function calledFunction(state, call) {
+  const target = callable(state, call.expression);
+  return target && (state.ts.isArrowFunction(target) || state.ts.isFunctionExpression(target) || state.ts.isFunctionDeclaration(target)) ? target : null;
+}
+
+/** What an argument that is no literal can still spell: resolved values, wrapper arguments, and what a key builder returns. */
+function indirectArguments(state, argument, prefix, seen) {
+  const { ts } = state;
+  for (const value of staticStrings(state, argument)) readKey(state, prefix, value);
+  for (const leaf of valuesOf(state, argument)) if (leaf !== argument) catalogArguments(state, leaf, prefix, seen);
+  const builder = ts.isCallExpression(argument) ? calledFunction(state, argument) : null;
+  for (const returned of builder ? returnedExpressions(ts, builder) : []) catalogArguments(state, returned, prefix, seen);
+}
+
+function templateArguments(state, template, prefix) {
+  // A literal head or tail makes the template a key pattern; a template of holes only proves nothing.
+  if (prefix !== null && hasLiteral(template)) state.templates.push([`${prefix}${template.head.text}`, ...template.templateSpans.map(span => span.literal.text)]);
+}
+
+function catalogArguments(state, node, prefix, seen = new Set()) {
+  const { ts } = state;
+  const argument = unwrap(ts, node);
+  if (!argument || seen.has(argument)) return;
+  seen.add(argument);
+  if (ts.isConditionalExpression(argument)) {
+    catalogArguments(state, argument.whenTrue, prefix, seen);
+    catalogArguments(state, argument.whenFalse, prefix, seen);
+  } else if (ts.isStringLiteralLike(argument)) readKey(state, prefix, argument.text);
+  else if (ts.isTemplateExpression(argument)) templateArguments(state, argument, prefix);
+  else indirectArguments(state, argument, prefix, seen);
+}
+
+function namespacePrefix(namespace) {
+  if (namespace === null) return null;
+  return namespace ? `${namespace}.` : '';
+}
+
+function collectLiteralReads(state, node) {
+  const { ts } = state;
+  if (ts.isStringLiteralLike(node) && !declarationName(ts, node)) state.reads.add(node.text);
+  jsonCatalogRead(state, node);
+  if (!ts.isCallExpression(node)) return;
+  for (const namespace of catalogNamespace(state, node.expression)) catalogArguments(state, node.arguments[0], namespacePrefix(namespace));
+}
+
+function sourceReads(state, sources) {
+  for (const source of sources.values()) {
+    const visit = node => {
+      const { ts } = state;
+      if (ignoredRead(state, node, source)) return;
+      if (ts.isIdentifier(node)) markReference(state, node);
+      collectLiteralReads(state, node);
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+}
+
+function jsonCandidates(state, files) {
+  for (const file of files.filter(file => JSON_CATALOG.test(file) && !EXCLUDED.test(file))) {
+    let json;
+    try { json = JSON.parse(readText(state.repoRoot, file)); } catch { continue; }
+    const leaves = (value, prefix = '') => {
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        for (const [key, child] of Object.entries(value)) leaves(child, prefix ? `${prefix}.${key}` : key);
+      } else if (prefix) state.candidates.push({ path: file, line: 1, column: 1, kind: 'catalog key', name: prefix, value: prefix, used: false });
+    };
+    leaves(json);
+  }
+}
+
+/** R106's rule for a translator handed in without its namespace: a key is read when a string equals any tail of its dotted path. */
+function looseRead(state, name) {
+  const segments = name.split('.');
+  return segments.some((_, index) => state.looseReads.has(segments.slice(index).join('.')));
+}
+
+function catalogRead(state, candidate, liveCodes) {
+  if (candidate.name.startsWith('errors.') && liveCodes.has(candidate.name.slice(7))) return true;
+  if (state.catalogReads.has(candidate.name) || looseRead(state, candidate.name)) return true;
+  return state.templates.some(parts => parts.some(Boolean) && (() => {
+    const tail = candidate.name;
+    let offset = 0;
+    for (const [index, part] of parts.entries()) {
+      const next = tail.indexOf(part, offset);
+      if (next < 0 || index === 0 && next !== 0) return false;
+      offset = next + part.length;
+    }
+    return tail.endsWith(parts.at(-1));
+  })());
+}
+
+/** The same rule applies to lite and full. Analyze all tracked consumers before filtering findings to a fast-check scope. */
+export function unusedSymbolFindings({ repoRoot, files, repo = {}, isRoot = false, inScope = () => true, ts: supplied }) {
+  const edition = repo.edition ?? 'full';
+  if (isRoot || repo.kind === 'runtime' || !['lite', 'full'].includes(edition)) return [];
+  const ts = compilerAt(repoRoot, supplied);
+  if (!ts) return [];
+  const sources = sourceFiles(ts, repoRoot, files);
+  const { program, resolveModule } = trackedProgram(ts, repoRoot, files, sources);
+  const state = { ts, checker: program.getTypeChecker(), resolveModule, repoRoot, candidates: [], symbols: new Map(), containers: new Map(), reads: new Set(), catalogReads: new Set(), translators: new Map(), templates: [], arguments: new Map(), catalogObjects: new Map(), decls: new Map(), looseReads: new Set() };
+  collectCandidates(state, sources);
+  argumentBindings(state, sources);
+  jsonCatalogBindings(state, sources, files);
+  translationBindings(state, sources);
+  sourceReads(state, sources);
+  jsonCandidates(state, files);
+  const ledgerFindings = applyDynamicKeysLedger(state, repo.profile);
+  for (const candidate of state.candidates) if (candidate.kind === 'error code' && state.reads.has(candidate.value)) candidate.used = true;
+  const liveCodes = new Set(state.candidates.filter(candidate => candidate.kind === 'error code' && candidate.used).map(candidate => candidate.value));
+  const findings = new Map();
+  for (const candidate of state.candidates) {
+    if (candidate.used || candidate.kind === 'catalog key' && catalogRead(state, candidate, liveCodes) || !inScope(candidate.path)) continue;
+    const { used: _used, ...extra } = candidate;
+    findings.set(`${candidate.path}:${candidate.name}`, found(HFS_UNUSED_SYMBOL, candidate.path, `${candidate.path} declares unused ${candidate.kind} ${candidate.name}; remove it or read it in production source (declarations, metadata maps and tests do not count).`, extra));
+  }
+  return [...findings.values(), ...ledgerFindings.filter(finding => inScope(finding.path))].sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.name.localeCompare(b.name));
+}

package/runtime/scripts/hfs/runtime-rules/source-ast.mjs

@@ -0,0 +1,185 @@
+// source-ast.mjs - the syntax-tree reading the runtime rules share (scripts/hfs/runtime-check.mjs): one TypeScript parse
+// per runtime source file, never a text grep. Pure: every function takes a source text and returns facts about it.
+//   parseSource(text, file)       the TypeScript SourceFile (JS script kind for .mjs/.cjs/.js)
+//   moduleRefs(source)            every import/export-from/require()/import() of a string specifier: [{module, line}]
+//   relativeImports(source)       the relative specifiers among them: [{specifier, line, column}]
+//   localBindings(source)         every name the file declares (variables, functions, classes, parameters, imports)
+//   exportedNames(source)         the names the module exports (export function/const/class, export {a as b}, default)
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+let typescript = null;
+/** The TypeScript compiler, loaded once from the runtime's own dependencies. */
+export const ts = () => (typescript ??= createRequire(import.meta.url)('typescript'));
+
+const FS_MODULES = new Set(['fs', 'node:fs', 'fs/promises', 'node:fs/promises']);
+
+/** `node` is a string literal naming an fs module specifier ('fs', 'node:fs', 'fs/promises', 'node:fs/promises'). */
+const fsSpecifier = (t, node) => Boolean(node && t.isStringLiteralLike(node) && FS_MODULES.has(node.text));
+
+/** `node` is a `require('fs' | 'node:fs' | 'fs/promises' | 'node:fs/promises')` call. */
+const fsRequireCall = (t, node) => node && t.isCallExpression(node) && t.isIdentifier(node.expression) && node.expression.text === 'require' && fsSpecifier(t, node.arguments[0]);
+
+function bindImport(t, node, wanted, namespaces, members) {
+  if (!t.isImportDeclaration(node) || !fsSpecifier(t, node.moduleSpecifier)) return;
+  const clause = node.importClause;
+  if (clause?.name) namespaces.add(clause.name.text);
+  const bindings = clause?.namedBindings;
+  if (bindings && t.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+  if (bindings && t.isNamedImports(bindings)) for (const element of bindings.elements) {
+    const imported = (element.propertyName ?? element.name).text;
+    if (imported === 'promises') namespaces.add(element.name.text);
+    else if (wanted(imported)) members.set(element.name.text, imported);
+  }
+}
+
+function requiredName(t, element) {
+  if (element.propertyName && t.isIdentifier(element.propertyName)) return element.propertyName.text;
+  if (t.isIdentifier(element.name)) return element.name.text;
+  return null;
+}
+
+function bindRequire(t, node, wanted, namespaces, members, destructuredRequires) {
+  if (!t.isVariableDeclaration(node) || !node.initializer || !fsRequireCall(t, node.initializer)) return;
+  if (t.isIdentifier(node.name)) namespaces.add(node.name.text);
+  else if (destructuredRequires && t.isObjectBindingPattern(node.name)) for (const element of node.name.elements) {
+    const imported = requiredName(t, element);
+    if (imported && wanted(imported) && t.isIdentifier(element.name)) members.set(element.name.text, imported);
+  }
+}
+
+/**
+ * The fs bindings a parsed source declares: `{ namespaces, members }`. `namespaces` holds the local names bound to
+ * a whole fs module - a default or namespace import, a `promises` named import, `const fs = require('fs')`.
+ * `members` is a Map(local name -> imported name) of named imports `wanted` accepts, plus the names of a
+ * `const {x} = require('fs')` destructure unless `destructuredRequires` is false.
+ */
+export function fsBindings(source, wanted, { destructuredRequires = true } = {}) {
+  const t = ts();
+  const namespaces = new Set();
+  const members = new Map();
+  const bind = (node) => {
+    bindImport(t, node, wanted, namespaces, members);
+    bindRequire(t, node, wanted, namespaces, members, destructuredRequires);
+    t.forEachChild(node, bind);
+  };
+  bind(source);
+  return { namespaces, members };
+}
+
+/** The fs member `callee` (a property access: `fs.X`, `fs.promises.X`) reaches through `namespaces`, or null. */
+export const fsMemberAccess = (t, callee, namespaces, wanted) => {
+  if (!t.isPropertyAccessExpression(callee) || !wanted(callee.name.text)) return null;
+  const target = callee.expression;
+  if (t.isIdentifier(target) && namespaces.has(target.text)) return callee.name.text;
+  if (t.isPropertyAccessExpression(target) && target.name.text === 'promises' && t.isIdentifier(target.expression) && namespaces.has(target.expression.text)) return callee.name.text;
+  return null;
+};
+
+/** The SourceFile of `text`; `.ts` files parse as TypeScript, everything else as JavaScript. */
+export function parseSource(text, file = 'x.mjs') {
+  const t = ts();
+  return t.createSourceFile(file, String(text), t.ScriptTarget.Latest, true, file.endsWith('.ts') ? t.ScriptKind.TS : t.ScriptKind.JS);
+}
+
+/** The 1-based line of `node` in `source`. */
+export const lineOf = (source, node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+
+/** Every module reference of a parsed file: static imports, re-exports, require('x') and import('x') with a string specifier. */
+export function moduleRefs(source) {
+  const t = ts();
+  const out = [];
+  const visit = (node) => {
+    if ((t.isImportDeclaration(node) || t.isExportDeclaration(node)) && node.moduleSpecifier && t.isStringLiteralLike(node.moduleSpecifier)) {
+      out.push({ module: node.moduleSpecifier.text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
+    } else if (t.isCallExpression(node) && node.arguments.length && t.isStringLiteralLike(node.arguments[0])) {
+      const callee = node.expression;
+      if ((t.isIdentifier(callee) && callee.text === 'require') || callee.kind === t.SyntaxKind.ImportKeyword) {
+        out.push({ module: node.arguments[0].text, line: lineOf(source, node), column: source.getLineAndCharacterOfPosition(node.getStart(source)).character + 1 });
+      }
+    }
+    t.forEachChild(node, visit);
+  };
+  visit(source);
+  return out;
+}
+
+/** The relative module references (`./x.mjs`, `../y.mjs`) of a parsed file. */
+const relativeImports = (source) => moduleRefs(source).filter((ref) => ref.module.startsWith('.')).map((ref) => ({ specifier: ref.module, line: ref.line, column: ref.column }));
+
+/**
+ * Exact relative runtime module targets from the shared AST. Tracked targets participate in the owner graph;
+ * an existing ignored generated target remains outside it. An absent target cannot silently remove an edge.
+ */
+export function relativeImportTargets(ctx, file) {
+  return relativeImports(ctx.parsed(file)).map((ref) => {
+    const to = path.posix.normalize(path.posix.join(path.posix.dirname(file), ref.specifier));
+    const tracked = ctx.fileSet.has(to);
+    const missing = ctx.read(to) == null;
+    return { ...ref, to, tracked, missing };
+  });
+}
+
+/** Adds the names `name` binds (an identifier, or the elements of a destructuring pattern) to `names`. */
+function addBoundNames(t, name, names) {
+  if (!name) return;
+  if (t.isIdentifier(name)) names.add(name.text);
+  else if (t.isObjectBindingPattern(name) || t.isArrayBindingPattern(name)) for (const el of name.elements) if (!t.isOmittedExpression(el)) addBoundNames(t, el.name, names);
+}
+
+const isNamedDeclaration = (t, node) => (t.isFunctionDeclaration(node) || t.isClassDeclaration(node) || t.isFunctionExpression(node) || t.isClassExpression(node)) && node.name;
+
+/** Adds the local name `node` binds, when it binds one, to `names`. */
+function addNodeBindings(t, node, names) {
+  if (t.isVariableDeclaration(node) || t.isParameter(node)) addBoundNames(t, node.name, names);
+  else if (isNamedDeclaration(t, node)) names.add(node.name.text);
+  else if (t.isImportClause(node) && node.name) names.add(node.name.text);
+  else if (t.isNamespaceImport(node) || t.isImportSpecifier(node)) names.add(node.name.text);
+}
+
+/** Every local name a parsed file binds: variable and parameter names (destructuring included), functions, classes, imports. */
+export function localBindings(source) {
+  const t = ts();
+  const names = new Set();
+  const visit = (node) => {
+    addNodeBindings(t, node, names);
+    t.forEachChild(node, visit);
+  };
+  visit(source);
+  return names;
+}
+
+function variableExports(t, node, source) {
+  const out = [];
+  for (const declaration of node.declarationList.declarations) {
+    if (!t.isIdentifier(declaration.name)) { out.push({ name: '<pattern>', fn: false, line: lineOf(source, declaration) }); continue; }
+    const initializer = declaration.initializer;
+    out.push({ name: declaration.name.text, fn: Boolean(initializer && (t.isArrowFunction(initializer) || t.isFunctionExpression(initializer))), line: lineOf(source, declaration) });
+  }
+  return out;
+}
+
+function exportClauseNames(t, node, source) {
+  if (!node.exportClause) return [{ name: '*', fn: false, line: lineOf(source, node) }];
+  if (t.isNamedExports(node.exportClause)) return node.exportClause.elements.map((element) => ({ name: element.name.text, fn: false, line: lineOf(source, element), reexport: true }));
+  return [{ name: node.exportClause.name.text, fn: false, line: lineOf(source, node) }];
+}
+
+function statementExports(t, node, source, exported, isDefault) {
+  if (t.isFunctionDeclaration(node) && exported(node)) return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: true, line: lineOf(source, node) }];
+  if (t.isClassDeclaration(node) && exported(node)) return [{ name: isDefault(node) ? 'default' : node.name?.text ?? 'default', fn: false, line: lineOf(source, node) }];
+  if (t.isVariableStatement(node) && exported(node)) return variableExports(t, node, source);
+  if (t.isExportDeclaration(node)) return exportClauseNames(t, node, source);
+  if (t.isExportAssignment(node)) return [{ name: 'default', fn: false, line: lineOf(source, node) }];
+  return [];
+}
+
+/** The names a parsed module exports, each with whether it is a function (declaration or an arrow/function initializer). */
+export function exportedNames(source) {
+  const t = ts();
+  const out = [];
+  const exported = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.ExportKeyword);
+  const isDefault = (node) => (t.canHaveModifiers?.(node) ? t.getModifiers(node) : node.modifiers)?.some((m) => m.kind === t.SyntaxKind.DefaultKeyword);
+  for (const node of source.statements) out.push(...statementExports(t, node, source, exported, isDefault));
+  return out;
+}

package/runtime/scripts/hfs/runtime-rules/workflow-source.mjs

@@ -0,0 +1,19 @@
+// workflow-source.mjs - what the workflow rules (ci-upload.mjs, git-triggers.mjs) share: which tracked files are CI workflows, and a workflow's
+// YAML document. A template's `{{placeholder}}` lines are blanked before the text is parsed.
+import { parseYaml } from '../../../engine/yaml.mjs';
+
+const WORKFLOW = /(?:^|\/)\.?(?:github\/)?workflows\/[^/]+\.ya?ml$/;
+
+/** The tracked workflow files of the runtime, its examples and the hfs templates (never a spec fixture under tests/). */
+const workflowFiles = (files) => files.filter((file) => WORKFLOW.test(file) && !file.startsWith('tests/'));
+
+/** The parsed workflow, or null when the text is not YAML (the other checks name that). */
+export function parseWorkflow(text) {
+  try { return parseYaml(text.replace(/^\{\{\w+\}\}\s*$/gm, '').replace(/\{\{\w+\}\}/g, 'x')); } catch { return null; }
+}
+
+/** The findings of `perFile({path, text})` over every tracked workflow `ctx` holds (ctx of scripts/hfs/runtime-check.mjs). */
+export const workflowFindings = (ctx, perFile) => workflowFiles(ctx.files).flatMap((file) => {
+  const text = ctx.read(file);
+  return text === null || text === undefined ? [] : perFile({ path: file, text });
+});

package/runtime/scripts/hfs/sealed-members.mjs

@@ -0,0 +1,101 @@
+// Names-only declarations become genuine sealed placeholders when an app or example is materialized.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { byCodeUnit } from '../lib/list.mjs';
+import { setSecretValues } from './secret-store.mjs';
+import { sealBootstrapValues } from './secret-bootstrap-crypto.mjs';
+
+const ENVIRONMENT = /^[a-z0-9][a-z0-9-]*$/u;
+const MEMBER = /^secrets\/([a-z0-9][a-z0-9-]*)(?:\.enc)?$/u;
+const KEY = /^[A-Z][A-Z0-9_]*$/u;
+
+function readDocument(file, format) {
+  if (!fs.existsSync(file)) return {};
+  const text = fs.readFileSync(file, 'utf8');
+  return format === 'json' ? JSON.parse(text) : parseYaml(text);
+}
+
+function memberOf(environment, declaration) {
+  const entry = typeof declaration === 'string' ? { where: declaration } : declaration;
+  const location = entry?.where ?? (entry?.name && `secrets/${entry.name}`);
+  const match = MEMBER.exec(location ?? '');
+  if (!ENVIRONMENT.test(environment) || !match)
+    throw new Error('sealed member declarations must use .starcistacks/<environment>/secrets/<slug>');
+  return { env: environment, slug: match[1], keys: entry.keys };
+}
+
+function rosterKeys(repoRoot, member) {
+  const file = path.join(repoRoot, '.starcistacks', member.env, 'runtime', 'env', 'KEYS.md');
+  if (!fs.existsSync(file)) return [];
+  const keys = [];
+  for (const line of fs.readFileSync(file, 'utf8').split(/\r?\n/u)) {
+    const key = /^\|\s*`([A-Z][A-Z0-9_]*)`\s*\|/u.exec(line)?.[1];
+    if (!key) continue;
+    const locations = [...line.matchAll(/(?:secrets\/|\/run\/secrets\/)([a-z0-9][a-z0-9-]*)(?:\.enc)?/gu)];
+    if (locations.some((match) => match[1] === member.slug)) keys.push(key);
+  }
+  return keys;
+}
+
+function keysOf(repoRoot, member) {
+  const declared = Array.isArray(member.keys) ? member.keys : rosterKeys(repoRoot, member);
+  const keys = declared.length ? declared : [member.slug.replaceAll('-', '_').toUpperCase()];
+  if (keys.some((key) => !KEY.test(key))) throw new Error('sealed member keys must be environment key names');
+  return [...new Set(keys)].sort(byCodeUnit);
+}
+
+function descriptorMembers(repoRoot) {
+  const stacks = path.join(repoRoot, '.starcistacks');
+  if (!fs.existsSync(stacks)) return [];
+  const members = [];
+  for (const entry of fs.readdirSync(stacks, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !ENVIRONMENT.test(entry.name)) continue;
+    const descriptor = readDocument(path.join(stacks, entry.name, 'environment.json'), 'json');
+    for (const declaration of descriptor.secrets ?? []) members.push(memberOf(entry.name, declaration));
+  }
+  return members;
+}
+
+/** Resolve public member/key names without opening any existing envelope or private identity. */
+export function declaredSealedMembers(repoRoot) {
+  const manifest = readDocument(path.join(repoRoot, '.starcistacks', 'application-stacks.yaml'), 'yaml');
+  const declarations = descriptorMembers(repoRoot);
+  for (const [environment, model] of Object.entries(manifest?.environments ?? {})) {
+    for (const declaration of model?.secrets ?? []) declarations.push(memberOf(environment, declaration));
+  }
+  const members = new Map();
+  for (const member of declarations) {
+    const id = `${member.env}/${member.slug}`;
+    members.set(id, { ...member, keys: keysOf(repoRoot, member) });
+  }
+  return [...members.values()].sort((left, right) => `${left.env}/${left.slug}`.localeCompare(`${right.env}/${right.slug}`));
+}
+
+function placeholderValue(key) {
+  const generated = randomUUID();
+  if (/DB_URL$/u.test(key)) return `postgresql://app_be:${generated}@db.invalid:5432/app`;
+  if (key.endsWith('_URL')) return `https://example.invalid/${generated}`;
+  return generated;
+}
+
+/** Create missing members for this app's recipient, preserving owner-provisioned members. */
+export function materializeDeclaredPlaceholders(repoRoot, { recipient, recipientsForFile, processEnv = process.env, sops, write } = {}) {
+  const members = [];
+  for (const member of declaredSealedMembers(repoRoot)) {
+    const relative = `.starcistacks/${member.env}/secrets/${member.slug}.enc`;
+    if (fs.existsSync(path.join(repoRoot, relative))) continue;
+    const age = recipientsForFile?.(path.join(repoRoot, relative)) ?? [recipient];
+    if (!age.length || age.some((value) => !/^age1[a-z0-9]+$/u.test(value ?? '')))
+      throw new Error('sealed placeholders require the app public age recipient');
+    if (!sops && age.length !== 1) throw new Error('multiple recipients require the standard SOPS adapter');
+    const values = Object.fromEntries(member.keys.map((key) => [key, placeholderValue(key)]));
+    const adapter = sops ?? { seal: () => sealBootstrapValues({ values, recipient: age[0] }) };
+    setSecretValues(repoRoot, { slug: member.slug, values, env: member.env }, {
+      age, processEnv, sops: adapter, write,
+    });
+    members.push(relative);
+  }
+  return { members };
+}