@starci/eslint-canon-fe 6.0.2 → 7.1.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/surface.mjs

@@ -0,0 +1,91 @@
+/**
+ * The lint surface: which architecture-machine findings an ESLint rule judges instead of `hfs check`.
+ * Single source of truth. Each enforcer id is the rules.yaml enforcer; `codes` are the exact violation.ruleId strings its
+ * check file emits on source files. plugins: 'be' = back-end profile repos, 'fe' = front-end profile, graph checks run for both.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BE = ['be'];
+const FE = ['fe'];
+const BOTH = ['be', 'fe'];
+
+// `via` names the machine check (the key of its run in index.mjs) when two enforcers share a code; `origin: 'repo'` marks a finding of the
+// slot manifest's per-path judgement (hfs-path-findings.mjs) instead of the machine. A finding reaches exactly one rule.
+const enforcer = (id, plugins, codes, description, extra = {}) => Object.freeze({ id, plugins: Object.freeze(plugins), codes: Object.freeze(codes), description, ...extra });
+
+export const LINT_ENFORCERS = Object.freeze([
+  enforcer('duplicate-code', BOTH, ['HFS_DUPLICATE_CODE'], 'A block of production code never repeats elsewhere in the owner graph.'),
+  enforcer('duplicate-symbol', BOTH, ['HFS_DUPLICATE_SYMBOL'], 'A symbol name is declared once across the production source.'),
+  enforcer('alias-reexport', BOTH, ['HFS_ALIAS_REEXPORT'], 'An owner entry re-exports a symbol under its own name, never through a const alias.'),
+  // cross-app-duplicate emits only FE_CROSS_APP_DUPLICATE today; HFS_DUPLICATE_CODE is named in its comment only.
+  enforcer('cross-app-duplicate', FE, ['FE_CROSS_APP_DUPLICATE'], 'A file is never copied between apps; shared code lives in a package.'),
+  enforcer('dead-exports', BOTH, ['HFS_UNUSED_EXPORT', 'HFS_UNUSED_FILE'], 'Every owner export and every production file is reached by a root.'),
+  enforcer('tier-direction', BOTH, ['BE_TIER_DIRECTION', 'FE_TIER_DIRECTION'], 'An import goes only to a tier the slot matrix allows.'),
+  enforcer('owner-cycle', BOTH, ['ARCH_OWNER_CYCLE'], 'Owners never import each other in a cycle.'),
+  enforcer('feature-imports-feature', BE, ['BE_FEATURE_IMPORTS_FEATURE'], 'A feature never imports another feature.'),
+  enforcer('app-isolation', FE, ['FE_APP_ISOLATION'], 'An app never imports another app.'),
+  enforcer('feature-layout', BE, ['BE_FEATURE_LAYOUT_INVALID'], 'A feature file sits in the folder its role names.'),
+  enforcer('application-never-imports-transport', BE, ['BE_APPLICATION_IMPORTS_TRANSPORT', 'BE_APPLICATION_TRANSPORT_FRAMEWORK'], 'Application code never imports transport code, directly or through a chain.'),
+  enforcer('owner-export-bypass', BOTH, ['ARCH_OWNER_EXPORT_BYPASS', 'ARCH_OWNER_EXPORT_STAR'], 'Another owner is imported only through its index entry, and an entry never uses export star.'),
+  enforcer('feature-not-composed', BE, ['BE_FEATURE_NOT_COMPOSED'], 'Every feature owner is composed into an app.'),
+  enforcer('owner-reachable', FE, ['FE_OWNER_REACHABLE', 'FE_HREF_RESOLVES'], 'Every owner is mounted by a route and every href resolves to a route.'),
+  enforcer('app-composition-only', BE, ['BE_APP_COMPOSITION_ONLY', 'BE_APP_BUSINESS_ROLE'], 'An app only composes modules and holds no business role.'),
+  enforcer('entrypoint-only-in-apps', BE, ['BE_ENTRYPOINT_ONLY_IN_APPS'], 'NestFactory and bootstrap live only in an app main file.'),
+  enforcer('schema-owner', BE, ['BE_SCHEMA_OWNER'], 'Each entity array is registered by one owner across all apps.'),
+  enforcer('error-code-unique', BE, ['BE_ERROR_HOME'], 'An error code is declared once in the repository.'),
+  enforcer('error-masked', BE, ['BE_ERROR_MASKED'], 'Every app wires the error filter that masks internal errors.'),
+  enforcer('default-deny-app-guard', BE, ['BE_DEFAULT_DENY'], 'Every app registers the default-deny guard before any other guard.'),
+  // BE_MODULE_SHAPE is emitted by both register-once and module-per-transport.
+  enforcer('register-once', BE, ['BE_MODULE_SHAPE'], 'A module is registered once and imported by one module.', { via: 'registerOnce' }),
+  enforcer('module-per-transport', BE, ['BE_MODULE_SHAPE'], 'An app imports transport modules only.', { via: 'modulePerTransport' }),
+  enforcer('module-registration', BE, ['BE_MODULE_HANDLER_REGISTRATION', 'BE_MODULE_PROVIDER_REREGISTRATION'], 'Every handler is registered by a module and no provider is registered twice.'),
+  enforcer('background-unowned', BE, ['BE_BACKGROUND_UNOWNED'], 'Every background job is reachable from a worker app.'),
+  enforcer('test-world-files', BE, ['BE_TEST_TOPOLOGY'], 'The test world files match the stack declaration.'),
+  enforcer('unit-spec-providers', BE, ['BE_SPEC_QUALITY'], 'A unit spec provides exactly the dependencies its service constructor takes.'),
+  enforcer('transport-owner', FE, ['FE_TRANSPORT_OWNER'], 'One client and one outcome type own the transport of the repository.'),
+  enforcer('swr-data-lifecycle', FE, ['FE_SWR_KEY_IDENTITY', 'FE_SWR_MUTATION_RESOURCE_IDENTITY'], 'SWR keys and mutations share one resource identity.'),
+  enforcer('route-files-thin', FE, ['FE_ROUTE_FILES_THIN'], 'A route file only mounts one feature owner.'),
+  enforcer('route-adapter', FE, ['FE_ROUTE_ONE_PAGE', 'FE_ROUTE_DRAWING_DECISION', 'FE_ROUTE_CLIENT_BOUNDARY', 'FE_ROUTE_CLIENT_HOOK', 'FE_ROUTE_DEFAULT_EXPORT'], 'A page route is a server adapter that mounts one pages-tier component.'),
+  enforcer('client-reaches-server', FE, ['FE_CLIENT_REACHES_SERVER'], 'Client code never reaches server-only code through any import chain.'),
+  enforcer('hooks-are-hooks', FE, ['FE_HOOKS_ARE_HOOKS'], 'A hooks folder holds hooks only, one shared file per domain.'),
+  enforcer('hook-location', FE, ['FE_CUSTOM_HOOK_LOCATION', 'FE_BLOCK_PRODUCT_HOOK_DEFINITION', 'FE_COMPONENT_DEEP_HOOK_IMPORT'], 'A custom hook is defined in the hooks folder and imported through its entry.'),
+  enforcer('connection-map', BE, ['BE_CONNECTION_DUPLICATE'], 'Each database connection is declared once and matches the connection map.'),
+  enforcer('injection-token-exported', BE, ['BE_RAW_INJECT'], 'An injection token is exported by its owner and never injected raw.'),
+  enforcer('sql-owner', BE, ['BE_SQL_TABLE_OWNER'], 'A SQL table is touched only by the owner of its entity.'),
+  enforcer('readonly-boundary', BE, ['BE_READONLY_BOUNDARY'], 'Messages and injected classes crossing a boundary are readonly.'),
+  enforcer('source-names', BE, ['BE_SOURCE_FORM'], 'Names and forms inside a source file follow its role.'),
+  enforcer('public-contract-form', BE, ['BE_PUBLIC_CONTRACT_FORM'], 'A public signature is typed by a named contract, never inline or untyped.'),
+  enforcer('frontend-source-layout', FE, ['FE_SOURCE_LAYOUT_INVALID'], 'A front-end source file sits in a tier folder.'),
+  enforcer('component-purity', FE, ['FE_COMPONENT_WORLD_OWNERSHIP', 'FE_WORLD_OWNER_RENDER_BOUNDARY', 'FE_CONNECTED_BLOCK_RENDER_PAIR', 'FE_PURE_REACHES_DATA', 'FE_PURE_WORLD_HOOK', 'FE_PURE_WORLD_IMPORT'], 'A pure component reaches no data or world state; its connected entry owns them.'),
+  enforcer('grammar-entry', FE, ['ARCH_GRAMMAR_CONTRACT_INVALID', 'ARCH_GRAMMAR_EXPORT_BYPASS'], 'Vendor grammar is reached only through its owner entry.'),
+  enforcer('i18n-keys', FE, ['FE_I18N_KEYS'], 'Translation keys read by source and keys held by catalogs agree both ways.'),
+  // The per-path judgements of the slot manifest (scripts/lib/hfs-path-findings.mjs), on a tracked TypeScript file.
+  enforcer('slot-undeclared', BOTH, ['HFS_SLOT_UNDECLARED', 'HFS_SLOT_AMBIGUOUS', 'HFS_SLOT_NOT_ENABLED'], 'A TypeScript file is owned by exactly one slot of the repository.', { origin: 'repo' }),
+  enforcer('source-suffix', BE, ['BE_SOURCE_FORM'], 'A source file name is index.ts, main.ts, a migration or <kebab-name>.<suffix>.ts with a suffix of the closed list.', { origin: 'repo' }),
+  enforcer('spec-placement', BE, ['BE_SPEC_PLACEMENT'], 'A spec file lives in one of the four test layers and nowhere else.', { origin: 'repo' }),
+  // The two below are emitted into context.errors today, not into violations.
+  enforcer('package-imports-app', BOTH, ['ARCH_PACKAGE_IMPORTS_APP'], 'A package never imports an app.'),
+  enforcer('package-export-bypass', BOTH, ['ARCH_PACKAGE_EXPORT_BYPASS'], 'A package is imported only through its declared exports.'),
+]);
+
+export const LINT_CODES = new Set(LINT_ENFORCERS.flatMap(e => e.codes));
+
+export const TS_SOURCE = /\.(?:[cm]?tsx?)$/;
+
+/** True when a finding sits on an existing TypeScript file of the repository: the only findings an editor can show on a line. */
+export function attachesToSource(repositoryRoot, violation) {
+  const file = violation?.path;
+  if (typeof file !== 'string' || !TS_SOURCE.test(file)) return false;
+  return fs.existsSync(path.join(repositoryRoot, ...file.split('/')));
+}
+
+/** The finding's code: a machine violation spells it `ruleId`, a repository finding `code`. */
+export const codeOf = (finding) => finding?.ruleId ?? finding?.code;
+
+/** Whether `finding` (with its origin and check tags) belongs to `enforcer`. */
+export const belongsTo = (enforcer, finding) => enforcer.codes.includes(codeOf(finding))
+  && (finding.origin ?? 'machine') === (enforcer.origin ?? 'machine') && (enforcer.via === undefined || finding.check === enforcer.via);
+
+/** True when some lint rule owns the finding and it sits on an existing TypeScript file: it is an ESLint report, not a `hfs check` finding. */
+export const onLintSurface = (repositoryRoot, finding) => LINT_ENFORCERS.some(enforcer => belongsTo(enforcer, finding)) && attachesToSource(repositoryRoot, finding);