@starci/hfs 4.11.21 → 4.12.0

package/runtime/scripts/hfs/rules/workflow-contexts.d.mts

@@ -0,0 +1,8 @@
+import type { Finding, Parsed } from './rule-types.mjs';
+/** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
+export declare function workflowContextFindings({ path: file, text }: {
+    path: string;
+    text: string;
+}): Finding[];
+/** Judge every tracked workflow in scope at the full or lite app root, using the shared workflow selector. */
+export declare function workflowContextsFindings(ctx: Parsed): any[];

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

@@ -2,7 +2,6 @@
 import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
 import { found } from './read.mjs';
 import { appWorkflowFindings } from './app-workflow-findings.mjs';
-
 const WORKFLOW = ['github', 'inputs', 'vars'];
 const JOB_IF = ['github', 'needs', 'vars', 'inputs'];
 const JOB = [...JOB_IF, 'strategy', 'matrix'];
@@ -10,94 +9,107 @@ const JOB_ENV = [...JOB, 'secrets'];
 const EXECUTION = [...JOB_ENV, 'job', 'runner', 'env'];
 const CONTEXTS = [...EXECUTION, 'steps'];
 const JOB_KEYS = new Set(['name', 'runs-on', 'concurrency', 'strategy', 'timeout-minutes', 'continue-on-error', 'with']);
-
 /** Container and service images are chosen before a runner exists; their other properties use execution contexts. */
 function containerContexts(keys) {
-  if (keys[2] === 'services') return keys[4] === 'image' ? JOB : EXECUTION;
-  return keys.length === 3 || keys[3] === 'image' ? JOB : EXECUTION;
+    if (keys[2] === 'services')
+        return keys[4] === 'image' ? JOB : EXECUTION;
+    return keys.length === 3 || keys[3] === 'image' ? JOB : EXECUTION;
 }
-
 /** The most specific row of GitHub's Context availability table governs each descendant value. */
 function jobContexts(keys) {
-  const key = keys[2];
-  if (key === 'steps') return CONTEXTS;
-  if (key === 'if') return JOB_IF;
-  if (key === 'strategy') return JOB_IF;
-  if (key === 'env' || key === 'secrets') return JOB_ENV;
-  if (key === 'outputs') return CONTEXTS;
-  if (key === 'defaults' && keys[3] === 'run') return [...JOB, 'env'];
-  if (key === 'environment') return keys[3] === 'url' ? CONTEXTS.filter((context) => context !== 'secrets') : JOB;
-  if (key === 'container' || key === 'services') return containerContexts(keys);
-  if (JOB_KEYS.has(key)) return JOB;
-  return [];
+    const key = keys[2];
+    if (key === 'steps')
+        return CONTEXTS;
+    if (key === 'if')
+        return JOB_IF;
+    if (key === 'strategy')
+        return JOB_IF;
+    if (key === 'env' || key === 'secrets')
+        return JOB_ENV;
+    if (key === 'outputs')
+        return CONTEXTS;
+    if (key === 'defaults' && keys[3] === 'run')
+        return [...JOB, 'env'];
+    if (key === 'environment')
+        return keys[3] === 'url' ? CONTEXTS.filter((context) => context !== 'secrets') : JOB;
+    if (key === 'container' || key === 'services')
+        return containerContexts(keys);
+    if (JOB_KEYS.has(key))
+        return JOB;
+    return [];
 }
-
 /** Unlisted workflow keys admit no contexts; reusable workflow outputs alone may read jobs. */
 function allowedContexts(keys) {
-  if (keys[0] === 'jobs') return jobContexts(keys);
-  if (keys[0] === 'env') return [...WORKFLOW, 'secrets'];
-  if (keys[0] === 'run-name' || keys[0] === 'concurrency') return WORKFLOW;
-  if (keys.slice(0, 3).join('.') === 'on.workflow_call.inputs' && keys[4] === 'default') return WORKFLOW;
-  if (keys.slice(0, 3).join('.') === 'on.workflow_call.outputs' && keys[4] === 'value') return [...WORKFLOW, 'jobs'];
-  return [];
+    if (keys[0] === 'jobs')
+        return jobContexts(keys);
+    if (keys[0] === 'env')
+        return [...WORKFLOW, 'secrets'];
+    if (keys[0] === 'run-name' || keys[0] === 'concurrency')
+        return WORKFLOW;
+    if (keys.slice(0, 3).join('.') === 'on.workflow_call.inputs' && keys[4] === 'default')
+        return WORKFLOW;
+    if (keys.slice(0, 3).join('.') === 'on.workflow_call.outputs' && keys[4] === 'value')
+        return [...WORKFLOW, 'jobs'];
+    return [];
 }
-
 /** Strings and property names are not context roots; bracket access and case-insensitive roots still are. */
 function expressionContexts(expression) {
-  const unquoted = expression.replace(/'(?:[^']|'')*'/g, ' ');
-  const tokens = unquoted.match(/[A-Za-z_][\w-]*|[^\s]/g) ?? [];
-  const roots = tokens.filter((token, index) => tokens[index - 1] !== '.' &&
-    ([...CONTEXTS, 'jobs'].includes(token.toLowerCase()) || ['.', '['].includes(tokens[index + 1]))).map((token) => token.toLowerCase());
-  return [...new Set(roots)];
+    const unquoted = expression.replace(/'(?:[^']|'')*'/g, ' ');
+    const tokens = unquoted.match(/[A-Za-z_][\w-]*|[^\s]/g) ?? [];
+    const roots = tokens.filter((token, index) => tokens[index - 1] !== '.' &&
+        ([...CONTEXTS, 'jobs'].includes(token.toLowerCase()) || ['.', '['].includes(tokens[index + 1]))).map((token) => token.toLowerCase());
+    return [...new Set(roots)];
 }
-
 /** A closing delimiter inside an Actions single-quoted string cannot end an expression. */
 function expressionEnd(value, start) {
-  let quoted = false;
-  for (let index = start; index < value.length; index++) {
-    if (value[index] === "'") quoted = !quoted;
-    if (!quoted && value.slice(index, index + 2) === '}}') return index;
-  }
-  return value.length;
+    let quoted = false;
+    for (let index = start; index < value.length; index++) {
+        if (value[index] === "'")
+            quoted = !quoted;
+        if (!quoted && value.slice(index, index + 2) === '}}')
+            return index;
+    }
+    return value.length;
 }
-
 /** Read marked expressions without ambiguous regex repetition or losing delimiters inside string literals. */
 function expressions(value) {
-  const result = [];
-  const marker = /\$\{\{ __hfs_context_line_(\d+)__ /g;
-  let match;
-  while ((match = marker.exec(value)) !== null) {
-    const end = expressionEnd(value, marker.lastIndex);
-    result.push({ line: Number(match[1]), body: value.slice(marker.lastIndex, end) });
-    marker.lastIndex = end + 2;
-  }
-  return result;
+    const result = [];
+    const marker = /\$\{\{ __hfs_context_line_(\d+)__ /g;
+    let match;
+    while ((match = marker.exec(value)) !== null) {
+        const end = expressionEnd(value, marker.lastIndex);
+        result.push({ line: Number(match[1]), body: value.slice(marker.lastIndex, end) });
+        marker.lastIndex = end + 2;
+    }
+    return result;
 }
-
 /** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
 export function workflowContextFindings({ path: file, text }) {
-  const marked = text.replaceAll('${{', (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
-  const findings = [];
-  function inspect(value, keys) {
-    const allowed = allowedContexts(keys);
-    for (const { line, body } of expressions(value)) {
-      for (const context of expressionContexts(body)) {
-        if (allowed.includes(context)) continue;
-        const keyPath = keys.join('.');
-        findings.push(found('HFS_WORKFLOW_CONTEXT', file, `HFS_WORKFLOW_CONTEXT: ${file}:${line}: ${keyPath} forbids context ${context}.`, { line, keyPath, context }));
-      }
+    const marked = text.replaceAll('${{', (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
+    const findings = [];
+    function inspect(value, keys) {
+        const allowed = allowedContexts(keys);
+        for (const { line, body } of expressions(value)) {
+            for (const context of expressionContexts(body)) {
+                if (allowed.includes(context))
+                    continue;
+                const keyPath = keys.join('.');
+                findings.push(found('HFS_WORKFLOW_CONTEXT', file, `HFS_WORKFLOW_CONTEXT: ${file}:${line}: ${keyPath} forbids context ${context}.`, { line, keyPath, context }));
+            }
+        }
+    }
+    function visit(value, keys = []) {
+        if (typeof value === 'string')
+            inspect(value, keys);
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [key, member] of Object.entries(value))
+            visit(member, [...keys, key]);
     }
-  }
-  function visit(value, keys = []) {
-    if (typeof value === 'string') inspect(value, keys);
-    if (!value || typeof value !== 'object') return;
-    for (const [key, member] of Object.entries(value)) visit(member, [...keys, key]);
-  }
-  visit(parseWorkflow(marked));
-  return findings;
+    visit(parseWorkflow(marked));
+    return findings;
 }
-
 /** Judge every tracked workflow in scope at the full or lite app root, using the shared workflow selector. */
 export function workflowContextsFindings(ctx) {
-  return appWorkflowFindings(ctx, workflowContextFindings, { dedupe: true });
+    return appWorkflowFindings(ctx, workflowContextFindings, { dedupe: true });
 }

package/runtime/scripts/hfs/runtime-rules/git-triggers.d.mts

@@ -0,0 +1,6 @@
+import type { Parsed } from '../rules/rule-types.mjs';
+export declare const CODE = "CI_TRIGGERS_RELEASE_ONLY";
+/** The branch pattern of the release candidate refs (refs/heads/release/candidate-<version>), shared with the release flows. */
+export declare const CANDIDATE_BRANCHES = "release/candidate-*";
+/** CI_TRIGGERS_RELEASE_ONLY over every tracked workflow (ctx of scripts/hfs/runtime-check.mjs). */
+export declare const gitTriggerFindings: (ctx: Parsed) => any[];

package/runtime/scripts/hfs/runtime-rules/git-triggers.mjs

@@ -1,7 +1,6 @@
 // CI_TRIGGERS_RELEASE_ONLY: runtime workflows and app ci.yml may judge main; release candidates, v* tags and manual dispatch retain their scope.
 import { parseWorkflow, workflowFindings } from './workflow-source.mjs';
 import { workflowEventOptions } from '../../lib/workflow-events.mjs';
-
 export const CODE = 'CI_TRIGGERS_RELEASE_ONLY';
 const RELEASE_TAGS = 'v*';
 const RUNTIME_BRANCH = 'main';
@@ -9,53 +8,55 @@ const RUNTIME_BRANCH = 'main';
 export const CANDIDATE_BRANCHES = 'release/candidate-*';
 /** The workflows that judge an app release (every app ci.yml): they must run on the candidate refs. The runtime's own workflows judge each push to main instead. */
 const RELEASE_WORKFLOW = /(^|\/)ci\.ya?ml$/;
-
 const isReleaseTagFilter = (tags) => Array.isArray(tags) && tags.length === 1 && String(tags[0]) === RELEASE_TAGS;
 /** The branches a filter may name: main (runtime workflows and app ci.yml) and the candidate pattern. */
 const allowedBranches = (ownBranch) => (ownBranch ? [RUNTIME_BRANCH, CANDIDATE_BRANCHES] : [CANDIDATE_BRANCHES]);
 const isBranchFilter = (ownBranch, branches) => Array.isArray(branches) && branches.length > 0 && new Set(branches.map(String)).size === branches.length
-  && branches.every((branch) => allowedBranches(ownBranch).includes(String(branch)));
+    && branches.every((branch) => allowedBranches(ownBranch).includes(String(branch)));
 const namesCandidate = (branches) => Array.isArray(branches) && branches.map(String).includes(CANDIDATE_BRANCHES);
-
 const missingFilterMessage = (ownBranch) => (ownBranch
-  ? `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches\` of [${RUNTIME_BRANCH}, '${CANDIDATE_BRANCHES}'] (no other branch starts CI)`
-  : `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches: ['${CANDIDATE_BRANCHES}']\` (no other branch starts an app's CI)`);
-
+    ? `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches\` of [${RUNTIME_BRANCH}, '${CANDIDATE_BRANCHES}'] (no other branch starts CI)`
+    : `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches: ['${CANDIDATE_BRANCHES}']\` (no other branch starts an app's CI)`);
 const branchFilterMessage = (ownBranch) => (ownBranch
-  ? `\`push.branches\` may name only ${RUNTIME_BRANCH} and '${CANDIDATE_BRANCHES}', each once`
-  : `\`push.branches\` may name only '${CANDIDATE_BRANCHES}' in an example or an app template: its CI runs on the release candidate and the release tag`);
-
+    ? `\`push.branches\` may name only ${RUNTIME_BRANCH} and '${CANDIDATE_BRANCHES}', each once`
+    : `\`push.branches\` may name only '${CANDIDATE_BRANCHES}' in an example or an app template: its CI runs on the release candidate and the release tag`);
 function pushFindings({ ownBranch, config, refuse, release }) {
-  const filters = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
-  const { tags, branches } = filters;
-  const found = [];
-  if (tags === undefined && branches === undefined) found.push(refuse(missingFilterMessage(ownBranch)));
-  if (tags !== undefined && !isReleaseTagFilter(tags)) found.push(refuse(`\`push.tags\` must be exactly ['${RELEASE_TAGS}']`));
-  if (branches !== undefined && !isBranchFilter(ownBranch, branches)) found.push(refuse(branchFilterMessage(ownBranch)));
-  if (release && !namesCandidate(branches)) found.push(refuse(`\`push.branches\` must name '${CANDIDATE_BRANCHES}': starci app release push waits for the CI run of the release sha on its candidate ref`));
-  for (const other of Object.keys(filters).filter((key) => key !== 'tags' && key !== 'branches')) found.push(refuse(`\`push.${other}\` is not allowed beside the trigger filters`));
-  return found;
+    const filters = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+    const { tags, branches } = filters;
+    const found = [];
+    if (tags === undefined && branches === undefined)
+        found.push(refuse(missingFilterMessage(ownBranch)));
+    if (tags !== undefined && !isReleaseTagFilter(tags))
+        found.push(refuse(`\`push.tags\` must be exactly ['${RELEASE_TAGS}']`));
+    if (branches !== undefined && !isBranchFilter(ownBranch, branches))
+        found.push(refuse(branchFilterMessage(ownBranch)));
+    if (release && !namesCandidate(branches))
+        found.push(refuse(`\`push.branches\` must name '${CANDIDATE_BRANCHES}': starci app release push waits for the CI run of the release sha on its candidate ref`));
+    for (const other of Object.keys(filters).filter((key) => key !== 'tags' && key !== 'branches'))
+        found.push(refuse(`\`push.${other}\` is not allowed beside the trigger filters`));
+    return found;
 }
-
 function eventFindings({ event, config, ownBranch, refuse, release }) {
-  if (event === 'workflow_dispatch') return [];
-  if (event !== 'push') return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}) and workflow_dispatch may start CI`)];
-  return pushFindings({ ownBranch, config, refuse, release });
+    if (event === 'workflow_dispatch')
+        return [];
+    if (event !== 'push')
+        return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}) and workflow_dispatch may start CI`)];
+    return pushFindings({ ownBranch, config, refuse, release });
 }
-
 /** The CI_TRIGGERS_RELEASE_ONLY findings of one workflow text; a text that is not YAML yields none (the other checks name it). Runtime workflows and app ci.yml may also push on main. */
 function workflowTriggerFindings({ path: file, text }) {
-  const doc = parseWorkflow(text);
-  if (!doc || typeof doc !== 'object') return [];
-  const ownBranch = file.startsWith('.github/workflows/') || RELEASE_WORKFLOW.test(file);
-  const refuse = (why) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${why}` });
-  const on = doc.on;
-  if (on === undefined || on === null) return [refuse('the workflow has no `on` trigger block: it must declare push of tags [v*] and/or workflow_dispatch')];
-  const events = workflowEventOptions(on, String);
-  const release = !file.startsWith('.github/workflows/') && RELEASE_WORKFLOW.test(file);
-  const missingPush = release && !Object.hasOwn(events, 'push') ? [refuse(`the app release workflow must run on a push of '${CANDIDATE_BRANCHES}' and of tags [${RELEASE_TAGS}]`)] : [];
-  return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ event, config, ownBranch, refuse, release }))];
+    const doc = parseWorkflow(text);
+    if (!doc || typeof doc !== 'object')
+        return [];
+    const ownBranch = file.startsWith('.github/workflows/') || RELEASE_WORKFLOW.test(file);
+    const refuse = (why) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${why}` });
+    const on = doc.on;
+    if (on === undefined || on === null)
+        return [refuse('the workflow has no `on` trigger block: it must declare push of tags [v*] and/or workflow_dispatch')];
+    const events = workflowEventOptions(on, String);
+    const release = !file.startsWith('.github/workflows/') && RELEASE_WORKFLOW.test(file);
+    const missingPush = release && !Object.hasOwn(events, 'push') ? [refuse(`the app release workflow must run on a push of '${CANDIDATE_BRANCHES}' and of tags [${RELEASE_TAGS}]`)] : [];
+    return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ event, config, ownBranch, refuse, release }))];
 }
-
 /** CI_TRIGGERS_RELEASE_ONLY over every tracked workflow (ctx of scripts/hfs/runtime-check.mjs). */
 export const gitTriggerFindings = (ctx) => workflowFindings(ctx, workflowTriggerFindings);

package/runtime/scripts/hfs/runtime-rules/hook-shape.d.mts

@@ -0,0 +1,10 @@
+import type { Parsed } from '../rules/rule-types.mjs';
+export declare const CODE = "RT_HOOK_SHAPE";
+export declare const TEMPLATE_DIR = "packages/hfs/templates/app/hooks/husky";
+/** RT_HOOK_SHAPE over the app hook templates and tracked host guard settings (ctx of scripts/hfs/runtime-check.mjs). */
+export declare function hookShapeFindings(ctx: Parsed): {
+    code: string;
+    level: string;
+    path: string;
+    message: string;
+}[];

package/runtime/scripts/hfs/runtime-rules/hook-shape.mjs

@@ -7,67 +7,70 @@
 // Comments are not judged (the templates explain what they do not run). Pure apart from ctx.read.
 import { shellCommandSource } from '../../lib/shell-source.mjs';
 import { HOOK_INPUT_LIMITS } from '../../lib/hook-limits.mjs';
-
 export const CODE = 'RT_HOOK_SHAPE';
 export const TEMPLATE_DIR = 'packages/hfs/templates/app/hooks/husky';
 const PRE_COMMIT = `${TEMPLATE_DIR}/pre-commit`;
 const PRE_PUSH = `${TEMPLATE_DIR}/pre-push`;
 const HOST_SETTINGS = '.claude/settings.json';
 const GUARD_LIMITS = 'modules/kernel/hook-input.yaml';
-
 const PRE_COMMIT_FORBIDDEN = [
-  [/\btypecheck\b/, 'a typecheck'],
-  [/\btest:|\bnpm\s+(?:run\s+)?test\b|\bjest\b|\bvitest\b|\bspecs?\b/, 'a test run'],
+    [/\btypecheck\b/, 'a typecheck'],
+    [/\btest:|\bnpm\s+(?:run\s+)?test\b|\bjest\b|\bvitest\b|\bspecs?\b/, 'a test run'],
 ];
 const PRE_PUSH_FORBIDDEN = [
-  [/\bnpm\s+(?:run\s+)?test\b|\btest:|\bjest\b|\bvitest\b/, 'a test run'],
-  [/\btypecheck\b/, 'a typecheck'],
-  [/\blint\b/, 'a lint run'],
+    [/\bnpm\s+(?:run\s+)?test\b|\btest:|\bjest\b|\bvitest\b/, 'a test run'],
+    [/\btypecheck\b/, 'a typecheck'],
+    [/\blint\b/, 'a lint run'],
 ];
 const PRE_PUSH_MARKERS = ["node --input-type=module -e", "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'", 'process.exit(await main())', 'node node_modules/starci-harness/dist/main.js deps check'];
-
 const finding = (file, message) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${message}` });
-
 /** The RT_HOOK_SHAPE findings of one hook template: `name` is 'pre-commit' or 'pre-push', `text` its content. */
 function fileHookShapeFindings({ path: file, name, text }) {
-  const body = shellCommandSource(text);
-  const found = [];
-  const forbidden = name === 'pre-commit' ? PRE_COMMIT_FORBIDDEN : PRE_PUSH_FORBIDDEN;
-  for (const [pattern, what] of forbidden) {
-    if (pattern.test(body)) found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate runs ${what}; it must use the bundled push policy alone`));
-  }
-  if (name === 'pre-push') {
-    const missing = PRE_PUSH_MARKERS.filter((marker) => !body.includes(marker));
-    if (missing.length) {
-      const markers = missing.map((m) => `\`${m}\``).join(', ');
-      found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy and the dependency push gate`));
+    const body = shellCommandSource(text);
+    const found = [];
+    const forbidden = name === 'pre-commit' ? PRE_COMMIT_FORBIDDEN : PRE_PUSH_FORBIDDEN;
+    for (const [pattern, what] of forbidden) {
+        if (pattern.test(body))
+            found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate runs ${what}; it must use the bundled push policy alone`));
     }
-  }
-  return found;
+    if (name === 'pre-push') {
+        const missing = PRE_PUSH_MARKERS.filter((marker) => !body.includes(marker));
+        if (missing.length) {
+            const markers = missing.map((m) => `\`${m}\``).join(', ');
+            found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy and the dependency push gate`));
+        }
+    }
+    return found;
 }
-
 /** Guard hooks finish inside the host timeout even when input, verdict, tree cleanup and both writes exhaust their budgets. */
 function guardTimeoutFindings(ctx) {
-  if (!ctx.fileSet.has(HOST_SETTINGS)) return [];
-  const limits = HOOK_INPUT_LIMITS;
-  const budget = limits.minInputWindowMs + limits.verdictTimeoutMs + limits.teardownTimeoutMs + 2 * limits.outputTimeoutMs;
-  const found = budget < limits.hookTimeoutSeconds * 1000 ? [] : [finding(GUARD_LIMITS, 'the complete guard lifetime must be shorter than the host hook timeout')];
-  let settings;
-  try { settings = JSON.parse(ctx.read(HOST_SETTINGS)); }
-  catch { return [...found, finding(HOST_SETTINGS, 'the guard hook settings must be readable JSON')]; }
-  const hooks = (settings?.hooks?.PreToolUse ?? []).flatMap((entry) => entry.hooks ?? []);
-  for (const hook of hooks) {
-    if (!/\bguard\s+(?:command|seat-tools)\b/.test(String(hook.command ?? ''))) continue;
-    if (hook.timeout !== limits.hookTimeoutSeconds) found.push(finding(HOST_SETTINGS, `the guard hook timeout must match ${GUARD_LIMITS} hookTimeoutSeconds`));
-  }
-  return found;
+    if (!ctx.fileSet.has(HOST_SETTINGS))
+        return [];
+    const limits = HOOK_INPUT_LIMITS;
+    const budget = limits.minInputWindowMs + limits.verdictTimeoutMs + limits.teardownTimeoutMs + 2 * limits.outputTimeoutMs;
+    const found = budget < limits.hookTimeoutSeconds * 1000 ? [] : [finding(GUARD_LIMITS, 'the complete guard lifetime must be shorter than the host hook timeout')];
+    let settings;
+    try {
+        settings = JSON.parse(ctx.read(HOST_SETTINGS));
+    }
+    catch {
+        return [...found, finding(HOST_SETTINGS, 'the guard hook settings must be readable JSON')];
+    }
+    const hooks = (settings?.hooks?.PreToolUse ?? []).flatMap((entry) => entry.hooks ?? []);
+    for (const hook of hooks) {
+        if (!/\bguard\s+(?:command|seat-tools)\b/.test(String(hook.command ?? '')))
+            continue;
+        if (hook.timeout !== limits.hookTimeoutSeconds)
+            found.push(finding(HOST_SETTINGS, `the guard hook timeout must match ${GUARD_LIMITS} hookTimeoutSeconds`));
+    }
+    return found;
 }
-
 /** RT_HOOK_SHAPE over the app hook templates and tracked host guard settings (ctx of scripts/hfs/runtime-check.mjs). */
 export function hookShapeFindings(ctx) {
-  return [...guardTimeoutFindings(ctx), ...[['pre-commit', PRE_COMMIT], ['pre-push', PRE_PUSH]].flatMap(([name, file]) => {
-    if (!ctx.fileSet.has(file)) return [];
-    const text = ctx.read(file);
-    return text === null || text === undefined ? [] : fileHookShapeFindings({ path: file, name, text });
-  })];
+    return [...guardTimeoutFindings(ctx), ...[['pre-commit', PRE_COMMIT], ['pre-push', PRE_PUSH]].flatMap(([name, file]) => {
+            if (!ctx.fileSet.has(file))
+                return [];
+            const text = ctx.read(file);
+            return text === null || text === undefined ? [] : fileHookShapeFindings({ path: file, name, text });
+        })];
 }

package/runtime/scripts/hfs/runtime-rules/source-ast.d.mts

@@ -0,0 +1,39 @@
+import type { Parsed } from '../rules/rule-types.mjs';
+/** The TypeScript compiler, loaded once from the runtime's own dependencies. */
+export declare const ts: () => any;
+/**
+ * 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 declare function fsBindings(source: Parsed, wanted: Parsed, { destructuredRequires }?: {
+    destructuredRequires?: boolean | undefined;
+}): {
+    namespaces: Set<unknown>;
+    members: Map<any, any>;
+};
+/** The fs member `callee` (a property access: `fs.X`, `fs.promises.X`) reaches through `namespaces`, or null. */
+export declare const fsMemberAccess: (t: Parsed, callee: Parsed, namespaces: Parsed, wanted: Parsed) => any;
+/** The SourceFile of `text`; `.ts` files parse as TypeScript, everything else as JavaScript. */
+export declare function parseSource(text: string, file?: string): any;
+/** The 1-based line of `node` in `source`. */
+export declare const lineOf: (source: Parsed, node: Parsed) => any;
+/** Every module reference of a parsed file: static imports, re-exports, require('x') and import('x') with a string specifier. */
+export declare function moduleRefs(source: Parsed): any[];
+/**
+ * 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 declare function relativeImportTargets(ctx: Parsed, file: string): {
+    to: string;
+    tracked: any;
+    missing: boolean;
+    specifier: any;
+    line: any;
+    column: any;
+}[];
+/** Every local name a parsed file binds: variable and parameter names (destructuring included), functions, classes, imports. */
+export declare function localBindings(source: Parsed): Set<unknown>;
+/** The names a parsed module exports, each with whether it is a function (declaration or an arrow/function initializer). */
+export declare function exportedNames(source: Parsed): any[];