@starci/hfs 4.3.0 → 4.4.1

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

@@ -1,8 +1,15 @@
 // 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';
+import path from 'node:path';
+import { parse as parseTomlSync } from 'smol-toml';
+import { found, readJson, readText } from './read.mjs';
+import {
+  CONFIG_FILE, DB_API_EXPOSED, DB_CONFIG_POLICY, DB_EXTENSION_ALLOWED, DB_TYPES_DRIFT, DB_VAULT_WRITE,
+  HFS_SEED_PII, isActiveMigration, TYPES_FILE,
+} from './database-constants.mjs';
+import { databaseExecutableTokens, databaseSqlStatements, databaseSqlTokens, destructiveMigrationFindings } from './database-migrations.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
 const ENV_REF = /^env\([A-Za-z_]\w*\)$/;
 const PUBLIC_KEYS = new Set(['anon_key', 'publishable_key', 'public_key']);
 
@@ -125,3 +132,244 @@ export async function typesFindings({ repoRoot, files, emitTypes, declaration })
   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 [];
 }
+
+const DEFAULT_EXTENSIONS = ['pgmq', 'pg_cron', 'pgcrypto', 'pg_trgm', 'vector', 'uuid-ossp', 'pg_net', 'supabase_vault', 'unaccent'];
+const DEFAULT_API_SCHEMAS = ['public', 'graphql_public'];
+const FORBIDDEN_API_SCHEMAS = new Set(['pgmq', 'pgmq_public']);
+const word = (token, value) => token?.t === 'word' && token.v === value;
+const identifier = (token) => token && ['word', 'ident'].includes(token.t) ? token.v : null;
+
+function dbParameters(manifest) {
+  const declared = manifest?.ruleParams?.db ?? {};
+  return {
+    extensions: Array.isArray(declared.extensions) ? declared.extensions : DEFAULT_EXTENSIONS,
+    apiSchemas: Array.isArray(declared.apiSchemas) ? declared.apiSchemas : DEFAULT_API_SCHEMAS,
+    majorVersion: declared.majorVersion ?? 17,
+  };
+}
+
+function qualifiedName(tokens, index) {
+  const name = identifier(tokens[index]);
+  if (name === null) return null;
+  return tokens[index + 1]?.v === '.' && identifier(tokens[index + 2]) !== null
+    ? { schema: name, name: identifier(tokens[index + 2]), next: index + 3 }
+    : { schema: 'public', name, next: index + 1 };
+}
+
+function extensionFindings(file, tokens, allowed) {
+  const findings = [];
+  for (let index = 0; index < tokens.length; index += 1) {
+    if (!word(tokens[index], 'create') || !word(tokens[index + 1], 'extension')) continue;
+    let at = index + 2;
+    if (word(tokens[at], 'if') && word(tokens[at + 1], 'not') && word(tokens[at + 2], 'exists')) at += 3;
+    const name = identifier(tokens[at]);
+    if (name !== null && !allowed.has(name)) findings.push(found(DB_EXTENSION_ALLOWED, file,
+      `${file}:${tokens[index].line} enables extension ${name}, which ruleParams.db.extensions does not allow`, { line: tokens[index].line, extension: name }));
+  }
+  return findings;
+}
+
+function vaultWriteAt(tokens, index) {
+  const token = tokens[index];
+  if (identifier(token) === 'vault' && tokens[index + 1]?.v === '.' && tokens[index + 3]?.v === '(') {
+    return ['create_secret', 'update_secret', 'delete_secret'].includes(identifier(tokens[index + 2]));
+  }
+  let at = null;
+  if (word(token, 'insert') || word(token, 'merge')) at = word(tokens[index + 1], 'into') ? index + 2 : null;
+  if (word(token, 'delete')) at = word(tokens[index + 1], 'from') ? index + 2 : null;
+  if (word(token, 'update')) at = index + 1;
+  if (word(token, 'truncate')) return truncatedVault(tokens, index);
+  if (at === null) return false;
+  if (word(tokens[at], 'only')) at += 1;
+  return qualifiedName(tokens, at)?.schema === 'vault';
+}
+
+function truncatedVault(tokens, index) {
+  let at = word(tokens[index + 1], 'table') ? index + 2 : index + 1;
+  while (at < tokens.length) {
+    if (word(tokens[at], 'only')) at += 1;
+    const name = qualifiedName(tokens, at);
+    if (!name) return false;
+    if (name.schema === 'vault') return true;
+    if (tokens[name.next]?.v !== ',') return false;
+    at = name.next + 1;
+  }
+  return false;
+}
+
+function passwordStatement(statement) {
+  const starts = statement.findIndex((token, index) => (word(token, 'create') || word(token, 'alter'))
+    && (word(statement[index + 1], 'role') || word(statement[index + 1], 'user')));
+  return starts !== -1 && statement.slice(starts + 2).some((token) => word(token, 'password')) ? statement[starts] : null;
+}
+
+function custodySqlFindings(file, tokens) {
+  const findings = [];
+  for (const statement of databaseSqlStatements(tokens)) {
+    const password = passwordStatement(statement);
+    if (password) findings.push(found(DB_VAULT_WRITE, file,
+      `${file}:${password.line} sets a role password in a migration; provision credentials through sealed secret custody`, { line: password.line, operation: 'role-password' }));
+    const vault = statement.find((token, index) => vaultWriteAt(statement, index));
+    if (vault) findings.push(found(DB_VAULT_WRITE, file,
+      `${file}:${vault.line} writes to vault; migration SQL never provisions secret values`, { line: vault.line, operation: 'vault-write' }));
+  }
+  return findings;
+}
+
+function policyTarget(statement, start) {
+  const on = statement.findIndex((token, index) => index > start && word(token, 'on'));
+  return on === -1 ? null : qualifiedName(statement, on + 1);
+}
+
+function policyRoles(statement) {
+  const to = statement.findIndex((token) => word(token, 'to'));
+  if (to === -1) return null;
+  const end = statement.findIndex((token, index) => index > to && (word(token, 'using') || word(token, 'with')));
+  return statement.slice(to + 1, end === -1 ? undefined : end).map(identifier).filter(Boolean);
+}
+
+function applyPublicReadPolicy(statement, policies) {
+  const at = statement.findIndex((token, index) => ['create', 'alter', 'drop'].some((verb) => word(token, verb)) && word(statement[index + 1], 'policy'));
+  if (at === -1) return;
+  const verb = statement[at].v;
+  let nameAt = at + 2;
+  if (word(statement[nameAt], 'if') && word(statement[nameAt + 1], 'exists')) nameAt += 2;
+  const name = identifier(statement[nameAt]);
+  const target = policyTarget(statement, nameAt);
+  if (!name || !target) return;
+  const key = `${target.schema}.${target.name}.${name}`;
+  if (verb === 'drop') { policies.delete(key); return; }
+  const rename = statement.findIndex((token) => word(token, 'rename'));
+  if (verb === 'alter' && word(statement[rename + 1], 'to')) {
+    const nextName = identifier(statement[rename + 2]);
+    if (nextName && policies.has(key)) {
+      policies.set(`${target.schema}.${target.name}.${nextName}`, { ...policies.get(key), name: nextName });
+      policies.delete(key);
+    }
+    return;
+  }
+  const roles = policyRoles(statement);
+  if (verb === 'alter') {
+    if (policies.has(key) && roles !== null) policies.set(key, { ...policies.get(key), roles });
+    return;
+  }
+  const forAt = statement.findIndex((token) => word(token, 'for'));
+  policies.set(key, { name, schema: target.schema, select: word(statement[forAt + 1], 'select'), roles: roles ?? ['public'] });
+}
+
+function publicReadSchemas(sources) {
+  const policies = new Map();
+  for (const { tokens } of sources) for (const statement of databaseSqlStatements(tokens)) applyPublicReadPolicy(statement, policies);
+  return new Set([...policies.values()].filter((policy) => policy.select && policy.name.endsWith('_public_read')
+    && policy.roles.some((role) => ['anon', 'public'].includes(role))).map((policy) => policy.schema));
+}
+
+function schemaConfigFindings(file, config, parameters, edition, publicSchemas) {
+  const schemas = config.api?.schemas;
+  const findings = [];
+  const allowed = new Set(parameters.apiSchemas);
+  if (!Array.isArray(schemas) || schemas.some((schema) => typeof schema !== 'string' || !allowed.has(schema))) {
+    findings.push(found(DB_CONFIG_POLICY, file, `${file} api.schemas must be an array drawn from ruleParams.db.apiSchemas`, { key: 'api.schemas' }));
+  }
+  if (Array.isArray(schemas) && schemas.some((schema) => FORBIDDEN_API_SCHEMAS.has(schema))) findings.push(found(DB_API_EXPOSED, file,
+    `${file} api.schemas exposes a pgmq schema; queues are accessible only to the application role`, { key: 'api.schemas' }));
+  const exposed = Array.isArray(schemas) ? schemas : DEFAULT_API_SCHEMAS;
+  if (edition === 'lite' && config.api?.enabled !== false && exposed.length > 0 && !exposed.some((schema) => publicSchemas.has(schema))) {
+    findings.push(found(DB_API_EXPOSED, file, `${file} enables the lite data API without an exposed *_public_read FOR SELECT policy; disable api or set schemas = []`, { key: 'api.enabled' }));
+  }
+  return findings;
+}
+
+function safetyConfigFindings(file, config, parameters, supabase) {
+  const findings = [];
+  const anonymous = config.auth?.enable_anonymous_sign_ins;
+  if (anonymous !== undefined && (typeof anonymous !== 'boolean' || (anonymous && supabase?.enableAnonymousSignIns !== true))) findings.push(found(DB_CONFIG_POLICY, file,
+    `${file} auth.enable_anonymous_sign_ins is enabled without hfs.json supabase.enableAnonymousSignIns`, { key: 'auth.enable_anonymous_sign_ins' }));
+  if (config.edge_runtime?.enabled !== false) findings.push(found(DB_CONFIG_POLICY, file,
+    `${file} edge_runtime.enabled must be false; application execution belongs to the back end`, { key: 'edge_runtime.enabled' }));
+  const storageLimit = config.storage?.file_size_limit;
+  if (config.storage?.enabled !== false && (typeof storageLimit !== 'string' || !/^[1-9]\d*(?:B|KB|MB|GB|KiB|MiB|GiB)$/.test(storageLimit))) findings.push(found(DB_CONFIG_POLICY, file,
+    `${file} storage.file_size_limit must declare a positive byte limit`, { key: 'storage.file_size_limit' }));
+  if (config.db?.major_version !== parameters.majorVersion) findings.push(found(DB_CONFIG_POLICY, file,
+    `${file} db.major_version must equal the ruleParams.db.majorVersion pin (${parameters.majorVersion})`, { key: 'db.major_version' }));
+  return findings;
+}
+
+function seedPattern(value) {
+  if (typeof value !== 'string' || !value || value.includes('\\') || path.posix.isAbsolute(value) || /^[A-Za-z]:/.test(value)) return null;
+  const relative = path.posix.normalize(`supabase/${value}`);
+  if (!relative.startsWith('supabase/')) return null;
+  const expression = relative.split(/(\*\*|\*|\?)/).map((part) => {
+    if (part === '**') return '.*';
+    if (part === '*') return '[^/]*';
+    if (part === '?') return '[^/]';
+    return escapeRegexPart(part);
+  }).join('');
+  return new RegExp(`^${expression}$`);
+}
+
+function seedConfigResult(repoRoot, files, config) {
+  const seeds = new Set(files.filter((file) => /^(?:supabase\/(?:seed\.sql|seeds?\/.+\.sql)|\.starcistacks\/[^/]+\/seeds\/.+\.sql)$/.test(file)));
+  const seed = config?.db?.seed;
+  if (!seed || seed.enabled === false) return { findings: [], seeds };
+  const paths = seed.sql_paths ?? ['./seed.sql'];
+  const findings = [];
+  if (!Array.isArray(paths) || paths.length === 0) return {
+    seeds, findings: [found(DB_CONFIG_POLICY, CONFIG_FILE, `${CONFIG_FILE} db.seed.sql_paths must list tracked SQL seed files`, { key: 'db.seed.sql_paths' })],
+  };
+  for (const value of paths) {
+    const pattern = seedPattern(value);
+    const matches = pattern ? files.filter((file) => file.endsWith('.sql') && pattern.test(file) && readText(repoRoot, file) !== null) : [];
+    if (matches.length === 0) findings.push(found(DB_CONFIG_POLICY, CONFIG_FILE,
+      `${CONFIG_FILE} db.seed.sql_paths contains a path with no readable tracked SQL seed file`, { key: 'db.seed.sql_paths' }));
+    for (const file of matches) seeds.add(file);
+  }
+  return { findings, seeds };
+}
+
+const EMAIL_LITERAL = /^[A-Z0-9._%+-]+@([A-Z0-9-]+(?:\.[A-Z0-9-]+)+)$/i;
+function piiLiteral(value) {
+  if (value.split(/[^\w.%+@-]+/).some((part) => {
+    const email = EMAIL_LITERAL.exec(part);
+    return email && email[1].toLowerCase() !== 'example.test';
+  })) return true;
+  if (!/^\+?[\d\s().-]+$/.test(value)) return false;
+  const digits = value.replaceAll(/\D/g, '');
+  if (digits.length < 9 || digits.length > 15 || /^\d{4}-\d{2}-\d{2}(?:\s|$)/.test(value)) return false;
+  return value.startsWith('+') || /[()\s]/.test(value) || /^\d{10,15}$/.test(value);
+}
+
+function seedPiiFindings(repoRoot, seeds) {
+  const findings = [];
+  for (const file of seeds) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    for (const token of databaseSqlTokens(text)) {
+      if (!['string', 'body'].includes(token.t) || !piiLiteral(token.v)) continue;
+      findings.push(found(HFS_SEED_PII, file, `${file}:${token.line} contains an email or phone literal; seed data uses synthetic identities and the example.test domain`, { line: token.line }));
+    }
+  }
+  return findings;
+}
+
+/** R259 config/content checks, synchronously judged at the app root for both editions. */
+export function databaseConfigFindings({ repoRoot, files = [], all = files, repo = {}, manifest, isRoot, inScope = () => true }) {
+  if (isRoot === false || ['be', 'fe'].includes(repo.profile)) return [];
+  const parameters = dbParameters(manifest);
+  const declaration = readJson(repoRoot, 'hfs.json');
+  const edition = repo.edition ?? declaration?.edition ?? 'full';
+  const migrations = all.filter((file) => isActiveMigration(file) && file.endsWith('.sql')).sort(byCodeUnit);
+  const sources = migrations.map((file) => ({ file, tokens: databaseExecutableTokens(readText(repoRoot, file) ?? '') }));
+  const findings = [];
+  for (const { file, tokens } of sources) findings.push(...extensionFindings(file, tokens, new Set(parameters.extensions)), ...custodySqlFindings(file, tokens));
+  findings.push(...destructiveMigrationFindings({ repoRoot, migrations, files: all }));
+  let config = null;
+  if (all.includes(CONFIG_FILE)) {
+    try { const text = readText(repoRoot, CONFIG_FILE); if (text !== null) config = parseTomlSync(text); } catch { /* L08 owns invalid TOML. */ }
+  }
+  if (config) findings.push(...schemaConfigFindings(CONFIG_FILE, config, parameters, edition, publicReadSchemas(sources)),
+    ...safetyConfigFindings(CONFIG_FILE, config, parameters, declaration?.supabase));
+  const seeds = seedConfigResult(repoRoot, all, config);
+  findings.push(...seeds.findings, ...seedPiiFindings(repoRoot, seeds.seeds));
+  return findings.filter((finding) => inScope(finding.path));
+}

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

@@ -7,6 +7,15 @@ 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 DB_BASELINE_SHAPE = 'DB_BASELINE_SHAPE';
+export const DB_ARCHIVE_MUTATED = 'DB_ARCHIVE_MUTATED';
+export const DB_PGMQ_DECLARED = 'DB_PGMQ_DECLARED';
+export const DB_CRON_OWNED = 'DB_CRON_OWNED';
+export const DB_EXTENSION_ALLOWED = 'DB_EXTENSION_ALLOWED';
+export const DB_API_EXPOSED = 'DB_API_EXPOSED';
+export const DB_MIGRATION_DESTRUCTIVE = 'DB_MIGRATION_DESTRUCTIVE';
+export const HFS_SEED_PII = 'HFS_SEED_PII';
+export const DB_VAULT_WRITE = 'DB_VAULT_WRITE';
 
 export const MIGRATIONS_DIR = 'supabase/migrations';
 /** The migrations retired at a baseline cutover (slot app.supabase.migrations.archive): never applied, never judged by L02-L08. */

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

@@ -7,8 +7,16 @@ 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, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
-const MIGRATION_NAME = /^(\d{14})_([a-z0-9]+(?:-[a-z0-9]+)*)\.sql$/;
+import { DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
+import path from 'node:path';
+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$/;
+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;
 
 /** `<ts14>` -> the UTC instant it names, or null when the digits are no real time (month 13, day 32, ...). */
 export function migrationStamp(text) {
@@ -84,14 +92,33 @@ function migrationHistory(files, retired, localNames) {
   return { onHead, latest: stamps.length ? Math.max(...stamps) : null };
 }
 
-function migrationOrderingFindings(local, history) {
+function migrationOrderingFindings(local, history, restamped = new Set()) {
   return local.flatMap((entry) => {
     const stamp = entry.match ? migrationStamp(entry.match[1]) : null;
-    if (history.onHead.has(entry.name) || stamp === null || history.latest === null || stamp > history.latest) return [];
+    if (history.onHead.has(entry.name) || restamped.has(entry.name) || stamp === null || history.latest === null || stamp > history.latest) return [];
     return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration already in repository history (latest active ${new Date(history.latest).toISOString()}); a new migration sorts after the committed active chain`, { stamp: entry.match[1], latest: new Date(history.latest).toISOString() })];
   });
 }
 
+/** A restamp changes only the version, and its header proves the explicit old->new map against repository SQL. */
+async function verifiedRestamps(local, files, repoRoot, git, sha) {
+  const prefix = `${MIGRATIONS_DIR}/`;
+  const active = files.filter(isActiveMigration).map((file) => file.slice(prefix.length));
+  const claims = local.map((entry) => ({ ...entry, header: RESTAMP_HEADER.exec(readText(repoRoot, entry.file) ?? '') })).filter((entry) => entry.header);
+  const accepted = [];
+  await eachInOrder(claims, async (entry) => {
+    const [, oldStamp, newStamp] = entry.header;
+    if (!entry.match || entry.match[1] !== newStamp || migrationStamp(oldStamp) === null || oldStamp === newStamp) return;
+    if (claims.filter((claim) => claim.header[1] === oldStamp).length !== 1) return;
+    const names = active.filter((name) => name.startsWith(`${oldStamp}_`) && name.slice(14) === entry.name.slice(14));
+    if (names.length !== 1 || local.some((candidate) => candidate.name === names[0])) return;
+    const committed = await baseFileText(git, repoRoot, sha, `${prefix}${names[0]}`);
+    if (committed === null || !sameText(withoutRestampHeader(readText(repoRoot, entry.file)), withoutRestampHeader(committed))) return;
+    accepted.push({ source: names[0], destination: entry.name });
+  });
+  return accepted;
+}
+
 async function baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase) {
   if (!entry.match) return [];
   if (onBase.has(entry.name)) {
@@ -124,11 +151,15 @@ export async function migrationShapeFindings({ repoRoot, migrations, archived =
   });
   const findings = localMigrationFindings(local);
   const retired = new Set(archived.map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1)));
-  const history = migrationHistory(await migrationFilesAt(git, repoRoot, 'HEAD'), retired, new Set(local.map((entry) => entry.name)));
-  findings.push(...migrationOrderingFindings(local, history));
+  const headFiles = await migrationFilesAt(git, repoRoot, 'HEAD');
   const baseSha = await baseShaOf(git, repoRoot, base);
+  const baseFiles = baseSha ? await migrationFilesAt(git, repoRoot, baseSha.sha) : [];
+  const restamps = await verifiedRestamps(local, baseSha ? baseFiles : headFiles, repoRoot, git, baseSha?.sha ?? 'HEAD');
+  for (const restamp of restamps) retired.add(restamp.source);
+  const history = migrationHistory(headFiles, retired, new Set(local.map((entry) => entry.name)));
+  findings.push(...migrationOrderingFindings(local, history, new Set(restamps.map((entry) => entry.destination))));
   if (!baseSha) return findings;
-  const baseNames = (await migrationFilesAt(git, repoRoot, baseSha.sha)).filter(isActiveMigration).map((file) => file.slice(prefix.length));
+  const baseNames = baseFiles.filter(isActiveMigration).map((file) => file.slice(prefix.length));
   const onBase = new Set(baseNames);
   await eachInOrder(local, async (entry) => {
     findings.push(...await baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase));
@@ -136,3 +167,251 @@ export async function migrationShapeFindings({ repoRoot, migrations, archived =
   findings.push(...removedMigrationFindings(local, retired, baseNames, baseSha));
   return findings;
 }
+
+const sqlName = (token) => token && ['word', 'ident'].includes(token.t) ? token.v : null;
+const sqlWord = (token, value) => token?.t === 'word' && token.v === value;
+
+function commentEnd(text, start) {
+  if (text.startsWith('--', start)) {
+    const end = text.indexOf('\n', start + 2);
+    return end === -1 ? text.length : end;
+  }
+  if (!text.startsWith('/*', start)) return null;
+  let depth = 1;
+  let index = start + 2;
+  while (index < text.length && depth > 0) {
+    if (text.startsWith('/*', index)) { depth += 1; index += 2; }
+    else if (text.startsWith('*/', index)) { depth -= 1; index += 2; }
+    else index += 1;
+  }
+  return index;
+}
+
+function quotedToken(text, start, quote, escaped = false) {
+  let index = start + 1;
+  let value = '';
+  while (index < text.length) {
+    if (text[index] === quote && text[index + 1] === quote) { value += quote; index += 2; }
+    else if (text[index] === quote) return { value, end: index + 1 };
+    else if (escaped && text[index] === '\\') { value += text[index + 1] ?? ''; index += 2; }
+    else { value += text[index]; index += 1; }
+  }
+  return { value, end: index };
+}
+
+function sqlTokenAt(text, index) {
+  const char = text[index];
+  if (char === "'" || char === '"') {
+    const token = quotedToken(text, index, char);
+    return { t: char === '"' ? 'ident' : 'string', v: token.value, end: token.end };
+  }
+  if (/[eE]/.test(char) && text[index + 1] === "'") {
+    const token = quotedToken(text, index + 1, "'", true);
+    return { t: 'string', v: token.value, end: token.end };
+  }
+  const tag = char === '$' ? /^\$(?:[A-Za-z_]\w*)?\$/.exec(text.slice(index))?.[0] : null;
+  if (tag) {
+    const end = text.indexOf(tag, index + tag.length);
+    return { t: 'body', v: text.slice(index + tag.length, end === -1 ? text.length : end), end: end === -1 ? text.length : end + tag.length };
+  }
+  const word = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(text.slice(index))?.[0];
+  if (word) return { t: 'word', v: word.toLowerCase(), end: index + word.length };
+  const number = /^\d+(?:\.\d+)?/.exec(text.slice(index))?.[0];
+  if (number) return { t: 'number', v: number, end: index + number.length };
+  return { t: 'punct', v: char, end: index + 1 };
+}
+
+/** Synchronous SQL tokens; literal values stay internal and must never be copied to a finding. */
+export function databaseSqlTokens(text) {
+  const tokens = [];
+  let index = 0;
+  let line = 1;
+  while (index < text.length) {
+    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);
+    tokens.push({ t: token.t, v: token.v, line, index });
+    line += text.slice(index, token.end).split('\n').length - 1;
+    index = token.end;
+  }
+  return tokens;
+}
+
+/** Split executable SQL, retaining function bodies as opaque tokens until their language is known. */
+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 = []; }
+    else current.push(token);
+  }
+  if (current.length) statements.push(current);
+  return statements;
+}
+
+function executableStatementTokens(statement, depth) {
+  const isDo = sqlWord(statement[0], 'do');
+  const functionAt = statement.findIndex((token) => sqlWord(token, 'function') || sqlWord(token, 'procedure'));
+  const isFunction = sqlWord(statement[0], 'create') && functionAt > 0 && functionAt < 4;
+  if (!isDo && !isFunction) return statement;
+  const languageAt = statement.findIndex((token) => sqlWord(token, 'language'));
+  const language = statement[languageAt + 1]?.v ?? 'sql';
+  if (languageAt !== -1 && !['sql', 'plpgsql'].includes(language)) return statement;
+  return statement.flatMap((token, index) => {
+    const body = token.t === 'body' || (token.t === 'string' && (isDo || sqlWord(statement[index - 1], 'as')));
+    if (!body) return [token];
+    return databaseExecutableTokens(token.v, depth + 1).map((child) => ({ ...child, line: child.line + token.line - 1 }));
+  });
+}
+
+/** SQL and PL/pgSQL bodies are scanned; comments, data literals and other function languages are opaque. */
+export function databaseExecutableTokens(text, depth = 0) {
+  const tokens = databaseSqlTokens(text);
+  if (depth > 8) return tokens;
+  return databaseSqlStatements(tokens).flatMap((statement) => [...executableStatementTokens(statement, depth), { t: 'punct', v: ';' }]);
+}
+
+function nameAt(tokens, index) {
+  const first = sqlName(tokens[index]);
+  if (first === null) return null;
+  const parts = [first];
+  let next = index + 1;
+  while (tokens[next]?.v === '.' && sqlName(tokens[next + 1]) !== null) { parts.push(sqlName(tokens[next + 1])); next += 2; }
+  return { name: parts.join('.'), leaf: parts.at(-1), next };
+}
+
+const skipWords = (tokens, index, words) => {
+  let next = index;
+  while (words.some((word) => sqlWord(tokens[next], word))) next += 1;
+  return next;
+};
+
+function dropObjects(tokens, start) {
+  const kind = tokens[start + 1]?.v;
+  if (!['table', 'role', 'user', 'schema', 'type', 'view', 'materialized', 'sequence', 'function', 'procedure', 'index', 'policy', 'trigger'].includes(kind)) return [];
+  let index = skipWords(tokens, start + 2, ['view', 'if', 'exists', 'concurrently']);
+  const objects = [];
+  while (index < tokens.length) {
+    const object = nameAt(tokens, index);
+    if (!object) break;
+    objects.push({ ...object, kind, line: tokens[start].line });
+    if (tokens[object.next]?.v !== ',') break;
+    index = object.next + 1;
+  }
+  return objects;
+}
+
+function columnAlterObject(tokens, index, table, line) {
+  let next = index + 1;
+  if (sqlWord(tokens[next], 'column')) next += 1;
+  const column = nameAt(tokens, next);
+  if (!column) return null;
+  const tail = tokens.slice(column.next);
+  const type = sqlWord(tail[0], 'type') || (sqlWord(tail[0], 'set') && sqlWord(tail[1], 'data') && sqlWord(tail[2], 'type'));
+  const notNull = sqlWord(tail[0], 'set') && sqlWord(tail[1], 'not') && sqlWord(tail[2], 'null');
+  const defaultSet = tokens.some((token, at) => sqlWord(token, 'alter') && sqlName(tokens[at + 1 + Number(sqlWord(tokens[at + 1], 'column'))]) === column.leaf
+    && sqlWord(tokens[at + 2 + Number(sqlWord(tokens[at + 1], 'column'))], 'set') && sqlWord(tokens[at + 3 + Number(sqlWord(tokens[at + 1], 'column'))], 'default'));
+  if (!type && !(notNull && !defaultSet)) return null;
+  return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
+}
+
+function alteredColumn(table, column, line) {
+  return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
+}
+
+function tableActionObject(body, index, table, line) {
+  if (sqlWord(body[index], 'drop')) {
+    const at = skipWords(body, index + 1, ['column', 'constraint', 'if', 'exists']);
+    if (sqlWord(body[at], 'default') || sqlWord(body[at], 'not')) return null;
+    const column = nameAt(body, at);
+    return column ? alteredColumn(table, column, line) : null;
+  }
+  if (sqlWord(body[index], 'rename')) {
+    const column = sqlWord(body[index + 1], 'column') ? nameAt(body, index + 2) : null;
+    return column ? alteredColumn(table, column, line) : { ...table, kind: 'table', line };
+  }
+  return sqlWord(body[index], 'alter') ? columnAlterObject(body, index, table, line) : null;
+}
+
+function alterObjects(tokens, start) {
+  const table = nameAt(tokens, skipWords(tokens, start + 2, ['if', 'exists', 'only']));
+  if (!table) return [];
+  const body = tokens.slice(table.next);
+  return body.map((token, index) => tableActionObject(body, index, table, tokens[start].line)).filter(Boolean);
+}
+
+function truncatedObjects(tokens, start) {
+  const objects = [];
+  let index = skipWords(tokens, start + 1, ['table', 'only']);
+  while (index < tokens.length) {
+    const table = nameAt(tokens, index);
+    if (!table) break;
+    objects.push({ ...table, kind: 'table', line: tokens[start].line });
+    if (tokens[table.next]?.v !== ',') break;
+    index = skipWords(tokens, table.next + 1, ['only']);
+  }
+  return objects;
+}
+
+function destructiveObjects(statement) {
+  const objects = [];
+  for (let index = 0; index < statement.length; index += 1) {
+    if (sqlWord(statement[index], 'drop')) objects.push(...dropObjects(statement, index));
+    else if (sqlWord(statement[index], 'truncate')) objects.push(...truncatedObjects(statement, index));
+    else if (sqlWord(statement[index], 'alter') && sqlWord(statement[index + 1], 'table')) objects.push(...alterObjects(statement, index));
+    else if (sqlWord(statement[index], 'alter') && ['type', 'schema', 'view', 'sequence', 'function', 'procedure', 'index'].includes(statement[index + 1]?.v)) {
+      const object = nameAt(statement, index + 2);
+      if (object && statement.slice(object.next).some((token) => sqlWord(token, 'rename'))) objects.push({ ...object, kind: statement[index + 1].v, line: statement[index].line });
+    }
+  }
+  return objects;
+}
+
+function sourceNames(ts, text, file) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const names = new Set();
+  const addSql = (sql) => { for (const token of databaseSqlTokens(sql)) if (sqlName(token) !== null) names.add(token.v); };
+  const visit = (node) => {
+    if (ts.isStringLiteralLike(node)) addSql(node.text);
+    if (ts.isTemplateExpression(node)) { addSql(node.head.text); for (const span of node.templateSpans) addSql(span.literal.text); }
+    if (/\.entity\.[cm]?tsx?$/.test(file) && ts.isIdentifier(node)) names.add(node.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return names;
+}
+
+function destructiveObjectFinding(file, object, contract, references) {
+  const reference = references.find(({ names }) => names.has(object.leaf));
+  if (contract && !reference) return null;
+  const reason = reference && contract ? `${reference.file} still references this object; remove the reference before the contract migration`
+    : 'use a *_contract_* migration after the application stops using this object';
+  return found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destructively changes ${object.name}; ${reason}`,
+    { line: object.line, object: object.name, ...(reference ? { reference: reference.file } : {}) });
+}
+
+function destructiveFileFindings(file, text, references) {
+  const contract = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file);
+  const seen = new Set();
+  const objects = databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects);
+  return objects.flatMap((object) => {
+    const key = `${object.line}:${object.name}`;
+    if (seen.has(key)) return [];
+    seen.add(key);
+    const finding = destructiveObjectFinding(file, object, contract, references);
+    return finding ? [finding] : [];
+  });
+}
+
+/** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
+export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
+  const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));
+  const ts = sources.length ? loadTypescript(repoRoot, HERE) : null;
+  if (sources.length && !ts) return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'destructive migration checks require the TypeScript parser to read be/src references')];
+  const references = sources.map((file) => ({ file, names: sourceNames(ts, readText(repoRoot, file) ?? '', file) }));
+  return migrations.flatMap((file) => {
+    const text = readText(repoRoot, file);
+    return text === null ? [] : destructiveFileFindings(file, text, references);
+  });
+}