@starci/hfs 4.0.10 → 4.1.0

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

@@ -8,10 +8,10 @@
 // api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { found, readText } from './read.mjs';
 import { safeRemove } from '../../api/fs/safe-remove.mjs';
+import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
 
 export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
 const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
@@ -19,7 +19,7 @@ const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
 
 /** sha256 of a file's text with line endings folded, or null when it cannot be read. */
 function contractHash(file) {
-  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex'); } catch { return null; }
+  try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replaceAll('\r\n', '\n')).digest('hex'); } catch { return null; }
 }
 
 /** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
@@ -42,6 +42,36 @@ export function contractFindings({ repoRoot, files, repo, resolver }) {
 /** The first lines of an error, enough to act on. */
 const errorText = (error) => String(error?.message ?? error).split(/\r?\n/).filter(Boolean).slice(0, 4).join(' | ');
 
+function emitFailure(app, artifacts, error, apps, findings) {
+  for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
+  const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
+  findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+}
+
+function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings }) {
+  const snapshot = `contracts/${app.name}/${artifact}`;
+  const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
+  if (!emitted.written.includes(snapshot)) {
+    if (committed === null) {
+      if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
+      return;
+    }
+    apps.push({ app: app.name, artifact, status: 'left-behind' });
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
+    return;
+  }
+  const fresh = contractHash(path.join(scratch, snapshot));
+  if (committed === null) {
+    // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
+    apps.push({ app: app.name, artifact, status: 'not-committed' });
+  } else if (committed === fresh) {
+    apps.push({ app: app.name, artifact, status: 'fresh' });
+  } else {
+    apps.push({ app: app.name, artifact, status: 'stale' });
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
+  }
+}
+
 /**
  * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
  * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
@@ -56,7 +86,7 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
   const apps = [];
   if (repo.profile !== 'be') return { findings, apps };
   const tracked = new Set(files);
-  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'hfs-contracts-'));
+  const scratch = makeTempDir('hfs-contracts-');
   try {
     for (const app of repo.apps.filter((a) => a.kind === 'api')) {
       const artifacts = [{ artifact: SNAPSHOT_OF.graphql, what: 'serves no GraphQL any more' }, { artifact: SNAPSHOT_OF.json, what: 'declares no operations any more' }];
@@ -64,33 +94,11 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
       try {
         emitted = emit({ repoRoot, declaration: { apps: [app] }, outDir: scratch });
       } catch (error) {
-        for (const { artifact } of artifacts) apps.push({ app: app.name, artifact, status: 'emit-failed' });
-        const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
-        findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `contracts/${app.name} cannot be verified: \`starci app emit\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+        emitFailure(app, artifacts, error, apps, findings);
         continue;
       }
       for (const { artifact, what } of artifacts) {
-        const snapshot = `contracts/${app.name}/${artifact}`;
-        const committed = tracked.has(snapshot) ? contractHash(path.join(repoRoot, snapshot)) : null;
-        if (!emitted.written.includes(snapshot)) {
-          if (committed === null) {
-            if (artifact === SNAPSHOT_OF.graphql) apps.push({ app: app.name, artifact, status: 'none' });
-            continue;
-          }
-          apps.push({ app: app.name, artifact, status: 'left-behind' });
-          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} is committed but ${app.name} ${what}; delete it`, { app: app.name, drift: 'left-behind' }));
-          continue;
-        }
-        const fresh = contractHash(path.join(scratch, snapshot));
-        if (committed === null) {
-          // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
-          apps.push({ app: app.name, artifact, status: 'not-committed' });
-        } else if (committed === fresh) {
-          apps.push({ app: app.name, artifact, status: 'fresh' });
-        } else {
-          apps.push({ app: app.name, artifact, status: 'stale' });
-          findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${snapshot} (${committed.slice(0, 12)}) differs from what ${app.name} emits now (${String(fresh).slice(0, 12)}); run \`npm run contract:emit\` and commit the result`, { app: app.name, drift: 'stale' }));
-        }
+        artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emitted, apps, findings });
       }
     }
   } finally {

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

@@ -3,7 +3,7 @@
 import { sameText } from '../../lib/same-text.mjs';
 import { found, readText } from './read.mjs';
 import { DB_CONFIG_POLICY, DB_TYPES_DRIFT, TYPES_FILE } from './database-constants.mjs';
-const ENV_REF = /^env\([A-Za-z_][A-Za-z0-9_]*\)$/;
+const ENV_REF = /^env\([A-Za-z_]\w*\)$/;
 const PUBLIC_KEYS = new Set(['anon_key', 'publishable_key', 'public_key']);
 
 
@@ -28,17 +28,69 @@ const isCredentialKey = (key) => {
     || (leaf.endsWith('_key') && !PUBLIC_KEYS.has(leaf));
 };
 
+const escapeRegexPart = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+
 const tomlLine = (text, key) => {
-  const expression = new RegExp(`^\\s*["']?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']?\\s*=`, 'm');
+  const expression = new RegExp(String.raw`^\s*["']?${escapeRegexPart(key)}["']?\s*=`, 'm');
   const match = expression.exec(text);
   return match ? text.slice(0, match.index).split('\n').length : undefined;
 };
 
+function credentialConfigFindings(file, text, toml) {
+  const findings = [];
+  for (const [at, key, value] of tomlEntries(toml)) {
+    if (!isCredentialKey(key)) continue;
+    const line = tomlLine(text, key);
+    if (typeof value !== 'string' || !ENV_REF.test(value)) {
+      const lineNote = line ? `:${line}` : '';
+      findings.push(found(DB_CONFIG_POLICY, file, `${file}${lineNote} ${at} holds a literal credential; a secret in config.toml is written env(NAME), never a value`, { ...(line ? { line } : {}), key: at }));
+    }
+  }
+  return findings;
+}
+
+// A finding for an auth setting of config.toml that differs from what hfs.json supabase.<field> declares; `shown` is the setting as read.
+const settingFinding = (file, key, field, shown, declaredValue, note = '') => found(DB_CONFIG_POLICY, file, `${file} ${key} is ${shown}; hfs.json supabase.${field} declares ${declaredValue}${note}`, { key, declared: declaredValue });
+
+const shownSetting = (value) => JSON.stringify(value ?? 'absent');
+
+function signupFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.enableSignup === undefined) return findings;
+  if (auth.enable_signup !== declared.enableSignup) findings.push(settingFinding(file, 'auth.enable_signup', 'enableSignup', shownSetting(auth.enable_signup), declared.enableSignup, ' - the invite posture is a checked fact, not a doc claim'));
+  if (auth.email?.enable_signup !== undefined && auth.email.enable_signup !== declared.enableSignup) {
+    findings.push(settingFinding(file, 'auth.email.enable_signup', 'enableSignup', JSON.stringify(auth.email.enable_signup), declared.enableSignup));
+  }
+  return findings;
+}
+
+function redirectUrlFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.redirectUrls === undefined) return findings;
+  const configured = Array.isArray(auth.additional_redirect_urls) ? auth.additional_redirect_urls : [];
+  for (const url of configured) {
+    if (!declared.redirectUrls.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls holds ${url}, which hfs.json supabase.redirectUrls does not declare; the config states nothing the app did not declare`, { key: 'auth.additional_redirect_urls', url }));
+  }
+  for (const url of declared.redirectUrls) {
+    if (!configured.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls omits ${url}, which hfs.json supabase.redirectUrls declares; the config and declaration must carry the same redirect set`, { key: 'auth.additional_redirect_urls', url }));
+  }
+  return findings;
+}
+
+function declarationConfigFindings(file, auth, declared) {
+  const findings = [];
+  if (declared.jwtExpiry !== undefined && auth.jwt_expiry !== declared.jwtExpiry) findings.push(settingFinding(file, 'auth.jwt_expiry', 'jwtExpiry', shownSetting(auth.jwt_expiry), declared.jwtExpiry));
+  findings.push(...signupFindings(file, auth, declared));
+  if (declared.siteUrl !== undefined && auth.site_url !== declared.siteUrl) findings.push(settingFinding(file, 'auth.site_url', 'siteUrl', shownSetting(auth.site_url), declared.siteUrl));
+  findings.push(...redirectUrlFindings(file, auth, declared));
+  return findings;
+}
+
 /** The parsed TOML of `text`, or null when it does not parse. */
 export async function parseToml(text) {
   try {
     const module = await import('smol-toml');
-    return (module.default?.parse ?? module.parse)(text);
+    return module.parse(text);
   } catch {
     return null;
   }
@@ -46,14 +98,7 @@ export async function parseToml(text) {
 
 /** L08 policy findings in one already-parsed supabase/config.toml. */
 export function configFindings({ file, text, toml, supabase }) {
-  const findings = [];
-  for (const [at, key, value] of tomlEntries(toml)) {
-    if (!isCredentialKey(key)) continue;
-    const line = tomlLine(text, key);
-    if (typeof value !== 'string' || !ENV_REF.test(value)) {
-      findings.push(found(DB_CONFIG_POLICY, file, `${file}${line ? `:${line}` : ''} ${at} holds a literal credential; a secret in config.toml is written env(NAME), never a value`, { ...(line ? { line } : {}), key: at }));
-    }
-  }
+  const findings = credentialConfigFindings(file, text, toml);
   const auth = toml?.auth ?? {};
   if (auth.jwt_expiry !== undefined && (typeof auth.jwt_expiry !== 'number' || auth.jwt_expiry > 3600)) {
     findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry)}; the access token lives at most 3600 seconds`, { key: 'auth.jwt_expiry' }));
@@ -63,27 +108,7 @@ export function configFindings({ file, text, toml, supabase }) {
     enableSignup: supabase.enableSignup, jwtExpiry: supabase.jwtExpiry, siteUrl: supabase.siteUrl,
     redirectUrls: Array.isArray(supabase.redirectUrls) ? supabase.redirectUrls : undefined,
   };
-  if (declared.jwtExpiry !== undefined && auth.jwt_expiry !== declared.jwtExpiry) {
-    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.jwt_expiry is ${JSON.stringify(auth.jwt_expiry ?? 'absent')}; hfs.json supabase.jwtExpiry declares ${declared.jwtExpiry}`, { key: 'auth.jwt_expiry', declared: declared.jwtExpiry }));
-  }
-  if (declared.enableSignup !== undefined) {
-    if (auth.enable_signup !== declared.enableSignup) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.enable_signup is ${JSON.stringify(auth.enable_signup ?? 'absent')}; hfs.json supabase.enableSignup declares ${declared.enableSignup} - the invite posture is a checked fact, not a doc claim`, { key: 'auth.enable_signup', declared: declared.enableSignup }));
-    if (auth.email?.enable_signup !== undefined && auth.email.enable_signup !== declared.enableSignup) {
-      findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.email.enable_signup is ${JSON.stringify(auth.email.enable_signup)}; hfs.json supabase.enableSignup declares ${declared.enableSignup}`, { key: 'auth.email.enable_signup', declared: declared.enableSignup }));
-    }
-  }
-  if (declared.siteUrl !== undefined && auth.site_url !== declared.siteUrl) {
-    findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.site_url is ${JSON.stringify(auth.site_url ?? 'absent')}; hfs.json supabase.siteUrl declares ${declared.siteUrl}`, { key: 'auth.site_url', declared: declared.siteUrl }));
-  }
-  if (declared.redirectUrls !== undefined) {
-    const configured = Array.isArray(auth.additional_redirect_urls) ? auth.additional_redirect_urls : [];
-    for (const url of configured) {
-      if (!declared.redirectUrls.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls holds ${url}, which hfs.json supabase.redirectUrls does not declare; the config states nothing the app did not declare`, { key: 'auth.additional_redirect_urls', url }));
-    }
-    for (const url of declared.redirectUrls) {
-      if (!configured.includes(url)) findings.push(found(DB_CONFIG_POLICY, file, `${file} auth.additional_redirect_urls omits ${url}, which hfs.json supabase.redirectUrls declares; the config and declaration must carry the same redirect set`, { key: 'auth.additional_redirect_urls', url }));
-    }
-  }
+  findings.push(...declarationConfigFindings(file, auth, declared));
   return findings;
 }
 

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

@@ -5,6 +5,7 @@ import { log } from '../../api/git/log.mjs';
 import { mergeBase } from '../../api/git/merge-base.mjs';
 import { show } from '../../api/git/show.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
+import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
 import { found, readText } from './read.mjs';
 import { DB_MIGRATION_SHAPE, MIGRATIONS_DIR } from './database-constants.mjs';
@@ -24,7 +25,9 @@ export function defaultGit(args, { cwd }) {
   const [verb, ...rest] = args;
   const env = withoutGitLocalEnv(process.env);
   if (verb === 'merge-base') { const sha = mergeBase(cwd, rest[0], rest[1]); return { ok: sha !== null, stdout: sha ?? '' }; }
-  const call = verb === 'ls-tree' ? lsTree : verb === 'log' ? log : show;
+  let call = show;
+  if (verb === 'ls-tree') call = lsTree;
+  else if (verb === 'log') call = log;
   const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
   return { ok: !result.error && result.status === 0, stdout: result.stdout };
 }
@@ -33,11 +36,13 @@ const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoo
   .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
 
 async function baseShaOf(git, repoRoot, base) {
-  for (const ref of base ? [base] : ['origin/main', 'main']) {
+  let found = null;
+  await findInOrder(base ? [base] : ['origin/main', 'main'], async (ref) => {
     const result = await runGit(git, repoRoot, ['merge-base', 'HEAD', ref]);
-    if (result.ok && result.stdout.trim()) return { ref, sha: result.stdout.trim() };
-  }
-  return null;
+    if (result.ok && result.stdout.trim()) found = { ref, sha: result.stdout.trim() };
+    return found !== null;
+  });
+  return found;
 }
 
 async function baseMigrationNames(git, repoRoot, sha) {
@@ -48,7 +53,8 @@ async function baseMigrationNames(git, repoRoot, sha) {
 }
 
 async function baseFileText(git, repoRoot, sha, file) {
-  const result = await runGit(git, repoRoot, ['show', `${sha}:${file}`]);
+  // `./` reads the path from the app root, which is a folder of a larger repository when the app is nested in one (an example of the runtime).
+  const result = await runGit(git, repoRoot, ['show', `${sha}:./${file}`]);
   return result.ok ? result.stdout : null;
 }
 
@@ -59,25 +65,18 @@ async function migrationTimeLimit(git, repoRoot, file, now) {
   return { at: now(), tracked: false };
 }
 
-
-/** L02 findings for names, stamps, ordering and immutability of supabase/migrations/*.sql. */
-export async function migrationShapeFindings({ repoRoot, migrations, git, base, now }) {
+async function localMigrationFindings(local, repoRoot, git, now) {
   const findings = [];
-  const prefix = `${MIGRATIONS_DIR}/`;
-  const local = migrations.map((file) => {
-    const name = file.startsWith(prefix) ? file.slice(prefix.length) : file;
-    return { file, name, match: MIGRATION_NAME.exec(name) };
-  });
   const stamps = new Map();
-  for (const entry of local) {
+  await eachInOrder(local, async (entry) => {
     if (!entry.match) {
       findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is not named <ts14>_<kebab>.sql; a migration is created by \`npm run db:new\` (supabase migration new), never renamed by hand`, { expected: '<ts14>_<kebab>.sql' }));
-      continue;
+      return;
     }
     const stamp = migrationStamp(entry.match[1]);
     if (stamp === null) {
       findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} carries ${entry.match[1]}, which is no valid UTC time; the stamp is the real creation time`, { stamp: entry.match[1] }));
-      continue;
+      return;
     }
     const limit = await migrationTimeLimit(git, repoRoot, entry.file, now);
     if (stamp > limit.at) {
@@ -86,26 +85,48 @@ export async function migrationShapeFindings({ repoRoot, migrations, git, base,
     }
     if (stamps.has(stamp)) findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} shares stamp ${entry.match[1]} with ${stamps.get(stamp)}; stamps are strictly increasing`, { stamp: entry.match[1], other: stamps.get(stamp) }));
     stamps.set(stamp, entry.file);
+  });
+  return findings;
+}
+
+async function baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase, baseMax) {
+  if (!entry.match) return [];
+  const stamp = migrationStamp(entry.match[1]);
+  if (onBase.has(entry.name)) {
+    const committed = await baseFileText(git, repoRoot, baseSha.sha, entry.file);
+    const current = readText(repoRoot, entry.file);
+    if (!sameText(current, committed)) return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} differs from its content on ${baseSha.ref}; a migration on the base branch is immutable - write a new migration`, { base: baseSha.ref })];
+  } else if (baseMax !== null && stamp !== null && stamp <= baseMax) {
+    return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration on ${baseSha.ref} (latest ${String(new Date(baseMax).toISOString())}); a new migration sorts after the base ones`, { stamp: entry.match[1], base: baseSha.ref })];
   }
+  return [];
+}
+
+function removedMigrationFindings(local, baseNames, baseSha) {
+  const findings = [];
+  for (const name of baseNames) {
+    if (!local.some((entry) => entry.name === name)) findings.push(found(DB_MIGRATION_SHAPE, `${MIGRATIONS_DIR}/${name}`, `${MIGRATIONS_DIR}/${name} exists on ${baseSha.ref} but is gone here; a migration on the base branch is immutable - restore it`, { base: baseSha.ref }));
+  }
+  return findings;
+}
+
+/** L02 findings for names, stamps, ordering and immutability of supabase/migrations/*.sql. */
+export async function migrationShapeFindings({ repoRoot, migrations, git, base, now }) {
+  const prefix = `${MIGRATIONS_DIR}/`;
+  const local = migrations.map((file) => {
+    const name = file.startsWith(prefix) ? file.slice(prefix.length) : file;
+    return { file, name, match: MIGRATION_NAME.exec(name) };
+  });
+  const findings = await localMigrationFindings(local, repoRoot, git, now);
   const baseSha = await baseShaOf(git, repoRoot, base);
   if (!baseSha) return findings;
   const baseNames = await baseMigrationNames(git, repoRoot, baseSha.sha);
   const onBase = new Set(baseNames);
   const baseStamps = baseNames.map((name) => MIGRATION_NAME.exec(name)?.[1]).filter(Boolean).map(migrationStamp).filter((stamp) => stamp !== null);
   const baseMax = baseStamps.length ? Math.max(...baseStamps) : null;
-  for (const entry of local) {
-    if (!entry.match) continue;
-    const stamp = migrationStamp(entry.match[1]);
-    if (onBase.has(entry.name)) {
-      const committed = await baseFileText(git, repoRoot, baseSha.sha, entry.file);
-      const current = readText(repoRoot, entry.file);
-      if (!sameText(current, committed)) findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} differs from its content on ${baseSha.ref}; a migration on the base branch is immutable - write a new migration`, { base: baseSha.ref }));
-    } else if (baseMax !== null && stamp !== null && stamp <= baseMax) {
-      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration on ${baseSha.ref} (latest ${String(new Date(baseMax).toISOString())}); a new migration sorts after the base ones`, { stamp: entry.match[1], base: baseSha.ref }));
-    }
-  }
-  for (const name of baseNames) {
-    if (!local.some((entry) => entry.name === name)) findings.push(found(DB_MIGRATION_SHAPE, `${MIGRATIONS_DIR}/${name}`, `${MIGRATIONS_DIR}/${name} exists on ${baseSha.ref} but is gone here; a migration on the base branch is immutable - restore it`, { base: baseSha.ref }));
-  }
+  await eachInOrder(local, async (entry) => {
+    findings.push(...await baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase, baseMax));
+  });
+  findings.push(...removedMigrationFindings(local, baseNames, baseSha));
   return findings;
 }

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

@@ -1,6 +1,7 @@
 // PL/pgSQL inspection for DB_DYNAMIC_DDL and DB_DEFINER_SAFE. Function and DO bodies are parsed by libpg-query;
 // dynamic query expressions are then parsed as PostgreSQL expressions instead of matched as raw migration text.
 import { found } from './read.mjs';
+import { eachInOrder } from '../../lib/in-order.mjs';
 import { parsePlpgsqlBody, parseSql } from '../sql/pg-parse.mjs';
 import { DB_DEFINER_SAFE, DB_DYNAMIC_DDL } from './database-constants.mjs';
 
@@ -12,36 +13,36 @@ const nameOf = (list, defaultSchema) => {
 
 const functionOption = (node, key) => (node.options ?? []).filter((option) => option?.DefElem?.defname === key).map((option) => option.DefElem);
 const securityDefiner = (node) => functionOption(node, 'security').some((option) => option.arg?.Boolean?.boolval === true || option.arg?.Integer?.ival === 1);
-const functionLanguage = (node) => functionOption(node, 'language').map((option) => option.arg?.String?.sval).filter(Boolean).at(-1) ?? 'sql';
+const functionLanguage = (node) => functionOption(node, 'language').map((option) => option.arg?.String?.sval).findLast(Boolean) ?? 'sql';
 const functionBody = (node) => functionOption(node, 'as').flatMap((option) => (option.arg?.List?.items ?? []).map((item) => item?.String?.sval ?? '')).join('') || null;
 const functionReturnKind = (node) => {
-  const name = node.returnType?.names?.map(sval).filter(Boolean).at(-1);
+  const name = node.returnType?.names?.map(sval).findLast(Boolean);
   if (name === 'void') return 'void';
   if (name === 'trigger' || name === 'event_trigger') return 'trigger';
   return node.returnType?.setof ? 'setof' : 'scalar';
 };
 
+/** The statement kinds that run a dynamic query, with the field holding its query expression. */
+const DYNAMIC_QUERY_FIELDS = new Map([['PLpgSQL_stmt_dynexecute', 'query'], ['PLpgSQL_stmt_dynfors', 'query'], ['PLpgSQL_stmt_open', 'dynquery']]);
+
+function collectDynamicQueries(value, out) {
+  if (!value || typeof value !== 'object') return;
+  if (Array.isArray(value)) {
+    for (const item of value) collectDynamicQueries(item, out);
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const field = DYNAMIC_QUERY_FIELDS.get(key);
+    const text = field === undefined ? undefined : child?.[field]?.PLpgSQL_expr?.query;
+    if (text !== undefined) out.push({ text, lineno: child.lineno });
+    collectDynamicQueries(child, out);
+  }
+}
+
 /** Every dynamic query expression in one parsed PL/pgSQL function. */
 function dynamicQueries(root) {
   const out = [];
-  const visit = (value) => {
-    if (!value || typeof value !== 'object') return;
-    if (Array.isArray(value)) {
-      for (const item of value) visit(item);
-      return;
-    }
-    for (const [key, child] of Object.entries(value)) {
-      if (key === 'PLpgSQL_stmt_dynexecute' || key === 'PLpgSQL_stmt_dynfors') {
-        const text = child?.query?.PLpgSQL_expr?.query;
-        if (text !== undefined) out.push({ text, lineno: child.lineno });
-      } else if (key === 'PLpgSQL_stmt_open') {
-        const text = child?.dynquery?.PLpgSQL_expr?.query;
-        if (text !== undefined) out.push({ text, lineno: child.lineno });
-      }
-      visit(child);
-    }
-  };
-  visit(root);
+  collectDynamicQueries(root, out);
   return out;
 }
 
@@ -80,6 +81,33 @@ function formatSpecifiers(template) {
   return template.slice(cursor).includes('%') ? null : specs;
 }
 
+/** The text one format() conversion renders to; an argument that is no string literal marks the render incomplete. */
+function substituteSpecifier(spec, args, state) {
+  if (spec.type === '%') return '%';
+  const argumentIndex = spec.position ?? state.sequential;
+  if (spec.position === null) state.sequential += 1;
+  if (spec.type === 'I') return 'hfs_identifier';
+  if (spec.type === 'L') return "'hfs_literal'";
+  const value = stringValue(args[argumentIndex + 1]);
+  if (value !== undefined) return value;
+  state.complete = false;
+  return 'hfs_dynamic';
+}
+
+function renderFormat(args) {
+  const template = stringValue(args[0]);
+  if (template === undefined) return { text: 'hfs_dynamic', complete: false };
+  const specs = formatSpecifiers(template);
+  if (specs === null) return { text: template, complete: false };
+  const state = { sequential: 0, specIndex: 0, complete: true };
+  const text = template.replace(FORMAT_SPECIFIER, () => {
+    const spec = specs[state.specIndex];
+    state.specIndex += 1;
+    return substituteSpecifier(spec, args, state);
+  });
+  return { text, complete: state.complete };
+}
+
 /** Render enough of a dynamic expression to let the PostgreSQL parser identify its generated statement kind. */
 function renderExpression(node) {
   const literal = stringValue(node);
@@ -90,31 +118,7 @@ function renderExpression(node) {
     const right = renderExpression(node.A_Expr.rexpr);
     return { text: `${left.text}${right.text}`, complete: left.complete && right.complete };
   }
-  if (formatName(node)) {
-    const args = node.FuncCall.args ?? [];
-    const template = stringValue(args[0]);
-    if (template === undefined) return { text: 'hfs_dynamic', complete: false };
-    const specs = formatSpecifiers(template);
-    if (specs === null) return { text: template, complete: false };
-    let sequential = 0;
-    let specIndex = 0;
-    let complete = true;
-    const text = template.replace(FORMAT_SPECIFIER, () => {
-      const spec = specs[specIndex];
-      specIndex += 1;
-      if (spec.type === '%') return '%';
-      const argumentIndex = spec.position ?? sequential;
-      if (spec.position === null) sequential += 1;
-      const argument = args[argumentIndex + 1];
-      if (spec.type === 'I') return 'hfs_identifier';
-      if (spec.type === 'L') return "'hfs_literal'";
-      const value = stringValue(argument);
-      if (value !== undefined) return value;
-      complete = false;
-      return 'hfs_dynamic';
-    });
-    return { text, complete };
-  }
+  if (formatName(node)) return renderFormat(node.FuncCall.args ?? []);
   return { text: 'hfs_dynamic', complete: false };
 }
 
@@ -142,15 +146,16 @@ async function dynamicQueryAnalysis(text) {
 
 async function dynamicDdlFindings(file, queries, where, baseLine) {
   const findings = [];
-  for (const { text, lineno } of queries) {
+  await eachInOrder(queries, async ({ text, lineno }) => {
     const line = lineno ? baseLine + lineno - 1 : undefined;
+    const lineNote = line ? `${file}:${line}` : file;
     const analysis = await dynamicQueryAnalysis(text);
     if (analysis.buildsDdl) {
-      findings.push(found(DB_DYNAMIC_DDL, file, `${file}${line ? `:${line}` : ''} ${where} builds DDL dynamically (\`${String(text).slice(0, 120)}\`); write the create/alter/drop or grant/revoke out as statements so the parser sees every one`, { ...(line ? { line } : {}), query: text }));
+      findings.push(found(DB_DYNAMIC_DDL, file, `${lineNote} ${where} builds DDL dynamically (\`${String(text).slice(0, 120)}\`); write the create/alter/drop or grant/revoke out as statements so the parser sees every one`, { ...(line ? { line } : {}), query: text }));
     } else if (analysis.opaque) {
-      findings.push(found(DB_DYNAMIC_DDL, file, `${file}${line ? `:${line}` : ''} ${where} runs dynamic SQL the pass cannot read (\`${String(text).slice(0, 120)}\`); dynamic DDL is refused and a query built from an opaque value cannot be judged`, { ...(line ? { line } : {}), query: text }));
+      findings.push(found(DB_DYNAMIC_DDL, file, `${lineNote} ${where} runs dynamic SQL the pass cannot read (\`${String(text).slice(0, 120)}\`); dynamic DDL is refused and a query built from an opaque value cannot be judged`, { ...(line ? { line } : {}), query: text }));
     }
-  }
+  });
   return findings;
 }
 
@@ -163,17 +168,18 @@ function safeDefinerExpression(node) {
   const template = stringValue(node.FuncCall.args?.[0]);
   if (template === undefined) return false;
   const specs = formatSpecifiers(template);
-  return specs !== null && specs.every((spec) => ['I', 'L', '%'].includes(spec.type));
+  return specs?.every((spec) => ['I', 'L', '%'].includes(spec.type)) ?? false;
 }
 
 async function definerDynamicFindings(file, fn, queries, baseLine) {
   const findings = [];
-  for (const { text, lineno } of queries) {
+  await eachInOrder(queries, async ({ text, lineno }) => {
     const line = lineno ? baseLine + lineno - 1 : undefined;
+    const lineNote = line ? `${file}:${line}` : file;
     const expression = await expressionOf(text);
-    if (expression !== null && safeDefinerExpression(expression)) continue;
-    findings.push(found(DB_DEFINER_SAFE, file, `${file}${line ? `:${line}` : ''} security definer function ${fn.name} builds dynamic SQL without quoting every parameter through format() %I or %L (\`${String(text).slice(0, 120)}\`)`, { ...(line ? { line } : {}), function: fn.name, query: text }));
-  }
+    if (expression !== null && safeDefinerExpression(expression)) return;
+    findings.push(found(DB_DEFINER_SAFE, file, `${lineNote} security definer function ${fn.name} builds dynamic SQL without quoting every parameter through format() %I or %L (\`${String(text).slice(0, 120)}\`)`, { ...(line ? { line } : {}), function: fn.name, query: text }));
+  });
   return findings;
 }
 
@@ -188,46 +194,55 @@ function revokedRolesFor(fn, grants) {
   return roles;
 }
 
-/** All PL/pgSQL-backed L04/L06 findings for one migration's extracted facts. */
-export async function plpgsqlFindings(file, facts, exposed) {
-  const findings = [];
-  for (const block of facts.doBlocks) {
-    if (block.body === undefined || block.language !== 'plpgsql') {
-      findings.push(found(DB_DYNAMIC_DDL, file, `${file}:${block.line} DO block in ${block.language} cannot be inspected; a DO block is plpgsql so a static pass sees its statements`, { line: block.line }));
-      continue;
-    }
-    const ast = await plpgsqlOf(block.body);
-    if (ast === null) {
-      findings.push(found(DB_DYNAMIC_DDL, file, `${file}:${block.line} DO block body is not valid plpgsql; the pass must see every statement a migration runs`, { line: block.line }));
-      continue;
-    }
-    findings.push(...await dynamicDdlFindings(file, dynamicQueries(ast), 'DO block', block.line));
+async function doBlockFindings(file, block) {
+  if (block.body === undefined || block.language !== 'plpgsql') {
+    return [found(DB_DYNAMIC_DDL, file, `${file}:${block.line} DO block in ${block.language} cannot be inspected; a DO block is plpgsql so a static pass sees its statements`, { line: block.line })];
   }
+  const ast = await plpgsqlOf(block.body);
+  if (ast === null) return [found(DB_DYNAMIC_DDL, file, `${file}:${block.line} DO block body is not valid plpgsql; the pass must see every statement a migration runs`, { line: block.line })];
+  return dynamicDdlFindings(file, dynamicQueries(ast), 'DO block', block.line);
+}
 
-  for (const fn of facts.functions) {
-    const definer = securityDefiner(fn.node);
-    if (definer) {
-      const pathSet = functionOption(fn.node, 'set').some((option) => facts.isSearchPathSet(option))
-        || facts.alterFunctions.some((alter) => alter.name === fn.name && alter.setsPath && alter.index > fn.index);
-      if (!pathSet) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} sets no search_path; add \`set search_path = ''\` (or a pinned schema list) on the create, or an alter function in the same migration`, { line: fn.line, function: fn.name }));
-      if (exposed.has(fn.schema)) {
-        const revoked = revokedRolesFor(fn, facts.grants);
-        if (!revoked.has('public') || !revoked.has('anon')) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} lives in the exposed schema ${fn.schema}; keep it in a non-exposed schema or revoke execute from public and anon in the same migration`, { line: fn.line, function: fn.name }));
-      }
-      if (!fn.node.is_procedure && !fn.node.returnType) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} declares no return type`, { line: fn.line, function: fn.name }));
-    }
+function definerDeclarationFindings(file, fn, facts, exposed, definer) {
+  if (!definer) return [];
+  const findings = [];
+  const pathSet = functionOption(fn.node, 'set').some((option) => facts.isSearchPathSet(option))
+    || facts.alterFunctions.some((alter) => alter.name === fn.name && alter.setsPath && alter.index > fn.index);
+  if (!pathSet) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} sets no search_path; add \`set search_path = ''\` (or a pinned schema list) on the create, or an alter function in the same migration`, { line: fn.line, function: fn.name }));
+  if (exposed.has(fn.schema)) {
+    const revoked = revokedRolesFor(fn, facts.grants);
+    if (!revoked.has('public') || !revoked.has('anon')) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} lives in the exposed schema ${fn.schema}; keep it in a non-exposed schema or revoke execute from public and anon in the same migration`, { line: fn.line, function: fn.name }));
+  }
+  if (!fn.node.is_procedure && !fn.node.returnType) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} declares no return type`, { line: fn.line, function: fn.name }));
+  return findings;
+}
 
-    if (functionLanguage(fn.node) !== 'plpgsql') continue;
-    const body = functionBody(fn.node);
-    if (body === null) continue;
-    const ast = await plpgsqlOf(body, fn.node.parameters, functionReturnKind(fn.node));
-    if (ast === null) {
-      if (definer) findings.push(found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} has a body the pass cannot read; a definer body must be plain plpgsql`, { line: fn.line, function: fn.name }));
-      continue;
-    }
-    const queries = dynamicQueries(ast);
-    findings.push(...await dynamicDdlFindings(file, queries, `function ${fn.name}`, fn.line));
-    if (definer) findings.push(...await definerDynamicFindings(file, fn, queries, fn.line));
+async function functionBodyFindings(file, fn, definer) {
+  if (functionLanguage(fn.node) !== 'plpgsql') return [];
+  const body = functionBody(fn.node);
+  if (body === null) return [];
+  const ast = await plpgsqlOf(body, fn.node.parameters, functionReturnKind(fn.node));
+  if (ast === null) {
+    if (definer) return [found(DB_DEFINER_SAFE, file, `${file}:${fn.line} security definer function ${fn.name} has a body the pass cannot read; a definer body must be plain plpgsql`, { line: fn.line, function: fn.name })];
+    return [];
   }
+  const queries = dynamicQueries(ast);
+  const findings = await dynamicDdlFindings(file, queries, `function ${fn.name}`, fn.line);
+  if (definer) findings.push(...await definerDynamicFindings(file, fn, queries, fn.line));
+  return findings;
+}
+
+async function functionFindings(file, fn, facts, exposed) {
+  const definer = securityDefiner(fn.node);
+  const findings = definerDeclarationFindings(file, fn, facts, exposed, definer);
+  findings.push(...await functionBodyFindings(file, fn, definer));
+  return findings;
+}
+
+/** All PL/pgSQL-backed L04/L06 findings for one migration's extracted facts. */
+export async function plpgsqlFindings(file, facts, exposed) {
+  const findings = [];
+  await eachInOrder(facts.doBlocks, async (block) => { findings.push(...await doBlockFindings(file, block)); });
+  await eachInOrder(facts.functions, async (fn) => { findings.push(...await functionFindings(file, fn, facts, exposed)); });
   return findings;
 }