@starci/hfs 1.0.1 → 2.0.0

package/runtime/scripts/checks/architecture/sql-owner.mjs

@@ -0,0 +1,142 @@
+import path from 'node:path';
+import { analyzeSql, HOLE } from './sql-tokens.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R86 `sql-owner` (BE_SQL_TABLE_OWNER). Every `sql` tagged template (the tag declared in platform/database) of a
+ * `<name>.sql.ts` file in a capability's `persistence/` is read with the tokenizer of sql-tokens.mjs and judged against the
+ * entities of the whole program:
+ *   - it writes (INSERT INTO, UPDATE, DELETE FROM, MERGE INTO, TRUNCATE) only tables the file's own capability declares
+ *     with `@Entity("<table>")` in its persistence;
+ *   - it reads (FROM, JOIN, USING) only tables of capabilities its owner may import (the tier matrix, through
+ *     `resolver.importAllowed` to the table owner's public entry) or its own;
+ *   - every table it names is declared by some entity;
+ *   - a SELECT carries LIMIT, or constrains the primary key or a unique key of its first table with `=`, or selects only
+ *     aggregates without GROUP BY.
+ * Table positions that hold a `${...}` substitution (SqlIdent) are dynamic; they are counted in the coverage and judged by
+ * nobody. Joined tables are not part of the bound: a to-many join under a key-constrained first table is a review point.
+ */
+export const SQL_OWNER_RULE_IDS = ['BE_SQL_TABLE_OWNER'];
+
+const RULE = 'BE_SQL_TABLE_OWNER';
+const TYPEORM = 'typeorm';
+
+const literalStrings = (ts, node) => {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node)) return [node.text];
+  if (ts.isArrayLiteralExpression(node) && node.elements.every(item => ts.isStringLiteralLike(item))) return node.elements.map(item => item.text);
+  return null;
+};
+
+function entitiesOf(kit, graph) {
+  const { ts } = kit;
+  const tables = new Map();
+  let unreadable = 0;
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !path.posix.basename(file.rel).endsWith('.entity.ts') || !file.owner) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    const typeorm = (node, ...names) => {
+      const call = ts.isCallExpression(node.expression) ? node.expression.expression : node.expression;
+      const binding = kit.importBinding(checker, call);
+      return binding?.module === TYPEORM && names.includes(binding.name);
+    };
+    for (const statement of file.sourceFile.statements) {
+      if (!ts.isClassDeclaration(statement)) continue;
+      const entity = kit.decorators(statement).find(decorator => typeorm(decorator, 'Entity'));
+      if (!entity) continue;
+      const argument = ts.isCallExpression(entity.expression) ? entity.expression.arguments[0] : null;
+      let table = argument && ts.isStringLiteralLike(argument) ? argument.text : null;
+      if (table === null && argument && ts.isObjectLiteralExpression(argument)) {
+        const property = kit.propertyOf(argument, 'name');
+        if (property && ts.isStringLiteralLike(kit.valueOfProperty(property))) table = kit.valueOfProperty(property).text;
+      }
+      if (table === null) { unreadable += 1; continue; }
+      const dbName = new Map();
+      const primary = [];
+      const sets = [];
+      for (const member of statement.members) {
+        if (!ts.isPropertyDeclaration(member) || !member.name || !ts.isIdentifier(member.name)) continue;
+        const property = member.name.text;
+        let column = property;
+        for (const decorator of kit.decorators(member)) {
+          const args = ts.isCallExpression(decorator.expression) ? decorator.expression.arguments : [];
+          for (const item of args) if (ts.isObjectLiteralExpression(item)) {
+            const named = kit.propertyOf(item, 'name');
+            if (named && ts.isStringLiteralLike(kit.valueOfProperty(named))) column = kit.valueOfProperty(named).text;
+          }
+        }
+        dbName.set(property, column.toLowerCase());
+        for (const decorator of kit.decorators(member)) {
+          const args = ts.isCallExpression(decorator.expression) ? decorator.expression.arguments : [];
+          const uniqueOption = args.some(item => ts.isObjectLiteralExpression(item) && kit.propertyOf(item, 'unique')
+            && kit.valueOfProperty(kit.propertyOf(item, 'unique')).kind === ts.SyntaxKind.TrueKeyword);
+          if (typeorm(decorator, 'PrimaryColumn', 'PrimaryGeneratedColumn')) primary.push(column.toLowerCase());
+          else if (typeorm(decorator, 'Column', 'Index') && uniqueOption) sets.push([column.toLowerCase()]);
+        }
+      }
+      if (primary.length) sets.push(primary);
+      for (const decorator of kit.decorators(statement)) {
+        const args = ts.isCallExpression(decorator.expression) ? decorator.expression.arguments : [];
+        const list = args.find(item => ts.isArrayLiteralExpression(item) && literalStrings(ts, item));
+        const columns = list ? literalStrings(ts, list) : null;
+        const unique = typeorm(decorator, 'Unique') || (typeorm(decorator, 'Index') && args.some(item => ts.isObjectLiteralExpression(item) && kit.propertyOf(item, 'unique')
+          && kit.valueOfProperty(kit.propertyOf(item, 'unique')).kind === ts.SyntaxKind.TrueKeyword));
+        if (unique && columns) sets.push(columns.map(column => (dbName.get(column) ?? column).toLowerCase()));
+      }
+      const key = table.toLowerCase();
+      if (!tables.has(key)) tables.set(key, { table, owner: file.owner.root, rel: file.rel, uniqueSets: sets });
+    }
+  }
+  return { tables, unreadable };
+}
+
+export function checkSqlOwner(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts, resolver } = kit;
+  const { tables, unreadable } = entitiesOf(kit, graph);
+  const violations = [];
+  let templates = 0;
+  let dynamic = 0;
+  let foreignTags = 0;
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !path.posix.basename(file.rel).endsWith('.sql.ts') || !file.owner) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isTaggedTemplateExpression(node)) return true;
+      const home = kit.declarationsOf(checker, node.tag).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!home || home.tier !== 'platform' || home.name !== 'database') { foreignTags += 1; return true; }
+      templates += 1;
+      const template = node.template;
+      const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text
+        : template.head.text + template.templateSpans.map(span => HOLE + span.literal.text).join('');
+      const seen = new Set();
+      const report = (message, extra = {}) => {
+        const key = `${message}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+      };
+      const result = analyzeSql(text, { uniqueSetsOf: table => tables.get(table.toLowerCase())?.uniqueSets ?? null });
+      dynamic += result.dynamic;
+      for (const write of result.writes) {
+        const entity = tables.get(write.table.toLowerCase());
+        if (!entity) report(`SQL writes table ${write.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: write.table });
+        else if (entity.owner !== file.owner.root) report(`SQL in ${file.owner.root} writes table ${write.table}, owned by ${entity.owner}; a capability writes only the tables of its own entities, call the owner's public API instead.`, { table: write.table, tableOwner: entity.owner });
+      }
+      for (const read of result.reads) {
+        const entity = tables.get(read.table.toLowerCase());
+        if (!entity) { report(`SQL reads table ${read.table}, which no @Entity declares; declare the entity in the owning capability's persistence/entities.`, { table: read.table }); continue; }
+        if (entity.owner === file.owner.root) continue;
+        const verdict = resolver.importAllowed(file.rel, `${entity.owner}/index.ts`);
+        if (!verdict.allowed) report(`SQL in ${file.owner.root} reads table ${read.table}, owned by ${entity.owner}, which ${file.owner.root} may not import (${verdict.reason}); read it through the owner's public API.`, { table: read.table, tableOwner: entity.owner, reason: verdict.reason });
+      }
+      for (const select of result.selects) {
+        if (select.bounded || (select.table && !tables.has(select.table.toLowerCase()))) continue;
+        report(`SELECT ${select.table ? `on ${select.table} ` : ''}has no LIMIT and does not constrain a primary key or unique column with =; bound it with LIMIT (PAGE_SIZE_MAX, LIST_ROWS_MAX or BATCH_ROWS from platform/database), filter by key, or select only aggregates.`, { table: select.table ?? undefined });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', entities: tables.size, unreadableEntities: unreadable, templates, dynamicIdentifiers: dynamic, foreignTags } };
+}

package/runtime/scripts/checks/architecture/sql-tokens.mjs

@@ -0,0 +1,327 @@
+/**
+ * A small PostgreSQL text reader for the R86 machine check (sql-owner). No SQL parser is a dependency of the runtime, so
+ * this is a tokenizer plus a clause scanner, written for exactly what the check needs: which tables a statement
+ * writes, which it reads, and whether a SELECT is bounded. Comments and string literals never reach the scanner.
+ * A substitution of the `sql` tag (a `${...}` hole, the SqlIdent form) is an opaque token: a table position that holds
+ * one is counted as dynamic and judged by nobody.
+ */
+export const HOLE = '';
+
+const isSpace = char => /\s/u.test(char);
+const isWordStart = char => /[\p{L}_]/u.test(char);
+const isWordPart = char => /[\p{L}\p{N}_$]/u.test(char);
+
+/** Tokens: {t: 'word'|'ident'|'string'|'number'|'param'|'hole'|'punct', v, up?} (`up` is the uppercase word). */
+export function tokenizeSql(text) {
+  const tokens = [];
+  let i = 0;
+  const push = (t, v) => tokens.push(t === 'word' ? { t, v, up: v.toUpperCase() } : { t, v });
+  while (i < text.length) {
+    const char = text[i];
+    if (isSpace(char)) { i += 1; continue; }
+    if (char === '-' && text[i + 1] === '-') { while (i < text.length && text[i] !== '\n') i += 1; continue; }
+    if (char === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+      continue;
+    }
+    if (char === HOLE) { push('hole', HOLE); i += 1; continue; }
+    if (char === "'") {
+      i += 1;
+      while (i < text.length) {
+        if (text[i] === "'" && text[i + 1] === "'") { i += 2; continue; }
+        if (text[i] === "'") break;
+        i += 1;
+      }
+      i += 1;
+      push('string', '');
+      continue;
+    }
+    if (char === '"') {
+      let value = '';
+      i += 1;
+      while (i < text.length) {
+        if (text[i] === '"' && text[i + 1] === '"') { value += '"'; i += 2; continue; }
+        if (text[i] === '"') break;
+        value += text[i];
+        i += 1;
+      }
+      i += 1;
+      push('ident', value);
+      continue;
+    }
+    if (char === '$') {
+      const param = /^\$(\d+)/u.exec(text.slice(i, i + 12));
+      if (param) { push('param', param[0]); i += param[0].length; continue; }
+      const tag = /^\$([\p{L}_][\p{L}\p{N}_]*)?\$/u.exec(text.slice(i));
+      if (tag) {
+        const end = text.indexOf(tag[0], i + tag[0].length);
+        i = end === -1 ? text.length : end + tag[0].length;
+        push('string', '');
+        continue;
+      }
+    }
+    if (/\d/u.test(char)) {
+      let j = i;
+      while (j < text.length && /[\d.]/u.test(text[j])) j += 1;
+      push('number', text.slice(i, j));
+      i = j;
+      continue;
+    }
+    if (isWordStart(char)) {
+      let j = i;
+      while (j < text.length && isWordPart(text[j])) j += 1;
+      const word = text.slice(i, j);
+      if (text[j] === "'" && /^[EeBbXxNn]$/u.test(word)) {
+        const escaped = /^[Ee]$/u.test(word);
+        j += 1;
+        while (j < text.length) {
+          if (escaped && text[j] === '\\') { j += 2; continue; }
+          if (text[j] === "'" && text[j + 1] === "'") { j += 2; continue; }
+          if (text[j] === "'") break;
+          j += 1;
+        }
+        i = j + 1;
+        push('string', '');
+        continue;
+      }
+      push('word', word);
+      i = j;
+      continue;
+    }
+    const two = text.slice(i, i + 2);
+    if (['::', '<=', '>=', '<>', '!=', '||', '->'].includes(two)) { push('punct', two); i += 2; continue; }
+    push('punct', char);
+    i += 1;
+  }
+  return tokens;
+}
+
+const CLAUSE_WORDS = new Set(['WHERE', 'JOIN', 'INNER', 'LEFT', 'RIGHT', 'FULL', 'CROSS', 'NATURAL', 'ON', 'USING', 'GROUP', 'ORDER', 'LIMIT', 'OFFSET',
+  'HAVING', 'UNION', 'INTERSECT', 'EXCEPT', 'WINDOW', 'FOR', 'RETURNING', 'SET', 'VALUES', 'SELECT', 'FETCH', 'OUTER', 'TABLESAMPLE', 'WITH', 'AS']);
+// PostgreSQL aggregate function names, kept as one string so they read as words, not as failure codes.
+const AGGREGATES = new Set('COUNT SUM AVG MIN MAX BOOL_AND BOOL_OR EVERY ARRAY_AGG STRING_AGG JSON_AGG JSONB_AGG JSON_OBJECT_AGG JSONB_OBJECT_AGG BIT_AND BIT_OR STDDEV VARIANCE'.split(' '));
+const FROM_INSIDE = new Set(['EXTRACT', 'SUBSTRING', 'TRIM', 'OVERLAY', 'POSITION']);
+const NOT_A_WRITE_BEFORE_UPDATE = new Set(['FOR', 'DO', 'ON', 'KEY', 'SHARE', 'OF']);
+const WHERE_END = new Set(['GROUP', 'ORDER', 'HAVING', 'LIMIT', 'OFFSET', 'UNION', 'INTERSECT', 'EXCEPT', 'FOR', 'WINDOW', 'RETURNING', 'FETCH']);
+const SYSTEM_SCHEMAS = new Set(['pg_catalog', 'information_schema']);
+
+const isName = token => token && (token.t === 'word' || token.t === 'ident');
+const nameOf = token => (token.t === 'word' ? token.v.toLowerCase() : token.v);
+const isWord = (token, up) => token?.t === 'word' && token.up === up;
+
+/**
+ * The table reference at `start`: {parts, table, alias, next}, {dynamic: true}, or null (a subquery, a function, nothing).
+ * `next` is the index after the reference and its alias.
+ */
+function tableRef(tokens, start, { columns = false } = {}) {
+  let i = start;
+  while (isWord(tokens[i], 'ONLY') || isWord(tokens[i], 'LATERAL')) i += 1;
+  const first = tokens[i];
+  if (first?.t === 'hole') return { dynamic: true, next: i + 1 };
+  if (!isName(first) || (first.t === 'word' && CLAUSE_WORDS.has(first.up) && first.up !== 'AS')) return null;
+  const parts = [nameOf(first)];
+  i += 1;
+  while (tokens[i]?.v === '.' && isName(tokens[i + 1])) { parts.push(nameOf(tokens[i + 1])); i += 2; }
+  if (tokens[i]?.v === '(' && !columns) return null;
+  let alias = null;
+  if (isWord(tokens[i], 'AS') && isName(tokens[i + 1])) { alias = nameOf(tokens[i + 1]); i += 2; }
+  else if (isName(tokens[i]) && !(tokens[i].t === 'word' && CLAUSE_WORDS.has(tokens[i].up))) { alias = nameOf(tokens[i]); i += 1; }
+  if (alias && tokens[i]?.v === '(') { let depth = 0; do { if (tokens[i].v === '(') depth += 1; else if (tokens[i].v === ')') depth -= 1; i += 1; } while (i < tokens.length && depth > 0); }
+  return { parts, table: parts.at(-1), schema: parts.length > 1 ? parts.at(-2) : null, alias, next: i };
+}
+
+function statementsOf(tokens) {
+  const statements = [];
+  let current = [];
+  let depth = 0;
+  for (const token of tokens) {
+    if (token.t === 'punct' && token.v === '(') depth += 1;
+    if (token.t === 'punct' && token.v === ')') depth -= 1;
+    if (token.t === 'punct' && token.v === ';' && depth <= 0) { if (current.length) statements.push(current); current = []; continue; }
+    current.push(token);
+  }
+  if (current.length) statements.push(current);
+  return statements;
+}
+
+/** The CTE names a statement declares: `name [(cols)] AS [NOT] [MATERIALIZED] (`. */
+function cteNames(tokens) {
+  const names = new Set();
+  for (let i = 1; i < tokens.length; i += 1) {
+    if (!isWord(tokens[i], 'AS')) continue;
+    let j = i + 1;
+    if (isWord(tokens[j], 'NOT')) j += 1;
+    if (isWord(tokens[j], 'MATERIALIZED')) j += 1;
+    if (tokens[j]?.v !== '(') continue;
+    let k = i - 1;
+    if (tokens[k]?.v === ')') { let depth = 0; do { if (tokens[k].v === ')') depth += 1; else if (tokens[k].v === '(') depth -= 1; k -= 1; } while (k >= 0 && depth > 0); }
+    const before = tokens[k - 1];
+    if (isName(tokens[k]) && (isWord(before, 'WITH') || isWord(before, 'RECURSIVE') || before?.v === ',')) names.add(nameOf(tokens[k]));
+  }
+  return names;
+}
+
+/** Depth of each token (the depth before it when it is `(`, after it when it is `)`). */
+function depths(tokens) {
+  let depth = 0;
+  return tokens.map(token => {
+    if (token.v === ')' && token.t === 'punct') depth -= 1;
+    const here = depth;
+    if (token.v === '(' && token.t === 'punct') depth += 1;
+    return here;
+  });
+}
+
+function matching(tokens, open) {
+  let depth = 0;
+  for (let i = open; i < tokens.length; i += 1) {
+    if (tokens[i].t !== 'punct') continue;
+    if (tokens[i].v === '(') depth += 1;
+    else if (tokens[i].v === ')') { depth -= 1; if (depth === 0) return i; }
+  }
+  return tokens.length - 1;
+}
+
+function isAggregateItem(item) {
+  for (let i = 0; i < item.length; i += 1) {
+    if (item[i].t === 'word' && AGGREGATES.has(item[i].up) && item[i + 1]?.v === '(') {
+      const close = matching(item, i + 1);
+      if (!isWord(item[close + 1], 'OVER')) return true;
+    }
+  }
+  return false;
+}
+
+/** The unique-key columns `columns` (lowercase Set of `=`-constrained column names) satisfy for one of `uniqueSets`. */
+const covers = (uniqueSets, columns) => uniqueSets.some(set => set.length > 0 && set.every(column => columns.has(column)));
+
+function equalityColumns(conjunct, qualifiers) {
+  const found = new Set();
+  const name = (from, to) => {
+    const part = conjunct.slice(from, to);
+    if (part.length === 1 && isName(part[0])) return nameOf(part[0]);
+    if (part.length === 3 && isName(part[0]) && part[1].v === '.' && isName(part[2]) && qualifiers.has(nameOf(part[0]))) return nameOf(part[2]);
+    return null;
+  };
+  const equals = conjunct.findIndex(token => token.t === 'punct' && token.v === '=');
+  if (equals < 0) return found;
+  const left = name(0, equals);
+  const rightStart = conjunct[equals + 1];
+  if (left && !(rightStart?.t === 'word' && ['ANY', 'ALL', 'SOME'].includes(rightStart.up))) found.add(left);
+  const right = name(equals + 1, conjunct.length);
+  if (right) found.add(right);
+  return found;
+}
+
+/**
+ * Judge one statement that reads rows (no INSERT/UPDATE/DELETE/MERGE at its own depth): `{bounded, basis}`. Bounded is
+ * a LIMIT/FETCH at the statement depth, no FROM at all (one row), only aggregates without GROUP BY, or an equality on
+ * every column of the primary key or of one unique key of the first table of FROM.
+ */
+function selectBound(tokens, level, uniqueSetsOf, cte) {
+  const at0 = index => level[index] === 0;
+  const find = (up, from = 0) => { for (let i = from; i < tokens.length; i += 1) if (at0(i) && isWord(tokens[i], up)) return i; return -1; };
+  if (find('LIMIT') >= 0 || find('FETCH') >= 0) return { bounded: true, basis: 'limit' };
+  const select = find('SELECT');
+  const from = find('FROM', select);
+  if (from < 0) return { bounded: true, basis: 'no from' };
+  const groupBy = tokens.findIndex((token, i) => at0(i) && isWord(token, 'GROUP') && isWord(tokens[i + 1], 'BY'));
+  if (groupBy < 0) {
+    const items = [];
+    let item = [];
+    for (let i = select + 1; i < from; i += 1) {
+      if (at0(i) && tokens[i].v === ',' && tokens[i].t === 'punct') { items.push(item); item = []; continue; }
+      if (!(items.length === 0 && item.length === 0 && (isWord(tokens[i], 'DISTINCT') || isWord(tokens[i], 'ALL')))) item.push(tokens[i]);
+    }
+    items.push(item);
+    if (items.length && items.every(isAggregateItem)) return { bounded: true, basis: 'aggregate' };
+  }
+  const primary = tableRef(tokens, from + 1);
+  if (!primary || primary.dynamic || cte.has(primary.table)) return { bounded: false, basis: 'unbounded', table: primary?.table ?? null };
+  const uniqueSets = uniqueSetsOf(primary.table);
+  const where = find('WHERE', from);
+  if (uniqueSets?.length && where >= 0) {
+    const region = [];
+    for (let i = where + 1; i < tokens.length; i += 1) {
+      if (at0(i) && tokens[i].t === 'word' && WHERE_END.has(tokens[i].up)) break;
+      region.push({ token: tokens[i], level: level[i] });
+    }
+    if (!region.some(entry => entry.level === 0 && isWord(entry.token, 'OR'))) {
+      const conjuncts = [[]];
+      let between = false;
+      for (const entry of region) {
+        if (entry.level === 0 && isWord(entry.token, 'BETWEEN')) between = true;
+        if (entry.level === 0 && isWord(entry.token, 'AND')) {
+          if (between) { between = false; } else { conjuncts.push([]); continue; }
+        }
+        conjuncts.at(-1).push(entry.token);
+      }
+      const qualifiers = new Set([primary.table, primary.alias].filter(Boolean));
+      const columns = new Set();
+      for (const conjunct of conjuncts) for (const column of equalityColumns(conjunct, qualifiers)) columns.add(column);
+      if (covers(uniqueSets, columns)) return { bounded: true, basis: 'unique' };
+    }
+  }
+  return { bounded: false, basis: 'unbounded', table: primary.table };
+}
+
+/**
+ * Read one SQL text. `uniqueSetsOf(table)` returns the unique-key column sets (each a lowercase column list) of the entity
+ * of `table`, or null when no entity declares it.
+ * Returns {writes: [{table, schema}], reads: [{table, schema}], selects: [{bounded, basis, table}], dynamic}.
+ */
+export function analyzeSql(text, { uniqueSetsOf = () => null } = {}) {
+  const writes = [];
+  const reads = [];
+  const selects = [];
+  let dynamic = 0;
+  for (const tokens of statementsOf(tokenizeSql(text))) {
+    const cte = cteNames(tokens);
+    const level = depths(tokens);
+    const parens = [];
+    const record = (list, ref) => {
+      if (!ref) return;
+      if (ref.dynamic) { dynamic += 1; return; }
+      if (ref.schema && SYSTEM_SCHEMAS.has(ref.schema)) return;
+      if (ref.table.startsWith('pg_')) return;
+      if (list === reads && !ref.schema && cte.has(ref.table)) return;
+      list.push({ table: ref.table, schema: ref.schema });
+    };
+    const mergeOrDelete = tokens.some(token => isWord(token, 'MERGE')) || tokens.some(token => isWord(token, 'DELETE'));
+    let hasWriteVerb = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+      const token = tokens[i];
+      if (token.t === 'punct' && token.v === '(') { parens.push(i > 0 && tokens[i - 1].t === 'word' && FROM_INSIDE.has(tokens[i - 1].up)); continue; }
+      if (token.t === 'punct' && token.v === ')') { parens.pop(); continue; }
+      if (token.t !== 'word') continue;
+      const previous = tokens[i - 1];
+      if (token.up === 'INSERT' && isWord(tokens[i + 1], 'INTO')) { if (level[i] === 0) hasWriteVerb = true; record(writes, tableRef(tokens, i + 2, { columns: true })); }
+      else if (token.up === 'UPDATE' && !(previous?.t === 'word' && NOT_A_WRITE_BEFORE_UPDATE.has(previous.up))) { if (level[i] === 0) hasWriteVerb = true; record(writes, tableRef(tokens, i + 1)); }
+      else if (token.up === 'DELETE' && isWord(tokens[i + 1], 'FROM')) { if (level[i] === 0) hasWriteVerb = true; record(writes, tableRef(tokens, i + 2)); i += 1; }
+      else if (token.up === 'MERGE' && isWord(tokens[i + 1], 'INTO')) { if (level[i] === 0) hasWriteVerb = true; record(writes, tableRef(tokens, i + 2)); }
+      else if (token.up === 'TRUNCATE') {
+        let j = i + 1;
+        if (isWord(tokens[j], 'TABLE')) j += 1;
+        for (;;) {
+          const ref = tableRef(tokens, j);
+          record(writes, ref);
+          if (ref && tokens[ref.next]?.v === ',') { j = ref.next + 1; continue; }
+          break;
+        }
+      } else if (token.up === 'FROM' && !isWord(previous, 'DISTINCT') && !isWord(previous, 'DELETE') && parens.at(-1) !== true) {
+        let j = i + 1;
+        for (;;) {
+          const ref = tableRef(tokens, j);
+          record(reads, ref);
+          if (ref && tokens[ref.next]?.v === ',' && tokens[ref.next].t === 'punct') { j = ref.next + 1; continue; }
+          break;
+        }
+      } else if (token.up === 'JOIN') record(reads, tableRef(tokens, i + 1));
+      else if (token.up === 'USING' && mergeOrDelete && tokens[i + 1]?.v !== '(') record(reads, tableRef(tokens, i + 1));
+    }
+    const hasSelect = tokens.some((candidate, i) => level[i] === 0 && isWord(candidate, 'SELECT'));
+    if (hasSelect && !hasWriteVerb) selects.push(selectBound(tokens, level, uniqueSetsOf, cte));
+  }
+  return { writes, reads, selects, dynamic };
+}

package/runtime/scripts/checks/architecture/symbols.mjs

@@ -0,0 +1,193 @@
+/**
+ * HFS check 5, one name one declaration (knowledge/hfs/rules.yaml R21 and R30, both profiles, errors in every gate):
+ *   HFS_DUPLICATE_SYMBOL  a name an owner's public entry exports, resolved to the file that declares it, that another
+ *                         production file of the repository also declares and exports (function, class, const, enum,
+ *                         type, interface). Two `InjectPrimaryEntityManager` declarations were this. A re-export of one
+ *                         declaration is not a second declaration. There is no allowlist of names.
+ *   HFS_ALIAS_REEXPORT    `export { X as Y }`, `export { default as Y }` and `export * as ns` in production source, and an
+ *                         exported `const Y = X` / `const Y = X.y` (a bare identifier or member that resolves to a function,
+ *                         class, const or enum of the repository), `type Y = X` and `interface Y extends X {}` (no body, no
+ *                         type arguments, no type parameters): a second name for one declaration. Rename the declaration,
+ *                         or import it by its name.
+ * Specs and tests are not in the graph. The public entry of an owner is found the way dead-exports.mjs finds it.
+ */
+import { canonical } from './config.mjs';
+import { entryOf } from './dead-exports.mjs';
+
+export const SYMBOL_RULE_IDS = ['HFS_DUPLICATE_SYMBOL', 'HFS_ALIAS_REEXPORT'];
+
+const lineOf = (sourceFile, node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+
+/** The names a source file declares at top level and exports: Map<name, line>. Re-exports from another module declare nothing. */
+function declaredExports(ts, sourceFile) {
+  const kind = ts.SyntaxKind;
+  const declared = new Map();
+  const exported = new Map();
+  const localLists = [];
+  const bindingNames = (name, into, node) => {
+    if (name.kind === kind.Identifier) into.set(name.text, lineOf(sourceFile, node));
+    else for (const element of name.elements) if (element.kind === kind.BindingElement) bindingNames(element.name, into, node);
+  };
+  for (const statement of sourceFile.statements) {
+    if (statement.kind === kind.ExportDeclaration) {
+      if (!statement.moduleSpecifier && statement.exportClause?.kind === kind.NamedExports) localLists.push(...statement.exportClause.elements);
+      continue;
+    }
+    const modifiers = statement.modifiers ?? [];
+    const publish = modifiers.some(modifier => modifier.kind === kind.ExportKeyword) && !modifiers.some(modifier => modifier.kind === kind.DefaultKeyword);
+    const into = publish ? exported : declared;
+    if (statement.kind === kind.VariableStatement) {
+      for (const declaration of statement.declarationList.declarations) bindingNames(declaration.name, into, declaration);
+    } else if (statement.name?.kind === kind.Identifier
+      && [kind.FunctionDeclaration, kind.ClassDeclaration, kind.EnumDeclaration, kind.TypeAliasDeclaration, kind.InterfaceDeclaration].includes(statement.kind)) {
+      into.set(statement.name.text, lineOf(sourceFile, statement));
+    }
+  }
+  // `export { local }` of a name declared in this file makes that declaration exported.
+  for (const element of localLists) {
+    const local = (element.propertyName ?? element.name).text;
+    if (declared.has(local)) exported.set(element.name.text, declared.get(local));
+  }
+  return exported;
+}
+
+/** The declaration an export of an entry resolves to: its repository-relative file and its own name, or null. */
+function declaringFile(ts, checker, graph, symbol) {
+  const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  for (const declaration of resolved?.declarations ?? []) {
+    const rel = graph.abs(canonical(declaration.getSourceFile().fileName));
+    if (rel) return { rel, name: resolved.getName() };
+  }
+  return null;
+}
+
+function duplicateSymbols({ context, graph, config }) {
+  const { ts } = context;
+  const declarations = new Map(); // name -> Map<rel, line>
+  for (const [rel, node] of graph.files) {
+    for (const [name, line] of declaredExports(ts, node.sourceFile)) {
+      if (name === 'default') continue;
+      if (!declarations.has(name)) declarations.set(name, new Map());
+      declarations.get(name).set(rel, line);
+    }
+  }
+  const violations = [];
+  const seen = new Set();
+  let surface = 0;
+  for (const [key, owner] of graph.ownerRoots) {
+    if (owner.tier === 'app') continue;
+    const entry = entryOf(graph, config, key, owner);
+    if (!entry) continue;
+    const entryFile = graph.files.get(entry);
+    const checker = context.checkerFor(entryFile.abs);
+    const moduleSymbol = checker?.getSymbolAtLocation(entryFile.sourceFile);
+    if (!moduleSymbol) continue;
+    for (const symbol of checker.getExportsOfModule(moduleSymbol)) {
+      surface += 1;
+      const declaration = declaringFile(ts, checker, graph, symbol);
+      if (!declaration || declaration.name === 'default') continue;
+      const { rel: home, name } = declaration;
+      const others = [...(declarations.get(name) ?? [])].filter(([rel]) => rel !== home);
+      if (!others.length || seen.has(`${home}\0${name}`)) continue;
+      seen.add(`${home}\0${name}`);
+      const where = others.map(([rel, at]) => `${rel}:${at}`);
+      violations.push({
+        ruleId: 'HFS_DUPLICATE_SYMBOL',
+        path: home, line: declarations.get(name).get(home) ?? 1, column: 1, name, owner: owner.root, entry,
+        otherDeclarations: where,
+        message: `${name} is exported through the public entry ${entry} (declared in ${home}) and also declared and exported in ${where.join(', ')}; one name, one declaration: rename or delete the copy.`,
+      });
+    }
+  }
+  return { violations, surface };
+}
+
+const isExported = (ts, statement) => (statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)
+  && !(statement.modifiers ?? []).some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+
+/** The declaration `node` (an identifier, a member or a qualified name) resolves to when a repository file declares it as one of `kinds`, else null. */
+function repositoryDeclaration(ts, checker, graph, node, kinds) {
+  const target = ts.isPropertyAccessExpression(node) ? node.name : ts.isQualifiedName(node) ? node.right : node;
+  const symbol = checker?.getSymbolAtLocation(target);
+  if (!symbol) return null;
+  const resolved = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  const home = (resolved?.declarations ?? []).find(declaration => kinds.includes(declaration.kind) && graph.abs(canonical(declaration.getSourceFile().fileName)));
+  return home ? resolved.getName() : null;
+}
+
+/**
+ * The exported declarations of one top-level statement that only rename another declaration of the repository:
+ * `export const Y = X` and `export const Y = X.y` (X or y a function, class, const or enum), `export type Y = X` and
+ * `export interface Y extends X {}` with no body, no type arguments and no type parameters.
+ */
+function declarationAliases(ts, checker, graph, statement) {
+  const kind = ts.SyntaxKind;
+  if (!checker || !isExported(ts, statement)) return [];
+  const bare = expression => ts.isIdentifier(expression) || (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.name) && (ts.isIdentifier(expression.expression) || ts.isPropertyAccessExpression(expression.expression)));
+  const found = [];
+  if (statement.kind === kind.VariableStatement) {
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer || !bare(declaration.initializer)) continue;
+      const of = repositoryDeclaration(ts, checker, graph, declaration.initializer, [kind.FunctionDeclaration, kind.ClassDeclaration, kind.VariableDeclaration, kind.EnumDeclaration]);
+      if (of && of !== declaration.name.text) found.push({ node: declaration, name: declaration.name.text, of, form: `export const ${declaration.name.text} = ${declaration.initializer.getText()}` });
+    }
+  } else if (statement.kind === kind.TypeAliasDeclaration && !statement.typeParameters?.length && ts.isTypeReferenceNode(statement.type) && !statement.type.typeArguments?.length) {
+    const of = repositoryDeclaration(ts, checker, graph, statement.type.typeName, [kind.InterfaceDeclaration, kind.TypeAliasDeclaration, kind.ClassDeclaration, kind.EnumDeclaration]);
+    if (of && of !== statement.name.text) found.push({ node: statement, name: statement.name.text, of, form: `export type ${statement.name.text} = ${statement.type.getText()}` });
+  } else if (statement.kind === kind.InterfaceDeclaration && !statement.members.length && !statement.typeParameters?.length) {
+    const heritage = (statement.heritageClauses ?? []).flatMap(clause => clause.types);
+    const [only] = heritage;
+    if (heritage.length === 1 && !only.typeArguments?.length && bare(only.expression)) {
+      const of = repositoryDeclaration(ts, checker, graph, only.expression, [kind.InterfaceDeclaration, kind.TypeAliasDeclaration, kind.ClassDeclaration]);
+      if (of && of !== statement.name.text) found.push({ node: statement, name: statement.name.text, of, form: `export interface ${statement.name.text} extends ${only.expression.getText()} {}` });
+    }
+  }
+  return found;
+}
+
+function aliasReexports({ context, graph }) {
+  const kind = context.ts.SyntaxKind;
+  const violations = [];
+  for (const [rel, node] of graph.files) {
+    const point = target => node.sourceFile.getLineAndCharacterOfPosition(target.getStart(node.sourceFile));
+    const checker = context.checkerFor(node.abs);
+    for (const statement of node.sourceFile.statements) {
+      for (const alias of declarationAliases(context.ts, checker, graph, statement)) {
+        const at = point(alias.node);
+        violations.push({
+          ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1, name: alias.name, aliasOf: alias.of,
+          message: `${alias.form} in ${rel} gives the declaration ${alias.of} a second name: use ${alias.of} where ${alias.name} is used and delete ${alias.name}.`,
+        });
+      }
+      if (statement.kind !== kind.ExportDeclaration || !statement.exportClause) continue;
+      const clause = statement.exportClause;
+      if (clause.kind === kind.NamespaceExport) {
+        const at = point(statement);
+        violations.push({
+          ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1, name: clause.name.text,
+          message: `export * as ${clause.name.text} in ${rel} publishes a whole module under a second name: export the declarations it holds by their own names.`,
+        });
+        continue;
+      }
+      for (const element of clause.elements) {
+        if (!element.propertyName || element.propertyName.text === element.name.text) continue;
+        const at = point(element);
+        violations.push({
+          ruleId: 'HFS_ALIAS_REEXPORT', path: rel, line: at.line + 1, column: at.character + 1,
+          name: element.name.text, aliasOf: element.propertyName.text,
+          message: `export { ${element.propertyName.text} as ${element.name.text} } in ${rel} gives one declaration a second name: rename the declaration to ${element.name.text}, or import and export it as ${element.propertyName.text}.`,
+        });
+      }
+    }
+  }
+  return { violations };
+}
+
+export function checkSymbols(input) {
+  const duplicates = duplicateSymbols(input);
+  const aliases = aliasReexports(input);
+  return {
+    violations: [...duplicates.violations, ...aliases.violations],
+    coverage: { status: 'checked', publicNames: duplicates.surface, duplicates: duplicates.violations.length, aliases: aliases.violations.length },
+  };
+}