@starci/hfs 4.0.7 → 4.0.9

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

@@ -0,0 +1,37 @@
+// cli.mjs - the one command line of a back end (R147 BE_CLI_REQUIRED).
+//   BE_CLI_REQUIRED       a back end that declares a connection (it has migrations to run) or tracks a command (src/features/cli/)
+//                         declares exactly one app of kind cli, named cli (be/apps/cli), and tracks its image be/apps/cli/Dockerfile:
+//                         one image, run as `cli <group> <command>`. A cli app with another name, or a second one, is refused.
+// Where a command is declared and that every command has its unit spec beside it are eslint-be's (cli-command-shape, and
+// unit-test-colocated over ruleParams.be.unitRoles).
+// Paths are app-relative; the cli app and the cli feature root are read from the slot manifest through the resolver.
+import { found } from './read.mjs';
+
+const CLI_REQUIRED = 'BE_CLI_REQUIRED';
+
+/** The one name of the cli app, its kind, and what its image is called below it. */
+export const CLI_APP = 'cli';
+const CLI_KIND = 'cli';
+const IMAGE = 'Dockerfile';
+const CLI_FEATURE_SLOT = 'be.cli';
+const CLI_APP_SLOT = 'be.app.cli';
+
+/** The findings of R147 over the tracked paths `files` (app-relative) of the app `repo`; `resolver` is the app's. */
+export function cliFindings({ files, repo, resolver }) {
+  if (!repo?.sides) return [];
+  const be = repo.sides.be;
+  const beResolver = resolver.sides?.be ?? resolver;
+  const onBe = files.filter((file) => file.startsWith('be/')).map((file) => file.slice('be/'.length));
+  const tracked = new Set(onBe);
+  const commandFiles = onBe.filter((file) => beResolver.classifyPath(file).slot === CLI_FEATURE_SLOT);
+  const findings = [];
+  const cliApps = be.apps.filter((app) => app.kind === CLI_KIND);
+  // Where the cli app is only optional (litePresence: schema migration is the Supabase CLI's job) a connection no longer forces it; a tracked command still does.
+  const migrates = (be.connections ?? []).length > 0 && beResolver.slot(CLI_APP_SLOT)?.presence !== 'optional';
+  const needs = migrates || commandFiles.length > 0;
+  const why = migrates ? `it declares the connection${be.connections.length === 1 ? '' : 's'} ${be.connections.map((c) => c.name).join(', ')} (their migrations run as \`cli migrate run\`)` : 'it tracks commands under be/src/features/cli/';
+  if (needs && cliApps.length === 0) findings.push(found(CLI_REQUIRED, 'hfs.json', `the back end declares no cli app, but ${why}; declare { "name": "${CLI_APP}", "kind": "${CLI_KIND}" } in sides.be.apps and build be/apps/${CLI_APP} on nest-commander: every one-off action of the back end is one of its commands.`, { needs: why }));
+  for (const app of cliApps.filter((entry) => entry.name !== CLI_APP)) findings.push(found(CLI_REQUIRED, 'hfs.json', `the cli app is named ${app.name}; the back end has ONE cli app, be/apps/${CLI_APP}, so its image and its command line are the same in every app.`, { app: app.name }));
+  if (cliApps.length > 0 && !tracked.has(`apps/${CLI_APP}/${IMAGE}`) && cliApps.some((app) => app.name === CLI_APP)) findings.push(found(CLI_REQUIRED, `be/apps/${CLI_APP}/${IMAGE}`, `be/apps/${CLI_APP} has no image: track be/apps/${CLI_APP}/${IMAGE}, the one cli image every one-off action runs from (\`cli <group> <command>\`).`, { app: CLI_APP }));
+  return findings;
+}

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

@@ -0,0 +1,71 @@
+// contract-compat.mjs - event contracts evolve only additively (BE_CONTRACT_BREAKING, R177).
+//
+// A service publishes its events in `be/contracts/<service>/events.json` (the vendored snapshot hfs emits from the service's event table).
+// The previous published contract is pinned beside it as `be/contracts/<service>/events.pin.json` (the same format, copied when a contract is
+// published). The current snapshot is compared with its pin, event by event:
+//   - every pinned event still exists under the same key, with the same `stream` and `version`;
+//   - every pinned payload field still exists with the same type and the same optionality (`<type>` or `<type>?`);
+//   - a field that is new is optional (events already on the wire do not carry it);
+//   - any other member the pinned event declared (for example `compensates`) is unchanged.
+// Anything else is a breaking change: it needs a NEW event key `<event>.v2` next to the old one, which stays until its consumers have moved.
+// A new event, and a new optional field, are additive and pass. A service with no pin is not judged (the pin is opt-in per service).
+import path from 'node:path';
+import { isPlainObject } from '../../../engine/plain-object.mjs';
+import { found, readJson } from './read.mjs';
+
+export const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
+
+const CONTRACTS = /^be\/contracts\/([^/]+)\/events\.pin\.json$/;
+
+const same = (a, b) => JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (!isPlainObject(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortKeys(value[key])]));
+}
+/** {type, optional} of a payload field spelling (`string`, `number?`, `string[]`). */
+const fieldOf = (spelling) => (typeof spelling === 'string' && spelling.endsWith('?') ? { type: spelling.slice(0, -1), optional: true } : { type: spelling, optional: false });
+
+/** The breaking changes of `current` against `pinned`: [{event, message}]. */
+export function breakingChanges(pinned, current) {
+  const problems = [];
+  const pinnedEvents = isPlainObject(pinned?.events) ? pinned.events : {};
+  const currentEvents = isPlainObject(current?.events) ? current.events : {};
+  for (const [name, before] of Object.entries(pinnedEvents)) {
+    const after = currentEvents[name];
+    if (!isPlainObject(after)) { problems.push({ event: name, message: `event ${name} was removed; a published event is never deleted while it can still be on the wire. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
+    for (const key of Object.keys(before)) {
+      if (key === 'payload') continue;
+      if (!same(before[key], after[key])) problems.push({ event: name, message: `event ${name} changed its ${key} from ${JSON.stringify(before[key])} to ${JSON.stringify(after[key] ?? null)}; a published event keeps its ${key}. Add ${name}.v2 for the new shape.` });
+    }
+    const was = isPlainObject(before.payload) ? before.payload : {};
+    const now = isPlainObject(after.payload) ? after.payload : {};
+    for (const [field, spelling] of Object.entries(was)) {
+      if (!(field in now)) { problems.push({ event: name, message: `event ${name} lost payload field ${field}; fields are only ever added. Keep it, and add ${name}.v2 for the new shape.` }); continue; }
+      const a = fieldOf(spelling);
+      const b = fieldOf(now[field]);
+      if (a.type !== b.type) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.type} to ${b.type}; a field keeps its type. Add ${name}.v2 for the new shape.` });
+      else if (a.optional !== b.optional) problems.push({ event: name, message: `event ${name} changed payload field ${field} from ${a.optional ? 'optional' : 'required'} to ${b.optional ? 'optional' : 'required'}; a field keeps its optionality. Add ${name}.v2 for the new shape.` });
+    }
+    for (const [field, spelling] of Object.entries(now)) {
+      if (!(field in was) && !fieldOf(spelling).optional) problems.push({ event: name, message: `event ${name} gained required payload field ${field}; events already on the wire do not carry it, so a new field is optional (${field}?). Make it optional, or add ${name}.v2.` });
+    }
+  }
+  return problems;
+}
+
+/** R177: the findings of every service whose contract is pinned. `files` are the repository-relative tracked paths. */
+export function contractCompatFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const rel of [...files].sort()) {
+    const match = CONTRACTS.exec(rel);
+    if (!match) continue;
+    const current = `be/contracts/${match[1]}/events.json`;
+    const pinned = readJson(repoRoot, rel);
+    const snapshot = readJson(repoRoot, current);
+    if (!isPlainObject(pinned) || !isPlainObject(pinned.events)) { findings.push(found(CONTRACT_BREAKING, rel, `${rel} is not a readable event contract (an object with an events table); copy a published ${path.posix.basename(current)} over it.`)); continue; }
+    if (!isPlainObject(snapshot) || !isPlainObject(snapshot.events)) { findings.push(found(CONTRACT_BREAKING, current, `${current} is missing or unreadable while ${rel} pins the contract of service ${match[1]}; the contract of a published service is never dropped. Emit it again.`)); continue; }
+    for (const { event, message } of breakingChanges(pinned, snapshot)) findings.push(found(CONTRACT_BREAKING, current, `${current}: ${message}`, { event, service: match[1] }));
+  }
+  return findings;
+}

package/runtime/scripts/{lib/hfs-rules → hfs/rules}/contract.mjs

@@ -2,7 +2,7 @@
 //   a be side with a GraphQL transport commits `contracts/<app>/schema.graphql` for each api app, and an api app with an operation table
 //   commits `contracts/<app>/openapi.json`. The fe side of the same app reads those snapshots where they are (`be/contracts/`, the one
 //   cross-side read of hfs.json sides.fe.reads) for its codegen: there is no copy to keep equal.
-// The snapshots are generated by `npm run contract:emit` (`hfs emit-contracts`, packages/hfs/emit/contracts.mjs): printSchema of the
+// The snapshots are generated by `npm run contract:emit` (`starci app emit`, packages/hfs/emit/contracts.mjs): printSchema of the
 // resolvers the app root composes, and the OpenAPI 3.1 document of the typed operation table `apps/<app>/src/operations.ts`.
 // That the committed snapshot equals what the app emits now is contractEmitFindings (full pass only, never --fast): it emits every
 // api app into a temp directory through the injected `emit` (packages/hfs/emit) and compares hashes; an emit that cannot run is a finding.
@@ -10,20 +10,20 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { found } from './read.mjs';
-import { safeRemoveTree } from '../safe-remove.mjs';
+import { found, readText } from './read.mjs';
+import { safeRemove } from '../../api/fs/safe-remove.mjs';
 
 export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
-export const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
+const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
 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. */
-export function contractHash(file) {
+function contractHash(file) {
   try { return createHash('sha256').update(fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n')).digest('hex'); } catch { return null; }
 }
 
 /** The findings of R23 for the be side at `repoRoot` (a side of another profile has none). */
-export function contractFindings({ files, repo, resolver }) {
+export function contractFindings({ repoRoot, files, repo, resolver }) {
   const findings = [];
   if (repo.profile !== 'be') return findings;
   const serves = files.some((file) => resolver.classifyPath(file).slot === GRAPHQL_TRANSPORT_SLOT);
@@ -31,7 +31,8 @@ export function contractFindings({ files, repo, resolver }) {
   for (const app of repo.apps.filter((a) => a.kind === 'api')) {
     const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
     if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
-    if (!serves) continue;
+    // An app serves GraphQL when its root module composes the platform graphql capability; a repository with a GraphQL transport slot does not make every api app one.
+    if (!serves || !(readText(repoRoot, `apps/${app.name}/src/app.module.ts`) ?? '').includes('platform/graphql')) continue;
     const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
     if (!tracked.has(snapshot)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
   }
@@ -65,7 +66,7 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
       } 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: \`hfs emit-contracts\` failed for ${app.name}: ${errorText(error)}`, { app: app.name, drift: 'emit-failed' }));
+        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' }));
         continue;
       }
       for (const { artifact, what } of artifacts) {
@@ -93,7 +94,8 @@ export function contractEmitFindings({ repoRoot, files, repo, emit }) {
       }
     }
   } finally {
-    safeRemoveTree(scratch);
+    // A temp directory this rule made itself, in no ledger's repository: no indexed job artifact can live in it.
+    safeRemove(scratch, { hold: () => null });
   }
   return { findings, apps };
 }

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

@@ -0,0 +1,102 @@
+// database-config.mjs - L08 Supabase TOML policy and L09 generated-type drift checks. Parsing and type emission stay
+// lazy/injected so applications without Supabase do not load either tool and this rule starts no Docker process.
+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 PUBLIC_KEYS = new Set(['anon_key', 'publishable_key', 'public_key']);
+
+
+function tomlEntries(value, path = []) {
+  if (!value || typeof value !== 'object') return [];
+  if (Array.isArray(value)) return value.flatMap((item) => tomlEntries(item, path));
+  return Object.entries(value).flatMap(([key, child]) => {
+    const at = [...path, key];
+    if (child && typeof child === 'object') {
+      if (Array.isArray(child)) {
+        if (child.every((item) => item && typeof item === 'object' && !Array.isArray(item))) return child.flatMap((item) => tomlEntries(item, at));
+      } else return tomlEntries(child, at);
+    }
+    return [[at.join('.'), key, child]];
+  });
+}
+
+const isCredentialKey = (key) => {
+  const leaf = key.toLowerCase();
+  return ['secret', 'client_id', 'key', 'pass', 'password', 'token'].includes(leaf)
+    || /_(secret|password|token|client_id|api_key)$/.test(leaf)
+    || (leaf.endsWith('_key') && !PUBLIC_KEYS.has(leaf));
+};
+
+const tomlLine = (text, key) => {
+  const expression = new RegExp(`^\\s*["']?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']?\\s*=`, 'm');
+  const match = expression.exec(text);
+  return match ? text.slice(0, match.index).split('\n').length : undefined;
+};
+
+/** 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);
+  } catch {
+    return null;
+  }
+}
+
+/** 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 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' }));
+  }
+  if (!supabase) return findings;
+  const declared = {
+    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 }));
+    }
+  }
+  return findings;
+}
+
+/** L09 drift findings for the committed generated database type file. */
+export async function typesFindings({ repoRoot, files, emitTypes, declaration }) {
+  if (typeof emitTypes !== 'function') return [];
+  const tracked = new Set(files);
+  let emitted;
+  try { emitted = await emitTypes({ repoRoot, declaration }); } catch (error) {
+    return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} cannot be verified: the types emit failed (${String(error?.message ?? error).split('\n').filter(Boolean).slice(0, 3).join(' | ')})`, { drift: 'emit-failed' })];
+  }
+  const committed = tracked.has(TYPES_FILE) ? readText(repoRoot, TYPES_FILE) : null;
+  if (committed === null) return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} is not committed; run \`npm run contract:emit\` and commit the generated types`, { drift: 'not-committed' })];
+  if (!sameText(committed, String(emitted))) return [found(DB_TYPES_DRIFT, TYPES_FILE, `${TYPES_FILE} differs from what \`contract:emit\` generates from the migrations now; run \`npm run contract:emit\` and commit the result`, { drift: 'stale' })];
+  return [];
+}

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

@@ -0,0 +1,13 @@
+// Single source of database-rule finding codes and owned Supabase paths.
+export const DB_MIGRATION_SHAPE = 'DB_MIGRATION_SHAPE';
+export const DB_RLS_REQUIRED = 'DB_RLS_REQUIRED';
+export const DB_DYNAMIC_DDL = 'DB_DYNAMIC_DDL';
+export const DB_POLICY_SHAPE = 'DB_POLICY_SHAPE';
+export const DB_DEFINER_SAFE = 'DB_DEFINER_SAFE';
+export const DB_STORAGE_POLICY = 'DB_STORAGE_POLICY';
+export const DB_CONFIG_POLICY = 'DB_CONFIG_POLICY';
+export const DB_TYPES_DRIFT = 'DB_TYPES_DRIFT';
+
+export const MIGRATIONS_DIR = 'supabase/migrations';
+export const CONFIG_FILE = 'supabase/config.toml';
+export const TYPES_FILE = 'supabase/types/database.types.ts';

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

@@ -0,0 +1,111 @@
+// database-migrations.mjs - L02 migration name, UTC ordering and base-branch immutability checks. Git reads go
+// through the runtime API call files, and specs may inject the same small runner contract used by database.mjs.
+import { lsTree } from '../../api/git/ls-tree.mjs';
+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 { sameText } from '../../lib/same-text.mjs';
+import { found, readText } from './read.mjs';
+import { DB_MIGRATION_SHAPE, MIGRATIONS_DIR } from './database-constants.mjs';
+const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*)\.sql$/;
+
+/** `<ts14>` -> the UTC instant it names, or null when the digits are no real time (month 13, day 32, ...). */
+export function migrationStamp(text) {
+  const [year, month, day, hour, minute, second] = [Number(text.slice(0, 4)), ...[4, 6, 8, 10, 12].map((at) => Number(text.slice(at, at + 2)))];
+  const stamp = Date.UTC(year, month - 1, day, hour, minute, second);
+  const date = new Date(stamp);
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+    && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second ? stamp : null;
+}
+
+/** The three git reads L02 makes: (args, {cwd}) -> {ok, stdout}. */
+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;
+  const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
+  return { ok: !result.error && result.status === 0, stdout: result.stdout };
+}
+
+const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
+  .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']) {
+    const result = await runGit(git, repoRoot, ['merge-base', 'HEAD', ref]);
+    if (result.ok && result.stdout.trim()) return { ref, sha: result.stdout.trim() };
+  }
+  return null;
+}
+
+async function baseMigrationNames(git, repoRoot, sha) {
+  const result = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', sha, '--', MIGRATIONS_DIR]);
+  if (!result.ok) return [];
+  const prefix = `${MIGRATIONS_DIR}/`;
+  return result.stdout.split('\0').filter(Boolean).map((entry) => (entry.startsWith(prefix) ? entry.slice(prefix.length) : entry));
+}
+
+async function baseFileText(git, repoRoot, sha, file) {
+  const result = await runGit(git, repoRoot, ['show', `${sha}:${file}`]);
+  return result.ok ? result.stdout : null;
+}
+
+async function migrationTimeLimit(git, repoRoot, file, now) {
+  const result = await runGit(git, repoRoot, ['log', '-1', '--format=%ct', '--', file]);
+  const seconds = Number(result.stdout.trim());
+  if (result.ok && Number.isFinite(seconds) && seconds > 0) return { at: seconds * 1000, tracked: true };
+  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 }) {
+  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) {
+    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;
+    }
+    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;
+    }
+    const limit = await migrationTimeLimit(git, repoRoot, entry.file, now);
+    if (stamp > limit.at) {
+      const boundary = limit.tracked ? `the file's commit time ${new Date(limit.at).toISOString()}` : `the current time ${new Date(limit.at).toISOString()}`;
+      findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, in the future relative to ${boundary}; a migration stamp is its real creation time, never a hand-picked date`, { stamp: entry.match[1], tracked: limit.tracked }));
+    }
+    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);
+  }
+  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 }));
+  }
+  return findings;
+}

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

@@ -0,0 +1,233 @@
+// 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 { parsePlpgsqlBody, parseSql } from '../sql/pg-parse.mjs';
+import { DB_DEFINER_SAFE, DB_DYNAMIC_DDL } from './database-constants.mjs';
+
+const sval = (node) => node?.String?.sval;
+const nameOf = (list, defaultSchema) => {
+  const parts = (list ?? []).map(sval).filter((part) => part !== undefined);
+  return parts.length === 1 && defaultSchema ? `${defaultSchema}.${parts[0]}` : parts.join('.');
+};
+
+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 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);
+  if (name === 'void') return 'void';
+  if (name === 'trigger' || name === 'event_trigger') return 'trigger';
+  return node.returnType?.setof ? 'setof' : 'scalar';
+};
+
+/** 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);
+  return out;
+}
+
+async function plpgsqlOf(body, parameters, returnKind) {
+  try {
+    return await parsePlpgsqlBody(body, parameters, returnKind);
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a PL/pgSQL dynamic-query source as one PostgreSQL expression. */
+async function expressionOf(text) {
+  try {
+    const parsed = await parseSql(`select ${text}`);
+    return parsed.stmts?.[0]?.stmt?.SelectStmt?.targetList?.[0]?.ResTarget?.val ?? null;
+  } catch {
+    return null;
+  }
+}
+
+const stringValue = (node) => node?.A_Const?.sval?.sval;
+const formatName = (node) => node?.FuncCall?.funcname?.map(sval).filter(Boolean).join('.').toLowerCase() === 'format';
+const operatorName = (node) => node?.A_Expr?.name?.map(sval).filter(Boolean).join('');
+const FORMAT_SPECIFIER = /%(?:(\d+)\$)?-?(?:\d+|\*(?:\d+\$)?)?([sIL%])/g;
+
+/** Every format() conversion, or null when the template contains an invalid/unreadable percent sequence. */
+function formatSpecifiers(template) {
+  const specs = [];
+  let cursor = 0;
+  for (const match of template.matchAll(FORMAT_SPECIFIER)) {
+    if (template.slice(cursor, match.index).includes('%')) return null;
+    specs.push({ position: match[1] ? Number(match[1]) - 1 : null, type: match[2] });
+    cursor = match.index + match[0].length;
+  }
+  return template.slice(cursor).includes('%') ? null : specs;
+}
+
+/** Render enough of a dynamic expression to let the PostgreSQL parser identify its generated statement kind. */
+function renderExpression(node) {
+  const literal = stringValue(node);
+  if (literal !== undefined) return { text: literal, complete: true };
+  if (node?.TypeCast) return renderExpression(node.TypeCast.arg);
+  if (operatorName(node) === '||') {
+    const left = renderExpression(node.A_Expr.lexpr);
+    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 };
+  }
+  return { text: 'hfs_dynamic', complete: false };
+}
+
+/** DDL statement kinds forbidden behind dynamic execution. */
+function containsDynamicDdl(parsed) {
+  for (const entry of parsed.stmts ?? []) {
+    const type = Object.keys(entry.stmt ?? {})[0];
+    if (['CreateStmt', 'CreateTableAsStmt', 'CreatePolicyStmt', 'CreateFunctionStmt', 'AlterTableStmt', 'AlterFunctionStmt', 'AlterPolicyStmt', 'AlterDefaultPrivilegesStmt', 'GrantStmt', 'GrantRoleStmt', 'RenameStmt'].includes(type)) return true;
+    if (type === 'DropStmt' && ['OBJECT_TABLE', 'OBJECT_POLICY', 'OBJECT_FUNCTION'].includes(entry.stmt.DropStmt?.removeType)) return true;
+  }
+  return false;
+}
+
+async function dynamicQueryAnalysis(text) {
+  const expression = await expressionOf(text);
+  if (expression === null) return { buildsDdl: false, opaque: true };
+  const rendered = renderExpression(expression);
+  try {
+    const parsed = await parseSql(rendered.text);
+    return { buildsDdl: containsDynamicDdl(parsed), opaque: false };
+  } catch {
+    return { buildsDdl: false, opaque: !rendered.complete };
+  }
+}
+
+async function dynamicDdlFindings(file, queries, where, baseLine) {
+  const findings = [];
+  for (const { text, lineno } of queries) {
+    const line = lineno ? baseLine + lineno - 1 : undefined;
+    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 }));
+    } 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 }));
+    }
+  }
+  return findings;
+}
+
+/** A definer expression is safe when it consists only of literals and format() calls whose conversions quote. */
+function safeDefinerExpression(node) {
+  if (stringValue(node) !== undefined) return true;
+  if (node?.TypeCast) return safeDefinerExpression(node.TypeCast.arg);
+  if (operatorName(node) === '||') return safeDefinerExpression(node.A_Expr.lexpr) && safeDefinerExpression(node.A_Expr.rexpr);
+  if (!formatName(node)) return false;
+  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));
+}
+
+async function definerDynamicFindings(file, fn, queries, baseLine) {
+  const findings = [];
+  for (const { text, lineno } of queries) {
+    const line = lineno ? baseLine + lineno - 1 : undefined;
+    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 }));
+  }
+  return findings;
+}
+
+function revokedRolesFor(fn, grants) {
+  const roles = new Set();
+  for (const grant of grants) {
+    if (grant.grant || grant.objtype !== 'OBJECT_FUNCTION') continue;
+    if (!grant.privileges.includes('execute') && !grant.privileges.includes('all')) continue;
+    const matches = grant.objects.some((object) => nameOf(object?.ObjectWithArgs?.objname, grant.defaultSchema) === fn.name);
+    if (matches) for (const role of grant.grantees) roles.add(role);
+  }
+  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));
+  }
+
+  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 }));
+    }
+
+    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));
+  }
+  return findings;
+}