@starci/hfs 4.7.12 → 4.7.13

package/release/lint-report.mjs

@@ -0,0 +1,52 @@
+// lint-report.mjs - the external issues report the release gate's sonar row produces before it runs the scanner.
+// The app declares `sonar.externalIssuesReportPaths=reports/lint.sonar.json`; the managed CI makes it with `lint --side <side> --sonar reports/lint.<side>.sonar.json`
+// per lint matrix side and a "merge Sonar lint reports" step. This module does the same locally, through the same process seam as every gate
+// (an argument array through ctx.spawn, never a shell). The merge below is the one in packages/hfs/sync/ci-commands.mjs (sonarMergeSteps): keep them identical.
+import fs from 'node:fs';
+import path from 'node:path';
+import { firstLine, tool } from '../stack/context.mjs';
+
+const LINT_SIDES = ['be', 'fe'];
+const MERGED_REPORT = 'reports/lint.sonar.json';
+const sideReport = (side) => `reports/lint.${side}.sonar.json`;
+
+/** CI merge: rules unique by id (last one wins, first position kept), issues concatenated in side order. */
+function mergeSonarReports(reports) {
+  const rules = [...new Map(reports.flatMap((report) => report.rules).map((rule) => [rule.id, rule])).values()];
+  const issues = reports.flatMap((report) => report.issues);
+  return { rules, issues };
+}
+
+/** The sides the app has: a be/ or fe/ folder beside the app root. */
+const sidesOf = (root) => LINT_SIDES.filter((side) => fs.existsSync(path.join(root, side)));
+
+/**
+ * Runs `starci app lint --side <side> --sonar <file>` for every side the app has, then writes reports/lint.sonar.json.
+ * `launch` turns an argv into [command, args] for the platform. Returns { pass, text }: the honest log of every lint run and the verdict.
+ * A lint that exits non-zero (findings or error) or writes no report fails the row; nothing is skipped.
+ */
+export function produceLintReports(ctx, { launch, platform, env }) {
+  const sides = sidesOf(ctx.cwd);
+  const out = [];
+  if (sides.length === 0) return { pass: false, text: `no be/ or fe/ side in ${ctx.cwd}: cannot produce ${MERGED_REPORT}\n` };
+  fs.mkdirSync(path.join(ctx.cwd, 'reports'), { recursive: true });
+  for (const side of sides) {
+    const file = path.join(ctx.cwd, sideReport(side));
+    fs.rmSync(file, { force: true });
+    const argv = ['npx', 'starci', 'app', 'lint', '--side', side, '--sonar', sideReport(side)];
+    const [command, args] = launch(argv, platform);
+    out.push(`$ ${argv.join(' ')}\n`);
+    const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
+    out.push(`${run.stdout ?? ''}${run.stderr ?? ''}`);
+    if (run.error) return { pass: false, text: `${out.join('')}\nlint ${side} cannot run (${run.error.message})\n` };
+    if (run.status !== 0) return { pass: false, text: `${out.join('')}\nlint ${side} failed: exit ${run.status}; the scanner was not run\n` };
+    if (!fs.existsSync(file)) return { pass: false, text: `${out.join('')}\nlint ${side} wrote no ${sideReport(side)}; the scanner was not run\n` };
+  }
+  try {
+    const reports = sides.map((side) => JSON.parse(fs.readFileSync(path.join(ctx.cwd, sideReport(side)), 'utf8')));
+    fs.writeFileSync(path.join(ctx.cwd, MERGED_REPORT), `${JSON.stringify(mergeSonarReports(reports), null, 2)}\n`);
+  } catch (error) {
+    return { pass: false, text: `${out.join('')}\ncannot merge the side reports: ${firstLine(error.message)}\n` };
+  }
+  return { pass: true, text: `${out.join('')}\nwrote ${MERGED_REPORT} from ${sides.map(sideReport).join(', ')}\n\n` };
+}

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.18
+    version: 3.4.20
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.18
+    version: 8.4.19
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.12
+    version: 1.7.13
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.12
+    version: 4.7.13
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -27,7 +27,7 @@ defaults:
 # The steps that need a raised Node heap on the GitHub runner, matched on their `run` text, and the least heap they must declare in NODE_OPTIONS.
 heap:
   minMiB: 6144
-  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app check --coverage-from']
+  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app check --coverage-from', 'npm run db:lint']
 
 items:
   - id: candidate-trigger

package/runtime/scripts/hfs/architecture/canon-clones.mjs

@@ -106,7 +106,7 @@ function queueMethods(env, declaration, constructor, excluded) {
     && decoratorsHave(env, parameter, 'InjectQueueOutbox', '@modules/platform/queue'));
   if (!outbox || !env.ts.isIdentifier(outbox.name)) return;
   for (const method of declaration.members) {
-    if (!env.ts.isMethodDeclaration(method) || !method.body || method.body.statements.length !== 1) continue;
+    if (!env.ts.isMethodDeclaration(method) || method.body?.statements.length !== 1) continue;
     const call = statementCall(env.ts, method.body.statements[0]);
     if (call && env.ts.isCallExpression(call) && receiverMember(env.ts, call) === outbox.name.text && call.expression.name.text === 'write'
       && call.arguments.length === 3 && call.arguments.every(argument => mapping(env, argument))) excluded.add(method);

package/runtime/scripts/hfs/architecture/i18n-keys.mjs

@@ -62,11 +62,13 @@ function catalogsPerApp(config, graph) {
 
 /** Each interpolation can fill part or all of a segment; the template's static fragments keep their literal spelling. */
 function templatePatternOf(node) {
-  return [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.').map(segment => {
-    if (!segment.includes('\u0000')) return segment;
+  const pattern = [];
+  for (const segment of [node.head.text, ...node.templateSpans.map(span => span.literal.text)].join('\u0000').split('.')) {
+    if (!segment.includes('\u0000')) { pattern.push(segment); continue; }
     const parts = segment.split('\u0000');
-    return parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su');
-  });
+    pattern.push(parts.every(part => part === '') ? '*' : new RegExp(`^${parts.map((part) => escapeRegExp(part)).join('.*')}$`, 'su'));
+  }
+  return pattern;
 }
 
 function patternsOf(ts, files) {

package/runtime/scripts/hfs/architecture/transport-owner.mjs

@@ -94,7 +94,7 @@ function moduleSpecifierOf(ts, node) {
 function isApolloClientConstruction(ts, kit, checker, node) {
   if (!ts.isNewExpression(node)) return false;
   const binding = kit.importBinding(checker, node.expression);
-  return Boolean(binding && binding.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
+  return Boolean(binding?.name === 'ApolloClient' && binding.module.startsWith('@apollo/client'));
 }
 
 function inspectLibraryImport({ ts, file, node, transport, report }) {

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -60,7 +60,10 @@ export function qualityServices(doc, { example = false } = {}) {
 /** Enumerate a missing directory as empty; all filesystem access uses the caller's injected synchronous seam. */
 function entries(dir, fs) {
   try { return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
-  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
 }
 
 /** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
@@ -70,7 +73,7 @@ export function sealedKeyNames(root, { fs }) {
     for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && entry.name.endsWith('.enc'))) {
       const file = `.starcistacks/${env.name}/secrets/${member.name}`;
       const source = fs.readFileSync(path.join(root, file), 'utf8');
-      const dotenv = [...source.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
+      const dotenv = [...source.matchAll(/^([A-Za-z_]\w*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
       let keys = dotenv;
       if (!dotenv.length) {
         const doc = parseYaml(source);

package/runtime/scripts/hfs/db-baseline-verb.mjs

@@ -87,7 +87,7 @@ function baselinePlan(root, opts, now) {
   if (!active.length) throw new DbVerbError('baseline requires an existing active migration chain');
   const archived = dbSqlFiles(root, MIGRATIONS_ARCHIVE_DIR);
   const oldStamps = [...active, ...archived].map((entry) => entry.stamp);
-  const last = oldStamps.sort((left, right) => left.localeCompare(right)).at(-1);
+  const last = oldStamps.toSorted((left, right) => left.localeCompare(right)).at(-1);
   const stamp = opts.stamp ?? now().toISOString().replace(/\D/g, '').slice(0, 14);
   if (!/^\d{14}$/.test(stamp) || migrationStamp(stamp) === null || stamp <= last) throw new DbVerbError('--stamp must be a valid UTC version after the archive boundary');
   const file = `${MIGRATIONS_DIR}/${stamp}_baseline.sql`;
@@ -225,7 +225,10 @@ function extensionDeclaration(stmt, sql, extensions) {
 
 function baselineStatement(state, stmt, sql) {
   if (roleDeclaration(stmt, sql, state.roles) || extensionDeclaration(stmt, sql, state.extensions)) return;
-  if (stmt.DropRoleStmt) { for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename); return; }
+  if (stmt.DropRoleStmt) {
+    for (const role of stmt.DropRoleStmt.roles ?? []) state.roles.delete(role.RoleSpec?.rolename);
+    return;
+  }
   if (stmt.GrantRoleStmt || stmt.AlterExtensionStmt || stmt.AlterExtensionContentsStmt || /^OBJECT_ROLE$/.test(stmt.RenameStmt?.renameType ?? '')) throw new DbVerbError('baseline cannot reconstruct role membership, role renames or extension alterations');
   if (dataMutation(stmt) || sourceExecution(stmt)) throw new DbVerbError('baseline cannot reconstruct migration-owned data changes or custom execution from a schema-only dump');
   const node = Object.values(stmt)[0];

package/runtime/scripts/hfs/doc-commands.mjs

@@ -29,7 +29,8 @@ const inner = (t) => t.replace(/^<|>$/g, '');
 
 // ---- extraction -----------------------------------------------------------------------------------------------
 
-const COMMAND_AT = /(?<![\w@./:-])(?:npx\s+starci|npm\s+run\s+starci(?:\s+--silent)?(?:\s+--)?|starci)(?![\w@./-])(?=\s|$)/g;
+const COMMAND_FORM = /npx\s+starci|npm\s+run\s+starci(?:\s+--silent)?(?:\s+--)?|starci/;
+const COMMAND_AT = new RegExp(String.raw`(?<![\w@./:-])(?:${COMMAND_FORM.source})(?![\w@./-])(?=\s|$)`, 'g');
 const FENCE = /^\s*(?:[-*>|]\s*)?```/;
 const SCRIPT_COMMENT = /^\s*(?:\/\/|\*|\/\*)/;
 const CONTINUED = /\\\s*$/;

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -21,7 +21,10 @@ const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'fail
 const CASE_KEYS = new Set(['id', 'date', 'source', 'ruling', 'quote', 'supersedes', 'status', 'staleWhen', 'amendedBy']);
 const CASE_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions', 'editionWhy']);
-const CASE_REFERENCE = /^(?:case-[1-9][0-9]*|(?:ruling:)?R[0-9]{2,3}(?:\/case-[1-9][0-9]*)?|owner:[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
+const CASE_ID = /case-[1-9]\d*/;
+const RULING_REFERENCE = new RegExp(String.raw`(?:ruling:)?R\d{2,3}(?:/${CASE_ID.source})?`);
+const OWNER_REFERENCE = /owner:[a-z][a-z0-9]*(?:-[a-z0-9]+)*/;
+const CASE_REFERENCE = new RegExp(`^(?:${CASE_ID.source}|${RULING_REFERENCE.source}|${OWNER_REFERENCE.source})$`);
 const EVIDENCE_KEYS = new Set(['path', 'edition', 'editions']);
 const PROOF_KEYS = new Set([...EVIDENCE_KEYS, 'codes', 'fixtures']);
 const WITNESS_KEYS = new Set(['edition', 'base', 'mutate', 'expect']);
@@ -191,7 +194,7 @@ function checkRuleCases(rule, label, bad) {
     const at = `${label}.cases[${index}]`;
     if (!isPlainObject(item)) { bad.push(`${at} is not a map`); return; }
     for (const key of Object.keys(item)) if (!CASE_KEYS.has(key)) bad.push(`${at} has unknown key ${key}`);
-    if (typeof item.id !== 'string' || !/^case-[1-9][0-9]*$/.test(item.id) || ids.has(item.id)) bad.push(`${at}.id must be a unique case-N`);
+    if (typeof item.id !== 'string' || !/^case-[1-9]\d*$/.test(item.id) || ids.has(item.id)) bad.push(`${at}.id must be a unique case-N`);
     ids.add(item.id);
     if (typeof item.date !== 'string' || !CASE_DATE.test(item.date)) bad.push(`${at}.date must be YYYY-MM-DD`);
     if (item.source !== 'owner') bad.push(`${at}.source must be owner`);

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -12,7 +12,6 @@ import { found } from './read.mjs';
 export const HFS_COVERAGE_BELOW = 'HFS_COVERAGE_BELOW';
 const METRICS = ['lines', 'functions', 'branches'];
 const SUMMARY = { LF: ['lines', 'found'], LH: ['lines', 'hit'], FNF: ['functions', 'found'], FNH: ['functions', 'hit'], BRF: ['branches', 'found'], BRH: ['branches', 'hit'] };
-const SOURCE = /\.ts$/;
 const SPEC = /(?:\.(?:spec|test)|-spec)\.ts$/;
 const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
 const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
@@ -66,7 +65,10 @@ function parseLcov(text) {
   const records = [];
   const problems = [];
   let current = null;
-  const flush = () => { if (current) records.push(current); current = null; };
+  const flush = () => {
+    if (current) records.push(current);
+    current = null;
+  };
   for (const [index, raw] of String(text).replace(/^\uFEFF/, '').split(/\r?\n/).entries()) {
     const line = raw.trim();
     if (!line) continue;
@@ -102,7 +104,7 @@ function inventory({ files, all, repo, manifest }) {
   const scope = coverageScope(effective, repo.providers ?? repo.sides?.be?.providers ?? []);
   const roots = scope.roots.map((dir) => globExpression(`${dir}**`));
   const excludes = scope.excludes.map((dir) => globExpression(`${dir}**`));
-  const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && SOURCE.test(file) && !SPEC.test(file)).sort(byCodeUnit);
+  const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && file.endsWith('.ts') && !SPEC.test(file)).sort(byCodeUnit);
   const measured = [];
   const unmeasured = [];
   for (const file of candidates) {

package/runtime/scripts/hfs/rules/database-access.mjs

@@ -74,7 +74,7 @@ async function principalHelpers(analyses) {
     try { bodies.push({ name: fn.name, ast: await parseSql(body) }); } catch { /* PL/pgSQL safety is checked separately. */ }
   });
   const helpers = new Set();
-  for (let pass = 0; pass < bodies.length; pass += 1) {
+  for (let remaining = bodies.length; remaining > 0; remaining -= 1) {
     for (const body of bodies) if (hasPrincipal(body.ast, helpers)) helpers.add(body.name);
   }
   return helpers;

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -13,7 +13,10 @@ import { fileURLToPath } from 'node:url';
 import { loadTypescript } from '../../lib/package-at.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*|contract_[a-z0-9]+(?:[-_][a-z0-9]+)*|[a-z0-9]+(?:-[a-z0-9]+)*_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*)\.sql$/;
+const MIGRATION_PLAIN = /[a-z0-9]+(?:-[a-z0-9]+)*/;
+const MIGRATION_CONTRACT_TAIL = /contract_[a-z0-9]+(?:[-_][a-z0-9]+)*/;
+const MIGRATION_SLUG = [MIGRATION_PLAIN.source, MIGRATION_CONTRACT_TAIL.source, `${MIGRATION_PLAIN.source}_${MIGRATION_CONTRACT_TAIL.source}`].join('|');
+const MIGRATION_NAME = new RegExp(String.raw`^(\d{14})_(${MIGRATION_SLUG})\.sql$`);
 export const isMigrationName = (name) => MIGRATION_NAME.test(name);
 const RESTAMP_HEADER = /^-- starci:restamp (\d{14}) (\d{14})(?:\r?\n|$)/;
 const withoutRestampHeader = (text) => text?.replace(RESTAMP_HEADER, '') ?? null;
@@ -227,7 +230,11 @@ export function databaseSqlTokens(text) {
   let index = 0;
   let line = 1;
   while (index < text.length) {
-    if (/\s/.test(text[index])) { if (text[index] === '\n') line += 1; index += 1; continue; }
+    if (/\s/.test(text[index])) {
+      if (text[index] === '\n') line += 1;
+      index += 1;
+      continue;
+    }
     const end = commentEnd(text, index);
     if (end !== null) { line += text.slice(index, end).split('\n').length - 1; index = end; continue; }
     const token = sqlTokenAt(text, index);
@@ -243,7 +250,10 @@ export function databaseSqlStatements(tokens) {
   const statements = [];
   let current = [];
   for (const token of tokens) {
-    if (token.t === 'punct' && token.v === ';') { if (current.length) statements.push(current); current = []; }
+    if (token.t === 'punct' && token.v === ';') {
+      if (current.length) statements.push(current);
+      current = [];
+    }
     else current.push(token);
   }
   if (current.length) statements.push(current);

package/runtime/scripts/hfs/rules/database-plpgsql.mjs

@@ -290,7 +290,7 @@ async function functionFindings(file, fn, facts, exposed) {
 
 function alteredDefinerFindings(file, alter, facts, exposed) {
   if (!alter.securityDefiner) return [];
-  const created = facts.functions.filter((fn) => fn.index < alter.index && matchesAlter(fn, alter)).at(-1);
+  const created = facts.functions.findLast((fn) => fn.index < alter.index && matchesAlter(fn, alter));
   const node = created?.node ?? { func: alter.node.func };
   const fn = { ...alter, node, altered: true, originIndex: created?.index ?? -1 };
   return definerDeclarationFindings(file, fn, facts, exposed, true);

package/runtime/scripts/hfs/rules/database-queues.mjs

@@ -104,7 +104,7 @@ function inspectDo(state, node, file) {
   const option = (key) => (node.args ?? []).find((item) => item.DefElem?.defname === key)?.DefElem?.arg?.String?.sval;
   const tree = plpgsqlTree(option('as') ?? '');
   walk(tree, (item) => {
-    if (item.PLpgSQL_expr && item.PLpgSQL_expr.parseMode === 0) inspectCalls(state, sqlTree(item.PLpgSQL_expr.query), file, true);
+    if (item.PLpgSQL_expr?.parseMode === 0) inspectCalls(state, sqlTree(item.PLpgSQL_expr.query), file, true);
     if (item.PLpgSQL_stmt_dynexecute) {
       const expression = sqlTree(`select ${item.PLpgSQL_stmt_dynexecute.query?.PLpgSQL_expr?.query ?? ''}`);
       dynamicOwnership(state, expression, file, true);
@@ -128,7 +128,7 @@ function grantCheck(state, node, file) {
 function recordGrant(state, node, file, executed) {
   state.grants.push({ node, file, created: new Map(state.created), executed });
   const grant = node.GrantStmt;
-  if (!executed || !grant || grant.objtype !== 'OBJECT_TABLE' || grant.targtype !== 'ACL_TARGET_OBJECT') return;
+  if (!executed || grant?.objtype !== 'OBJECT_TABLE' || grant.targtype !== 'ACL_TARGET_OBJECT') return;
   if (!(grant.grantees ?? []).some((item) => item.RoleSpec?.rolename === state.appRole)) return;
   const privileges = grant.privileges?.map((item) => item.AccessPriv?.priv_name).filter(Boolean) ?? TABLE_PRIVILEGES;
   for (const object of grant.objects ?? []) {

package/runtime/scripts/hfs/rules/deploy-scan.mjs

@@ -8,17 +8,61 @@ const DEPLOY = /(?:^|\/)deploy\//;
 const SCRIPT = /(?:^|\/)scripts\//;
 const COMPOSE = /(?:^|\/)(?:docker-)?compose(?:[.-][^/]*)?\.ya?ml$/;
 const DOCKERFILE = /(?:^|\/)Dockerfile(?:\.[^/]*)?$/;
-const CREDENTIAL_FILE = /(?:(?:^|\/)(?:secrets?\.env(?:\.[^/]*)?|\.env(?:\.[^/]*)?|secrets\/))|(?:\.enc$)/i;
-const HOST_CRON = /\b(?:crontab|anacron|crond|supercronic)\b|\/etc\/cron(?:\b|[./])|\bcron\.d\b|\/var\/spool\/cron\b|@(?:reboot|yearly|annually|monthly|weekly|daily|midnight|hourly)\b|\b[\w.@-]+\.timer\b|\bOn(?:Calendar|BootSec|UnitActiveSec|ActiveSec)\s*=|(?:^|[\s;|&"'])at\s+(?:(?:-[a-z]+\s+)*)((?:-[ft]\b)|now\b|tomorrow\b|\d{1,2}:\d{2}\b|midnight\b|noon\b)/im;
+const CREDENTIAL_FILE_PARTS = [/(?:^|\/)secrets?\.env(?:\.[^/]*)?/, /(?:^|\/)\.env(?:\.[^/]*)?/, /(?:^|\/)secrets\//, /\.enc$/];
+const CREDENTIAL_FILE = new RegExp(CREDENTIAL_FILE_PARTS.map((part) => part.source).join('|'), 'i');
+const AT_JOB_ARGUMENT = /-[ft]\b|now\b|tomorrow\b|\d{1,2}:\d{2}\b|midnight\b|noon\b/.source;
+const HOST_CRON_PARTS = [
+  /\b(?:crontab|anacron|crond|supercronic)\b/,
+  /\/etc\/cron(?:\b|[./])/,
+  /\bcron\.d\b/,
+  /\/var\/spool\/cron\b/,
+  /@(?:reboot|yearly|annually|monthly|weekly|daily|midnight|hourly)\b/,
+  /\b[\w.@-]+\.timer\b/,
+  /\bOn(?:Calendar|BootSec|UnitActiveSec|ActiveSec)\s*=/,
+  new RegExp(String.raw`(?:^|[\s;|&"'])at\s+(?:-[a-z]+\s+)*(?:${AT_JOB_ARGUMENT})`),
+];
+const HOST_CRON = new RegExp(HOST_CRON_PARTS.map((part) => part.source).join('|'), 'im');
 const HOST_CRON_PATH = /(?:^|\/)(?:crontab(?:$|\/)|cron\.d(?:\/|$)|[^/]+\.(?:timer|crontab)$)/;
 const CRON_NUMERIC_FIELD = /^[\d*,/-]+$/;
 const CRON_NAMED_FIELD = /^[\w*,/-]+$/;
-const CRON_CONTAINER = /\bimage\s*:\s*["']?(?:[^\s"']*\/)?(?:cron|crond|supercronic|ofelia)(?=[:@\s"']|$)|\b(?:command|entrypoint)\s*:[^\n]*\b(?:cron|crond|supercronic)\b/i;
-const SLEEP_LOOP = /\b(?:while\s+(?:true|:|\[\s*1\s*\])|for\s*\(\(\s*;\s*;\s*\)\))\s*[;\n][\s\S]{0,4000}?\bsleep\s+/i;
+const CRON_CONTAINER_PARTS = [
+  /\bimage\s*:\s*["']?(?:[^\s"']*\/)?(?:cron|crond|supercronic|ofelia)(?=[:@\s"']|$)/,
+  /\b(?:command|entrypoint)\s*:[^\n]*\b(?:cron|crond|supercronic)\b/,
+];
+const CRON_CONTAINER = new RegExp(CRON_CONTAINER_PARTS.map((part) => part.source).join('|'), 'i');
+const SLEEP_LOOP_HEAD_PARTS = [/while\s+(?:true|:|\[\s*1\s*\])/, /for\s*\(\(\s*;\s*;\s*\)\)/];
+const SLEEP_LOOP_HEAD = new RegExp(String.raw`\b(?:${SLEEP_LOOP_HEAD_PARTS.map((part) => part.source).join('|')})`, 'gi');
+const SLEEP_LOOP_BREAK = /[^\S\n]*[;\n]/y;
+const SLEEP_LOOP_SLEEP = /\bsleep\s+/gi;
+const SLEEP_LOOP_REACH = 4000;
+/** An endless-loop head, a statement break, then a `sleep` within SLEEP_LOOP_REACH characters: searched in steps so no regex backtracks across the pair. */
+const SLEEP_LOOP = {
+  test(text) {
+    for (const head of text.matchAll(SLEEP_LOOP_HEAD)) {
+      SLEEP_LOOP_BREAK.lastIndex = head.index + head[0].length;
+      if (!SLEEP_LOOP_BREAK.test(text)) continue;
+      SLEEP_LOOP_SLEEP.lastIndex = SLEEP_LOOP_BREAK.lastIndex;
+      const sleep = SLEEP_LOOP_SLEEP.exec(text);
+      if (sleep && sleep.index - SLEEP_LOOP_BREAK.lastIndex <= SLEEP_LOOP_REACH) return true;
+    }
+    return false;
+  },
+};
 const INLINE_NODE = /\bnode\b[^\n;&|]*?\s(?:-(?:e|p|pe)\b|--(?:eval|print)(?:\s|=))/;
-const INLINE_SQL_ACTION = /\b(?:insert\s+into|update\s+[\w."']+\s+set|delete\s+from|create\s+(?:table|function|view)|alter\s+table|truncate\s+(?:table\s+)?[\w."'])\b/i;
+const INLINE_SQL_ACTION_PARTS = [
+  /insert\s+into/,
+  /update\s+[\w."']+\s+set/,
+  /delete\s+from/,
+  /create\s+(?:table|function|view)/,
+  /alter\s+table/,
+  /truncate\s+(?:table\s+)?[\w."']/,
+];
+const INLINE_SQL_ACTION = new RegExp(String.raw`\b(?:${INLINE_SQL_ACTION_PARTS.map((part) => part.source).join('|')})\b`, 'i');
 const REMOTE_SHELL = /\b(?:curl|wget)\b[^|\n]*\|\s*(?:sudo\s+)?(?:ba|da|z)?sh\b/i;
-const COMPOSE_COMMAND = /\bdocker(?:\s+(?:--(?:context|host)(?:\s+|=)\S+|-H\s+\S+))*\s+compose\b[^\n;&|]*|\bdocker-compose\b[^\n;&|]*/g;
+const DOCKER_GLOBAL_OPTION = /(?:--(?:context|host)(?:\s+|=)|-H\s+)\S+/.source;
+const DOCKER_COMPOSE_COMMAND = new RegExp(String.raw`\bdocker(?:\s+${DOCKER_GLOBAL_OPTION})*\s+compose\b[^\n;&|]*`).source;
+const DOCKER_COMPOSE_V1_COMMAND = /\bdocker-compose\b[^\n;&|]*/.source;
+const COMPOSE_COMMAND = new RegExp(`${DOCKER_COMPOSE_COMMAND}|${DOCKER_COMPOSE_V1_COMMAND}`, 'g');
 const COMPOSE_OPTIONS = new Set(['-f', '--file', '-p', '--project-name', '--project-directory', '--env-file', '--profile', '--parallel', '--ansi', '--progress']);
 const DEV = /(?:^|[\s/._="'-])(?:dev|development|local)(?=$|[\s/._"'-])/i;
 const NON_DEV = /(?:^|[\s/._="'-])(?:prod|production|staging|stage|vps|preview)(?=$|[\s/._"'-])/i;

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

@@ -59,7 +59,17 @@ const validPermissions = (value) => record(value) || value === 'read-all' || val
 const validConcurrency = (value) => nonempty(value) || (record(value) && nonempty(value.group));
 const deployName = (value) => !/authorize[\s_.-]+deploy[\s_.-]+key/i.test(value) && /(?:^|[\s/_.-])deploy(?:[\s/_.-]|$)/i.test(value);
 const materializeCommand = (script) => commands(script).some(({ text }) => /^starci\s+app\s+secret\s+materialize\b/.test(commandBody(text)));
-const deploymentCommand = (script) => commands(script).some(({ text }) => /^(?:starci\s+(?:app\s+)?(?:deploy|secret\s+materialize)\b|docker\s+stack\s+deploy\b|(?:ba?sh\s+)?(?:\.\/)?deploy\/|(?:ba?sh\s+)?(?:\.\/)?(?:scripts\/)?[\w.-]*deploy[\w.-]*\.sh\b|npm\s+run\s+deploy(?=[:\s]|$))/.test(commandBody(text)));
+const DEPLOYMENT_COMMANDS = [
+  /^starci\s+(?:app\s+)?(?:deploy|secret\s+materialize)\b/,
+  /^docker\s+stack\s+deploy\b/,
+  /^(?:ba?sh\s+)?(?:\.\/)?deploy\//,
+  /^(?:ba?sh\s+)?(?:\.\/)?(?:scripts\/)?[\w.-]*deploy[\w.-]*\.sh\b/,
+  /^npm\s+run\s+deploy(?=[:\s]|$)/,
+];
+const deploymentCommand = (script) => commands(script).some(({ text }) => {
+  const body = commandBody(text);
+  return DEPLOYMENT_COMMANDS.some((pattern) => pattern.test(body));
+});
 
 function hasAgeIdentity(job, doc) {
   const steps = activeSteps(job);

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

@@ -52,10 +52,15 @@ function resolvedPath(raw, file, tracked, link, generated, roots) {
   return candidates.some((candidate) => !candidate.startsWith('../') && (trackedPath(candidate, tracked) || generated.has(candidate)));
 }
 
+const ENV_NAME = /[A-Z][A-Z0-9_]*/.source;
+const INLINE_LINK = /\]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+['"][^)]*)?\)/.source;
+const REFERENCE_LINK = /^\s*\[[^\]]+\]:\s*(?:<([^>]+)>|(\S+))/.source;
+const MARKDOWN_LINK = new RegExp(`${INLINE_LINK}|${REFERENCE_LINK}`, 'g');
+
 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)) {
+  for (const match of line.matchAll(MARKDOWN_LINK)) {
     refs.push({ target: match[1] ?? match[2] ?? match[3] ?? match[4], link: true });
   }
   const masked = line.replace(/\]\([^)]*\)/g, ']');
@@ -171,9 +176,14 @@ function importedFiles(file, text, tracked) {
   });
 }
 
+const READER_CALL = /\b(\w+)\s*\.\s*\w+\s*\(\s*['"]([A-Z][A-Z0-9_]*)['"]/.source;
+const PROCESS_ENV_DOT = /\bprocess\.env\.([A-Z][A-Z0-9_]*)/.source;
+const PROCESS_ENV_INDEX = /\bprocess\.env\[['"]([A-Z][A-Z0-9_]*)['"]\]/.source;
+const ENV_READ = new RegExp(`${READER_CALL}|${PROCESS_ENV_DOT}|${PROCESS_ENV_INDEX}`, 'g');
+
 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)) {
+  for (const match of text.matchAll(ENV_READ)) {
     if (match[3] || match[4]) keys.add(match[3] ?? match[4]);
     else if (readers.has(match[1])) keys.add(match[2]);
   }
@@ -242,6 +252,11 @@ function unknownEnvironmentName(name, line, keys, codes, tokens, explicit) {
   return !keys.has(name) && !(name.endsWith('_FILE') && keys.has(name.slice(0, -5)));
 }
 
+const QUOTED_ENV_NAME = `\`(${ENV_NAME})\``;
+const REFERENCED_ENV_NAME = String.raw`\b(?:process\.env\.|\$\{?)(${ENV_NAME})`;
+const ASSIGNED_ENV_NAME = String.raw`\b(${ENV_NAME})\s*=`;
+const ENV_NAME_CITATION = new RegExp(`${QUOTED_ENV_NAME}|${REFERENCED_ENV_NAME}|${ASSIGNED_ENV_NAME}`, 'g');
+
 function nameFindings(file, lines, keys, rules, tokens) {
   const findings = [];
   const codes = new Set(rules.rules.flatMap((rule) => rule.failureCodes));
@@ -249,7 +264,7 @@ function nameFindings(file, lines, keys, rules, tokens) {
     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)) {
+    for (const match of line.matchAll(ENV_NAME_CITATION)) {
       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 }));

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

@@ -222,7 +222,10 @@ function masksProbeFailure(body) {
   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 (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
     if (char === '"' || char === "'") { quote = char; continue; }
     if (char === ';' || char === '|') return true;
   }

package/runtime/scripts/hfs/rules/env-parity.mjs

@@ -35,12 +35,10 @@ const APP_MAIN = /(?:^|\/)apps\/[^/]+\/src\/main\.ts$/u;
 const SEALED_MEMBER = /^\.starcistacks\/[^/]+\/secrets\/[^/]+\.enc$/u;
 const KEYS_ROSTER = /^\.starcistacks\/[^/]+\/runtime\/env\/KEYS\.md$/u;
 const STACK_YAML = /^\.starcistacks\/.+\.ya?ml$/u;
-const ENV_EXAMPLE = /\.env\.example$/u;
-const PUBLIC_PREFIX = /^NEXT_PUBLIC_/u;
 const KEY_NAME = /^[A-Za-z_]\w*$/u;
 const FILE_SUFFIX = /_FILE$/u;
 const EXAMPLE_LINE = /^[ \t]*(?:export[ \t]+)?([A-Za-z_]\w*)[ \t]*=(.*)$/u;
-const ROSTER_KEY = /`([A-Za-z_][A-Za-z0-9_]*)`/gu;
+const ROSTER_KEY = /`([A-Za-z_]\w*)`/gu;
 
 const REQUIRED_ALWAYS = new Set(['string', 'url', 'secret', 'enum']);
 const FALLBACK_OPTIONAL = new Set(['int', 'bool', 'duration']);
@@ -274,14 +272,17 @@ function declaredYamlEntry(key, value, add) {
 /** The env names one yaml node declares: `environment:`/`env:` keys or `K=V` entries, `runtimeSecrets`, `secrets` and `vars[].name`. */
 function declaredFromYaml(node, add) {
   if (!node || typeof node !== 'object') return;
-  if (Array.isArray(node)) { for (const item of node) declaredFromYaml(item, add); return; }
+  if (Array.isArray(node)) {
+    for (const item of node) declaredFromYaml(item, add);
+    return;
+  }
   for (const [key, value] of Object.entries(node)) declaredYamlEntry(key, value, add);
 }
 
 function addDeclaredKey(declared, name) {
   if (!KEY_NAME.test(name)) return;
   declared.add(name);
-  if (FILE_SUFFIX.test(name)) declared.add(name.replace(FILE_SUFFIX, ''));
+  if (name.endsWith('_FILE')) declared.add(name.replace(FILE_SUFFIX, ''));
 }
 
 function declareKeysFromText(file, text, add) {
@@ -314,7 +315,7 @@ function addRequiredFindings(reads, sealed, declared, findings) {
 
 function sealedMemberFinding(key, member, reads, declared) {
   // The specific public-custody code wins over the generic unread one for a NEXT_PUBLIC_* key.
-  if (PUBLIC_PREFIX.test(key)) {
+  if (key.startsWith('NEXT_PUBLIC_')) {
     return found(ENV_PUBLIC_SEALED, member, `${member} seals the public key ${key}; NEXT_PUBLIC_* values are public configuration and never enter custody`);
   }
   if (!reads.has(key) && !declared.has(key)) {
@@ -347,7 +348,7 @@ function addDuplicateFindings(key, members, findings) {
 }
 
 function addExampleFindings(repoRoot, all, reads, findings) {
-  for (const file of all.filter((rel) => ENV_EXAMPLE.test(rel))) {
+  for (const file of all.filter((rel) => rel.endsWith('.env.example'))) {
     const text = readText(repoRoot, file);
     if (text === null) continue;
     for (const { key } of envExampleEntries(text)) {

package/runtime/scripts/hfs/rules/env-value-shape.mjs

@@ -19,8 +19,6 @@ import { found, readText } from './read.mjs';
 export const ENV_VALUE_SHAPE = 'ENV_VALUE_SHAPE';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-const FILE_SUFFIX = /_FILE$/u;
-const ENV_EXAMPLE = /\.env\.example$/u;
 const SKIP_DIRECTORY = new Set(['node_modules', 'dist', 'coverage', '.git']);
 
 const SHAPES = Object.freeze({
@@ -61,7 +59,7 @@ function listEnvSourceFiles(repoRoot) {
 function shapeViolations(reads, map) {
   const violations = [];
   for (const [key, value] of Object.entries(map)) {
-    if (FILE_SUFFIX.test(key)) continue;
+    if (key.endsWith('_FILE')) continue;
     const shape = reads.get(key)?.shape;
     if (shape && !shapeOk(shape, value)) violations.push({ key, expected: shapeText(shape) });
   }
@@ -71,7 +69,7 @@ function shapeViolations(reads, map) {
 /** The findings of R249 over the `*.env.example` files of an app judged at its root scope (both editions). */
 export function envValueShapeFindings({ repoRoot, all = [], isRoot }) {
   if (!isRoot) return [];
-  const examples = all.filter((file) => ENV_EXAMPLE.test(file));
+  const examples = all.filter((file) => file.endsWith('.env.example'));
   if (!examples.length) return [];
   const reads = collectEnvReads(repoRoot, all);
   if (reads === null) return [];

package/runtime/scripts/hfs/rules/fe-build-args.mjs

@@ -91,7 +91,7 @@ function requiredNames(root, files, app, ts) {
   const names = new Set();
   for (const file of files.filter(file => file.startsWith(prefix))) {
     const local = file.slice(prefix.length);
-    const source = SOURCE.test(local) && (local.startsWith('src/') || /^next\.config\./u.test(local) || SCHEMA.test(local));
+    const source = SOURCE.test(local) && (local.startsWith('src/') || local.startsWith('next.config.') || SCHEMA.test(local));
     const schema = SCHEMA.test(local) && /\.(?:json|ya?ml)$/u.test(local);
     if (!source && !schema) continue;
     const text = readText(root, file);

package/runtime/scripts/hfs/rules/release-provenance.mjs

@@ -13,7 +13,10 @@ import { found, readJson, readText } from './read.mjs';
 
 export const HFS_RELEASE_TAG_MISMATCH = 'HFS_RELEASE_TAG_MISMATCH';
 export const HFS_DB_DEPLOY_UNGUARDED = 'HFS_DB_DEPLOY_UNGUARDED';
-const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[0-9]*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const SEMVER_NUMBER = String.raw`(?:0|[1-9]\d*)`;
+const SEMVER_PRERELEASE_ID = String.raw`(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)`;
+const SEMVER_BUILD_ID = '[0-9A-Za-z-]+';
+const SEMVER = new RegExp(String.raw`^${SEMVER_NUMBER}\.${SEMVER_NUMBER}\.${SEMVER_NUMBER}(?:-${SEMVER_PRERELEASE_ID}(?:\.${SEMVER_PRERELEASE_ID})*)?(?:\+${SEMVER_BUILD_ID}(?:\.${SEMVER_BUILD_ID})*)?$`);
 const WORKFLOW = /^\.github\/workflows\/(images|db-deploy)\.ya?ml$/;
 const TAG = 1;
 const VERSION_PREFIX = 2;
@@ -42,7 +45,7 @@ function splitBoolean(expression, operator) {
   let start = 0, depth = 0, quote = '';
   for (let i = 0; i < expression.length; i += 1) {
     const char = expression[i];
-    if (quote) { if (char === quote) quote = ''; continue; }
+    if (quote) { if (char === quote) { quote = ''; } continue; }
     if (char === "'" || char === '"') { quote = char; continue; }
     if (char === '(') depth += 1;
     if (char === ')') depth -= 1;
@@ -56,7 +59,7 @@ function enclosingParentheses(text) {
   let depth = 0, quote = '';
   for (let i = 0; i < text.length - 1; i += 1) {
     const char = text[i];
-    if (quote) { if (char === quote) quote = ''; continue; }
+    if (quote) { if (char === quote) { quote = ''; } continue; }
     if (char === "'" || char === '"') { quote = char; continue; }
     if (char === '(') depth += 1;
     if (char === ')' && --depth === 0) return false;
@@ -109,7 +112,7 @@ function shellTagGuard(step) {
 }
 
 function checkoutPreservesRef(job) {
-  return (job.steps ?? []).filter((step) => /^actions\/checkout@/.test(step.uses ?? '')).every((step) => {
+  return (job.steps ?? []).filter((step) => (step.uses ?? '').startsWith('actions/checkout@')).every((step) => {
     const ref = step.with?.ref;
     return ref === undefined || /^\$\{\{\s*github\.(?:ref|ref_name|sha)\s*\}\}$/.test(String(ref));
   });
@@ -174,7 +177,7 @@ function imageFindings(file, workflow, version) {
   let builds = 0;
   for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
     for (const step of job?.steps ?? []) {
-      if (!/^docker\/build-push-action@/.test(step.uses ?? '')) continue;
+      if (!(step.uses ?? '').startsWith('docker/build-push-action@')) continue;
       builds += 1;
       const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
       if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version)) findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));