@starci/eslint-canon-be 3.3.0 → 3.4.0

package/runtime/scripts/lib/env.mjs

@@ -0,0 +1,20 @@
+// env.mjs - the one place the runtime reads a named environment variable (smell S8-01/S8-02/S11-04; scripts/checks/check-env.mjs).
+// modules/schemas/env.yaml catalogues every variable with its purpose and kind. Production code reads a variable here
+// (readEnv) or takes an injected `env` parameter; it never reads `process.env.NAME` itself. The test runner is observed
+// in exactly one place, isSpecRun: code that must not touch the host's real state during a spec asks it.
+
+/** The value of the environment variable `name` in `env` (default: the process environment), or undefined. */
+export const readEnv = (name, env = process.env) => env[name];
+
+/** True when `env` (default: the process environment) belongs to a spec run (`node --test` marks its children with NODE_TEST_CONTEXT). */
+export const isSpecRun = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);
+
+/**
+ * The environment for a child that is itself a test runner: `env` without the mark of an enclosing spec run. A `node --test` that inherits NODE_TEST_CONTEXT believes it is a
+ * subtest of that run: it reports to its parent and exits 0 whatever its tests did, so a verb that runs specs as a child (starci test affected, the land gate, the release cut, the
+ * suite) would pass red specs from inside a test process. The runner marks the spec files it starts itself, so isSpecRun stays true inside them.
+ */
+export function withoutTestRunner(env = process.env) {
+  const { NODE_TEST_CONTEXT: _enclosing, ...rest } = env;
+  return rest;
+}

package/runtime/scripts/lib/event-contract.mjs

@@ -0,0 +1,107 @@
+// event-contract.mjs - the async contract between the services of one product (R166 HFS_EVENT_CONTRACT).
+// The one source of the contract is the typed event classes of a service, `be/src/modules/events/<service>/<event>.event.ts`:
+//   export interface OrderPlacedPayload { readonly orderId: string; readonly totalMinorUnits: number }
+//   export class OrderPlacedEvent extends BaseEvent {
+//     static readonly eventName = "order.placed"; static readonly version = 1
+//     static readonly compensates = "order.placed"            // only an event that reports the failure of a step
+//     static create(payload: OrderPlacedPayload): OrderPlacedEvent { ... }
+//   }
+// `starci app emit` writes `be/contracts/<service>/events.json` from them (name, version, compensates, and the payload fields of the
+// interface `create` takes); `starci app check` compares the committed file with the same reader. Nothing is executed: both walk the TypeScript
+// syntax tree. The functions take the `ts` module the caller loaded (the repository's own, else the runtime's); this file imports only the code-unit comparator.
+import { byCodeUnit } from './list.mjs';
+
+const EVENT_CONTRACT_SCHEMA = 'starci/event-contract@1';
+const FIELD_TYPE = /^(?:string|number|boolean|string\[\]|number\[\])\??$/;
+
+const hasStatic = (ts, member) => member.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.StaticKeyword) === true;
+
+/** The literal of a `static readonly <name> = <literal>` member: `{ text }` for a string, `{ number }` for an integer, or null. */
+function staticLiteral(ts, member) {
+  if (!ts.isPropertyDeclaration(member) || !hasStatic(ts, member) || !ts.isIdentifier(member.name) || member.initializer === undefined) return null;
+  let value = member.initializer;
+  while (ts.isAsExpression(value) || ts.isParenthesizedExpression(value)) value = value.expression;
+  if (ts.isStringLiteralLike(value)) return { name: member.name.text, text: value.text };
+  if (ts.isNumericLiteral(value) && Number.isInteger(Number(value.text))) return { name: member.name.text, number: Number(value.text) };
+  return null;
+}
+
+/** The text of a type node when it is one of the wire field types (`string`, `number`, `boolean`, `string[]`, `number[]`), else null. */
+function fieldType(ts, node) {
+  if (node.kind === ts.SyntaxKind.StringKeyword) return 'string';
+  if (node.kind === ts.SyntaxKind.NumberKeyword) return 'number';
+  if (node.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean';
+  if (ts.isArrayTypeNode(node)) {
+    const element = fieldType(ts, node.elementType);
+    return element === 'string' || element === 'number' ? `${element}[]` : null;
+  }
+  return null;
+}
+
+function appendPayloadMember(ts, member, typeName, problems, where, payload) {
+  if (!ts.isPropertySignature(member) || !ts.isIdentifier(member.name) || member.type === undefined) {
+    problems.push(`${where}: the payload ${typeName} holds a member that is not \`name: type\``);
+    return;
+  }
+  const type = fieldType(ts, member.type);
+  let written = null;
+  if (type !== null) written = `${type}${member.questionToken ? '?' : ''}`;
+  if (written === null || !FIELD_TYPE.test(written)) problems.push(`${where}: payload field ${member.name.text} must be string, number, boolean, string[] or number[]`);
+  else payload[member.name.text] = written;
+}
+
+/** The payload fields of the interface or type literal named `typeName` in the file: `{ <field>: <type> }`, optional fields with a `?`. */
+function payloadOf(ts, sourceFile, typeName, problems, where) {
+  let members = null;
+  for (const statement of sourceFile.statements) {
+    if (ts.isInterfaceDeclaration(statement) && statement.name.text === typeName) members = statement.members;
+    if (ts.isTypeAliasDeclaration(statement) && statement.name.text === typeName && ts.isTypeLiteralNode(statement.type)) members = statement.type.members;
+  }
+  if (members === null) {
+    problems.push(`${where}: the payload type ${typeName} is not an interface or type literal of the file`);
+    return {};
+  }
+  const payload = {};
+  for (const member of members) appendPayloadMember(ts, member, typeName, problems, where, payload);
+  return payload;
+}
+
+/**
+ * The event classes of one source text: `{ events: [{ className, name, version, compensates, payload }], problems: [text] }`. A class is an event
+ * when it declares `static readonly eventName`; `version` is required, `create(payload: <Interface>)` names the payload.
+ */
+export function readEventClasses(ts, text, file = 'event.ts') {
+  const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const events = [];
+  const problems = [];
+  for (const statement of sourceFile.statements) {
+    if (!ts.isClassDeclaration(statement) || statement.name === undefined) continue;
+    const literals = statement.members.map((member) => staticLiteral(ts, member)).filter((literal) => literal !== null);
+    const name = literals.find((literal) => literal.name === 'eventName')?.text;
+    if (name === undefined) continue;
+    const className = statement.name.text;
+    const version = literals.find((literal) => literal.name === 'version')?.number;
+    const compensates = literals.find((literal) => literal.name === 'compensates')?.text;
+    if (version === undefined || version < 1) problems.push(`${className} needs \`static readonly version\` as a positive integer`);
+    const create = statement.members.find((member) => ts.isMethodDeclaration(member) && hasStatic(ts, member) && ts.isIdentifier(member.name) && member.name.text === 'create');
+    const parameter = create?.parameters[0]?.type;
+    if (parameter === undefined || !ts.isTypeReferenceNode(parameter) || !ts.isIdentifier(parameter.typeName)) {
+      problems.push(`${className} needs \`static create(payload: <Interface>)\` naming its payload interface`);
+      continue;
+    }
+    events.push({ className, name, version: version ?? 0, ...(compensates === undefined ? {} : { compensates }), payload: payloadOf(ts, sourceFile, parameter.typeName.text, problems, className) });
+  }
+  return { events, problems };
+}
+
+/** The sorted object: keys in code-point order, recursively (what the snapshot prints). */
+const sorted = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sorted(value[key])])) : value);
+
+/** The text of the snapshot of a service from its event classes: 2-space JSON, sorted keys, one final newline. */
+export function snapshotText(service, events) {
+  const table = Object.fromEntries(events.map(({ name, version, compensates, payload }) => [name, { version, payload, ...(compensates === undefined ? {} : { compensates }) }]));
+  return `${JSON.stringify(sorted({ schema: EVENT_CONTRACT_SCHEMA, service, events: table }), null, 2)}\n`;
+}
+
+/** The snapshot's text with line endings folded, for comparing a committed file to a fresh one. */
+export const folded = (text) => text.replaceAll('\r\n', '\n');

package/runtime/scripts/lib/json-clone.mjs

@@ -0,0 +1,61 @@
+// json-clone.mjs — a deep copy that keeps exactly what survives a JSON text and nothing else: the plain-data
+// copy of a value, detached from every reference, frozen state and class of the original. `structuredClone` keeps
+// what JSON drops (undefined members, Dates, Maps, sparse holes) and refuses what JSON accepts (functions,
+// `toJSON` objects), so it is not a substitute; this walks the value once under the JSON.stringify rules.
+
+/** The boxed primitives JSON.stringify unwraps: recognised by the internal slot a valueOf call reads, as JSON does. */
+const BOXED = [
+  { slot: Number.prototype.valueOf, read: Number },
+  { slot: String.prototype.valueOf, read: String },
+  { slot: Boolean.prototype.valueOf, read: (box) => Boolean.prototype.valueOf.call(box) },
+  { slot: BigInt.prototype.valueOf, read: (box) => BigInt.prototype.valueOf.call(box) },
+];
+
+/** Whether `value` carries the internal slot `slot` reads (a valueOf of that boxed type does not throw on it). */
+const hasSlot = (slot, value) => {
+  try { slot.call(value); return true; } catch { return false; }
+};
+
+/** What JSON.stringify takes of `holder[key]`: the toJSON result when there is one, a boxed primitive unwrapped. */
+const serialized = (holder, key) => {
+  let value = holder[key];
+  if (value !== null && (typeof value === 'object' || typeof value === 'bigint') && typeof value.toJSON === 'function') value = value.toJSON(key);
+  if (value === null || typeof value !== 'object') return value;
+  const box = BOXED.find((candidate) => hasSlot(candidate.slot, value));
+  return box ? box.read(value) : value;
+};
+
+/** A member JSON leaves out of an object (and writes as null in an array). */
+const isAbsent = (value) => value === undefined || typeof value === 'function' || typeof value === 'symbol';
+
+const copyValue = (value, ancestors) => {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value + 0 : null;
+  if (typeof value === 'bigint') throw new TypeError('Do not know how to serialize a BigInt');
+  if (ancestors.includes(value)) throw new TypeError('Converting circular structure to JSON');
+  const inside = [...ancestors, value];
+  if (Array.isArray(value)) {
+    return Array.from({ length: value.length }, (_, index) => {
+      const item = serialized(value, String(index));
+      return isAbsent(item) ? null : copyValue(item, inside);
+    });
+  }
+  const entries = [];
+  for (const name of Object.keys(value)) {
+    const member = serialized(value, name);
+    if (!isAbsent(member)) entries.push([name, copyValue(member, inside)]);
+  }
+  return Object.fromEntries(entries);
+};
+
+/**
+ * `value` copied as JSON data: members that are undefined, functions or symbols are dropped (an array item becomes
+ * null), non-finite numbers become null and -0 becomes 0, `toJSON` results replace their objects (a Date becomes its ISO string), boxed
+ * primitives unwrap, and a cycle or a BigInt throws a TypeError. A value JSON has no text for (undefined, a function,
+ * a symbol) throws a SyntaxError, as parsing the missing text does.
+ */
+export function jsonClone(value) {
+  const top = serialized({ '': value }, '');
+  if (isAbsent(top)) throw new SyntaxError('"undefined" is not valid JSON');
+  return copyValue(top, []);
+}

package/runtime/scripts/lib/list.mjs

@@ -17,6 +17,10 @@ export const objectList = (v) => (Array.isArray(v) ? v : []).filter((item) => it
 export const stringList = (v, { blank = true } = {}) =>
   Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0 && (blank || s.trim().length > 0));
 
+/** A non-empty list of distinct values, all accepted by the supplied predicate. */
+export const nonemptyUniqueList = (values, accepts) => Array.isArray(values) && values.length > 0
+  && values.every((entry) => accepts(entry)) && new Set(values).size === values.length;
+
 /** The items of a `sep`-separated list: trimmed, empties dropped; `dedupe` keeps first occurrences only. */
 export const splitList = (v, { sep = ',', dedupe = false } = {}) => {
   const items = String(v ?? '').split(sep).map((s) => s.trim()).filter(Boolean);

package/runtime/scripts/lib/secret-patterns.mjs

@@ -12,6 +12,57 @@ export const FORBIDDEN_FILES = [
   { name: 'starcistacks-secret-plaintext', test: (f) => /(^|\/)\.starcistacks\/[^/]+\/secrets\//i.test(f) && !/(\.enc|\/\.gitkeep|\/KEYS\.md)$/i.test(f) },
   { name: 'credentials-json', test: (f) => /(^|\/)(credentials|service-account|client_secret)[^/]*\.json$/i.test(f) },
 ];
+// `word` in any case (name checks are case-aware by construction, not by flag).
+const fold = (word) => word.replace(/[a-z]/gi, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
+
+// A name that holds secret material: the keyword is an identifier segment, so DB_PASSWORD, dbPassword,
+// OPENAI_API_KEY, api_secret and accessToken are candidates while `secondary`, `tokenize`, `monkey`, `secrets.x`
+// and `$secret` are not. A segment starts at the name edge, after `_`/`-`/`.`, or at a camel hump.
+const SECRET_WORD = [
+  'password', 'passwd', 'passphrase', 'secret', 'credentials?', 'token',
+  'api[_-]?key', 'access[_-]?token', 'auth[_-]?token', 'refresh[_-]?token', 'id[_-]?token', 'session[_-]?token',
+  'client[_-]?secret', 'api[_-]?secret', 'session[_-]?secret', 'jwt[_-]?secret',
+  'private[_-]?key', 'secret[_-]?key', 'signing[_-]?key', 'encryption[_-]?key', 'master[_-]?key',
+  'service[_-]?role[_-]?key', 'service[_-]?key', 'session[_-]?key',
+].map((word) => fold(word)).join('|');
+
+// A name whose last segment is configuration, not material: SECRET_FILE and *_PATH point at the materialized
+// secret file (the materializer's own form), PASSWORD_MIN_LENGTH is a number, *_REF/_ID a reference.
+const BENIGN_WORD = [
+  'file', 'path', 'dir', 'url', 'uri', 'endpoint', 'host', 'refs?', 'names?', 'ids?', 'arn', 'urn',
+  'length', 'min', 'max', 'size', 'count', 'budget', 'limit', 'regex', 'pattern', 'policy',
+  'algorithm', 'scheme', 'expiry', 'expires', 'ttl', 'required', 'enabled', 'disabled', 'type', 'version',
+].map((word) => fold(word)).join('|');
+
+const SEGMENT_BEFORE = String.raw`(?:(?<![A-Za-z0-9_$])|(?<=[_\-.])|(?<=[a-z])(?=[A-Z]))`;
+const NAME_REST = '[A-Za-z0-9_$.-]*?';
+const SECRET_NAME = [
+  '(?<![A-Za-z0-9_$])',
+  String.raw`(?!${NAME_REST}${SEGMENT_BEFORE}(?:${BENIGN_WORD})(?=\s*[:=]))`,
+  String.raw`(?=${NAME_REST}${SEGMENT_BEFORE}(?:${SECRET_WORD})(?=[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$))`,
+  String.raw`[A-Za-z_$][A-Za-z0-9_$.-]*\s*[:=]\s*`,
+].join('');
+
+// `password = "hunter2hunter2"` — the quoted literal. `env(NAME)` is a reference, never a secret.
+const ASSIGNED_QUOTED = new RegExp(
+  SECRET_NAME + String.raw`['"\`](?!env\([A-Z_][A-Z0-9_]*\)['"\`])([^'"\`\n\s$<{]{12,})['"\`]`,
+);
+// `DB_PASSWORD=hunter2hunter2` — the compose list-item and dotenv form; the dotenv value has no `:` so
+// `password: secret:db/password` and `token: ref:vault/api` stay references, and the end boundary keeps
+// calls and member/index references such as `secret = credentialsSource.current` out of the literals.
+const ASSIGNED_UNQUOTED = new RegExp(
+  SECRET_NAME + String.raw`(?!['"\`]|env\()([A-Za-z0-9_+=-]{12,})(?![A-Za-z0-9_+=.(\[-])`,
+);
+
+const NAME_WORD = (word, tail) => new RegExp(`^${NAME_REST}${SEGMENT_BEFORE}(?:${word})${tail}`);
+const SECRET_NAME_TEST = NAME_WORD(SECRET_WORD, String.raw`(?:[_\-.]|[A-Z]|[^A-Za-z0-9_$]|$)`);
+const BENIGN_TAIL_TEST = NAME_WORD(BENIGN_WORD, '$');
+
+/** True when a bare variable `name` holds secret material as an identifier segment (DB_PASSWORD, dbPassword,
+ *  SUPABASE_SERVICE_ROLE_KEY) and does not end in a config suffix (PASSWORD_MIN_LENGTH, SECRET_FILE,
+ *  tokenBudget). The same name judgement the `assigned-secret` patterns make, for callers that read keys. */
+export const secretNameLike = (name) => SECRET_NAME_TEST.test(name) && !BENIGN_TAIL_TEST.test(name);
+
 export const SECRET_PATTERNS = [
   { name: 'private-key-block', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
   { name: 'aws-access-key', re: /\bAKIA[0-9A-Z]{16}\b/ },
@@ -23,17 +74,20 @@ export const SECRET_PATTERNS = [
   { name: 'telegram-bot-token', re: /\b\d{8,10}:AA[0-9A-Za-z_-]{33}\b/ },
   { name: 'stripe-secret', re: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/ },
   { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+  { name: 'age-secret-key', re: /\bAGE-SECRET-KEY-1[0-9A-Z]{20,}\b/ },
+  { name: 'password-connection-string', re: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis):\/\/[^:\s/@]+:[^@\s/${}]{8,}@/iu },
   // A value written `env(NAME)` (the Supabase config.toml reference form) names a variable, not a secret.
   // A keyword-assigned value that names itself a stand-in (a test stub's `accessToken: "fixture-..."`) is no
   // candidate; only this heuristic takes the exemption, never a provider-shaped token above.
   // A spec file's keyword-assigned values are test inputs (a spec's sign-in
   // form password and a mocked accessToken once refused a push): the heuristic skips spec files too.
-  { name: 'assigned-secret', re: new RegExp([
-    String.raw`\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|client[_-]?secret)`,
-    String.raw`\b\s*[:=]\s*['"](?!env\([A-Z_][A-Z0-9_]*\)['"])([^'"\s$<{]{12,})`,
-    `['"]`,
-  ].join(''), 'i'), placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+  // A SCREAMING_SNAKE quoted value in source is a public code (an enum member whose value is an upper-case code), not a credential.
+  { name: 'assigned-secret', re: ASSIGNED_QUOTED, sourceCode: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
     skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$/ },
+  // An unquoted value in TypeScript or JavaScript source is an identifier or a type (`token: InjectionToken`,
+  // `MODULE_OPTIONS_TOKEN: DATABASE_OPTIONS_TOKEN`), never a literal; the unquoted form is the dotenv, compose and toml shape.
+  { name: 'assigned-secret', re: ASSIGNED_UNQUOTED, placeholder: /fixture|stub|fake|dummy|placeholder|example|sample|changeme|redacted|mock/i,
+    skipFile: /\.(?:spec|test|e2e-spec)\.[cm]?[jt]sx?$|\.[cm]?[jt]sx?$/ },
 ];
 
 
@@ -43,6 +97,7 @@ export function secretHits(file, text) {
   for (const rule of SECRET_PATTERNS) {
     if (rule.skipFile?.test(file ?? '')) continue;
     const hit = rule.re.exec(text);
+    if (hit && rule.sourceCode?.test(hit[1] ?? '') && /\.[cm]?[jt]sx?$/.test(file ?? '')) continue;
     if (hit && !rule.placeholder?.test(hit[1] ?? '')) names.push(rule.name);
   }
   return names;

package/runtime/scripts/lib/stack-services.mjs

@@ -58,7 +58,7 @@ const KNOWN_IMAGES = Object.freeze({
 export const STATEFUL_KINDS = Object.freeze(new Set(['database', 'cache', 'identity', 'storage', 'mail', 'queue', 'search']));
 
 /** The repository name of an image reference: `quay.io/keycloak/keycloak:26.0` -> `keycloak`. */
-const repositoryOf = image => {
+export const repositoryOf = image => {
   const withoutDigest = image.split('@')[0];
   const lastSegment = withoutDigest.split('/').at(-1) ?? withoutDigest;
   return lastSegment.split(':')[0];

package/runtime/scripts/lib/ts-analysis.mjs

@@ -1,7 +1,7 @@
 /** The expression under the wrappers selected by an AST check's contract. */
-export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, satisfiesExpressions = true } = {}) {
+export function unwrapExpression(ts, expression, { awaitExpressions = false, typeAssertions = true, nonNullExpressions = true, satisfiesExpressions = true } = {}) {
   while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
-    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || ts.isNonNullExpression(expression)
+    || (typeAssertions && ts.isTypeAssertionExpression(expression)) || (nonNullExpressions && ts.isNonNullExpression(expression))
     || (satisfiesExpressions && (ts.isSatisfiesExpression?.(expression) ?? false))
     || (awaitExpressions && ts.isAwaitExpression(expression)))) expression = expression.expression;
   return expression;
@@ -18,3 +18,6 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
   }
   return imports;
 }
+
+/** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
+export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });

package/runtime/scripts/lib/ts-ast.mjs

@@ -11,8 +11,18 @@ export const hasAnyFlag = (flags, mask) => ((flags ?? 0) & mask) !== 0;
 /** Whether the variable `declaration` belongs to a `const` list: the TypeScript node-flag test, an explicit comparison of the masked flags. */
 export const isConstVariable = (ts, declaration) => (ts.getCombinedNodeFlags(declaration.parent) & ts.NodeFlags.Const) !== 0;
 
-/** The text of an identifier or a string-literal-like `node`, or null (property names, literal specifiers). */
-export const nameText = (ts, node) => (node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null);
+/** Text of a string-literal-like node or an enabled identifier/numeric name; null for other expressions. */
+export function nameText(ts, node, { identifiers = true, numbers = false } = {}) {
+  if (!node) return null;
+  if (ts.isStringLiteralLike(node) || (identifiers && ts.isIdentifier(node)) || (numbers && ts.isNumericLiteral(node))) return node.text;
+  return null;
+}
+
+/** A statically selected property name, including string-literal element access; null for computed selections. */
+export function accessName(ts, node) {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  return ts.isElementAccessExpression(node) ? literalText(ts, node.argumentExpression) : null;
+}
 
 /** The text of a string-literal-like `node` (a string literal or a no-substitution template), or null. */
 export const literalText = (ts, node) => (node && ts.isStringLiteralLike(node) ? node.text : null);
@@ -42,3 +52,18 @@ export function propertyText(ts, text, { file = 'source.ts', key, declaration =
   visit(source);
   return value;
 }
+
+/** Initializers of every identifier-named variable, grouped in traversal order across the source's scopes. */
+export function variableInitializerGroups(ts, source) {
+  const groups = new Map();
+  const collect = (node) => {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      const initializers = groups.get(node.name.text) ?? [];
+      initializers.push(node.initializer);
+      groups.set(node.name.text, initializers);
+    }
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  return groups;
+}

package/service-isolation.mjs

@@ -19,6 +19,9 @@ const isRelative = (specifier) => specifier === "." || specifier === ".." || spe
 
 /** Calls `check(node, specifier)` for every import and re-export that names a module. */
 const onSpecifiers = (check) => ({
+  ImportExpression(node) {
+    check(node.source, node.source.value)
+  },
   ImportDeclaration(node) {
     check(node.source, node.source.value)
   },

package/size-budget.mjs

@@ -4,7 +4,8 @@
  * A source file has a hard-growth budget of `fileLines.hardGrowth` lines (`ruleParams.be.fileLines` of the
  * slot manifest, read through `settings.starci.hfs`, see `lib/hfs.mjs`). `file-size-growth` is the ratchet and fails only on a file that must not
  * be this long: a NEW file over the budget, or an existing file over the budget that is longer than its recorded size.
- * The recorded size is the file's line count at the parent commit (`git show HEAD:<file>`). A file may stay as large
+ * The recorded size is the file's line count at `merge-base HEAD <base>` (STARCI_BASE_REF, origin/main, then main).
+ * Only staged lint text in a commit hook is compared with HEAD. An unavailable baseline is reported. A file may stay as large
  * as it is; it may not grow, and it may not be born large. The rule takes no option: the budget is the manifest's, the
  * baseline is git's.
  *
@@ -33,7 +34,8 @@ export const fileSizeGrowth = {
         schema: [],
         messages: {
             born: "This new file has {{lines}} lines, over the budget of {{max}}. A new file starts within the budget: split it by responsibility.",
-            grew: "This file has {{lines}} lines, over the budget of {{max}}, and it was {{recorded}} at the parent commit. A file over the budget may not grow: move the new code into its own file.",
+            grew: "This file has {{lines}} lines, over the budget of {{max}}, and it was {{recorded}} at the recorded revision. A file over the budget may not grow: move the new code into its own file.",
+            unavailable: "The recorded size of this over-budget file is unavailable. Make STARCI_BASE_REF, origin/main or main and its merge-base history available before linting.",
         },
     },
     create(context) {
@@ -43,11 +45,13 @@ export const fileSizeGrowth = {
         const max = hardGrowthLines(hfs.ruleParams.fileLines)
         return {
             "Program:exit"(node) {
-                const lines = lineCount((context.sourceCode || context.getSourceCode()).text)
+                const source = (context.sourceCode || context.getSourceCode()).text
+                const lines = lineCount(source)
                 if (lines <= max) return
-                const recorded = recordedLines(filename)
+                const recorded = recordedLines(filename, { source })
                 const loc = { line: 1, column: 0 }
-                if (recorded === null) context.report({ node, loc, messageId: "born", data: { lines, max } })
+                if (recorded === "unavailable") context.report({ node, loc, messageId: "unavailable" })
+                else if (recorded === null) context.report({ node, loc, messageId: "born", data: { lines, max } })
                 else if (lines > recorded) context.report({ node, loc, messageId: "grew", data: { lines, max, recorded } })
             },
         }

package/third-party-owner.mjs

@@ -0,0 +1,149 @@
+/**
+ * R279 BE_THIRD_PARTY_OWNER: dependencies outside the pure-library and framework vocabulary belong to one integration.
+ *
+ * The SDK inventory comes from the app-root package.json, not a list of SDK names. An unknown dependency is therefore
+ * subject to ownership immediately. R90's infrastructure table remains authoritative for its existing libraries;
+ * framework packages here supply composition, transport and persistence types that other canon rules already judge.
+ * The HFS view decides every source file's tier and owner, including imports in specs and provider support files.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { isBuiltin } from "node:module"
+import { dirname, join, resolve } from "node:path"
+import ts from "typescript"
+import { hfsOf, inTestWorld } from "./lib/hfs.mjs"
+import { moduleReferences } from "./lib/import-source.mjs"
+import { isSpecFile } from "./lib/path.mjs"
+
+const PURE = new Set([
+    "class-transformer", "class-validator", "rxjs", "reflect-metadata", "tslib", "zod", "lodash", "lodash-es",
+    "ramda", "decimal.js", "big.js", "bignumber.js", "uuid", "nanoid", "graphql", "graphql-scalars", "graphql-tag",
+    "dataloader", "fast-json-stable-stringify", "ajv", "yaml", "js-yaml", "semver",
+])
+const FRAMEWORK = new Set([
+    "@nestjs/common", "@nestjs/core", "@nestjs/cqrs", "@nestjs/graphql", "@nestjs/apollo", "@nestjs/platform-express",
+    "@nestjs/typeorm", "@nestjs/swagger", "@nestjs/mapped-types", "@nestjs/throttler", "@apollo/server",
+    "@as-integrations/express5", "express", "nest-commander", "typeorm",
+])
+const TEST_LIBRARIES = new Set(["@nestjs/testing", "@starci/jest-preset", "@starci/test-world", "@jest/globals", "jest", "jest-mock"])
+const INVENTORIES = new WeakMap()
+const SOURCE = /\.[cm]?[jt]sx?$/
+const GENERATED = new Set(["node_modules", "dist", "coverage", ".git"])
+
+/** The package root of a bare module specifier, including a scoped package's subpaths. */
+const packageOf = (specifier) => {
+    if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("#") || isBuiltin(specifier)) return null
+    const parts = specifier.split("/")
+    return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]
+}
+
+/** A file that the back-end slot view classifies as executable source or a test. */
+const inSource = (hfs, file) => {
+    const tier = hfs.tierOf(file)
+    return (tier !== null && tier !== "none") || hfs.slotOf(file)?.startsWith("be.tests.") === true
+}
+
+/** Every literal module reference in a source file, including dynamic imports, require and re-exports. */
+const referencesOf = (file, text) => {
+    const found = new Set()
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true)
+    const add = (node) => {
+        if (node && (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))) found.add(node.text)
+    }
+    const visit = (node) => {
+        if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(node.moduleSpecifier)
+        else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(node.moduleReference.expression)
+        else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || (ts.isIdentifier(node.expression) && node.expression.text === "require"))) add(node.arguments[0])
+        ts.forEachChild(node, visit)
+    }
+    visit(source)
+    return found
+}
+
+/**
+ * The app's dependency declarations and the SDK imports of all integration owners, read once for this HFS view.
+ * No ancestor search: be/ has the app-root package.json immediately above it; standalone fixtures may put it at root.
+ */
+const inventoryOf = (hfs) => {
+    if (INVENTORIES.has(hfs)) return INVENTORIES.get(hfs)
+    const appManifest = join(dirname(hfs.repoRoot), "package.json")
+    const manifest = existsSync(appManifest) ? appManifest : join(hfs.repoRoot, "package.json")
+    if (!existsSync(manifest)) throw new Error("third-party-import-owner needs the app-root package.json beside be/ to derive SDK ownership")
+    const declaration = JSON.parse(readFileSync(manifest, "utf8"))
+    const dependencies = new Map()
+    for (const section of ["dependencies", "optionalDependencies", "peerDependencies", "devDependencies"]) {
+        for (const [name, version] of Object.entries(declaration[section] ?? {})) {
+            if (/^(?:workspace:|file:|link:)/.test(String(version))) continue
+            const alias = /^npm:((?:@[^/]+\/)?[^@]+)(?:@|$)/.exec(String(version))
+            dependencies.set(name, alias?.[1] ?? name)
+        }
+    }
+    const byFile = new Map()
+    const walk = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (GENERATED.has(entry.name) || entry.isSymbolicLink()) continue
+            const file = join(directory, entry.name)
+            if (entry.isDirectory()) walk(file)
+            else if (SOURCE.test(entry.name) && hfs.tierOf(file) === "integrations") byFile.set(resolve(file), referencesOf(file, readFileSync(file, "utf8")))
+        }
+    }
+    walk(hfs.repoRoot)
+    const result = { dependencies, byFile }
+    INVENTORIES.set(hfs, result)
+    return result
+}
+
+/** The table already owns this import (including a package subpath); R90 alone judges it. */
+const inInfraTable = (hfs, specifier) => Object.keys(hfs.ruleParams.infraOwners).some((key) => specifier === key || specifier.startsWith(`${key}/`))
+
+/** The declared SDK identity, or null for an import that belongs to another existing concern. */
+const sdkOf = (hfs, dependencies, file, specifier) => {
+    const name = packageOf(specifier)
+    const dependency = dependencies.get(name)
+    if (!dependency || inInfraTable(hfs, specifier) || PURE.has(dependency) || FRAMEWORK.has(dependency)) return null
+    const isTest = isSpecFile(file) || hfs.slotOf(file)?.startsWith("be.tests.") === true
+    if (isTest && TEST_LIBRARIES.has(dependency)) return null
+    if (inTestWorld(hfs, file) && (dependency === "testcontainers" || dependency.startsWith("@testcontainers/"))) return null
+    return dependency
+}
+
+/** Every third-party SDK import stays in a single integrations/<provider> capability. */
+export const thirdPartyImportOwner = {
+    meta: {
+        type: "problem",
+        docs: { description: "BE_THIRD_PARTY_OWNER: a declared third-party SDK is imported only by one integration owner." },
+        schema: [],
+        messages: {
+            foreign: "[BE_THIRD_PARTY_OWNER] `{{name}}` is a third-party dependency from package.json. Import its SDK only inside one `integrations/<provider>` capability and inject that integration's public API here.",
+            multiple: "[BE_THIRD_PARTY_OWNER] `{{name}}` is imported by multiple integrations: {{owners}}. Keep its SDK, credentials and protocol mapping in one `integrations/<provider>` owner.",
+        },
+    },
+    create(context) {
+        const hfs = hfsOf(context)
+        const file = context.filename
+        if (!inSource(hfs, file)) return {}
+        let inventory
+        return moduleReferences(({ source, value }) => {
+            // Relative paths, node builtins and the infrastructure table need no dependency manifest.
+            if (packageOf(value) === null || inInfraTable(hfs, value)) return
+            inventory ??= inventoryOf(hfs)
+            const sdk = sdkOf(hfs, inventory.dependencies, file, value)
+            if (sdk === null) return
+            const here = hfs.ownerOf(file)
+            if (hfs.tierOf(file) !== "integrations" || here === null) {
+                context.report({ node: source, messageId: "foreign", data: { name: value } })
+                return
+            }
+            const owners = new Set([here])
+            for (const [other, references] of inventory.byFile) {
+                // ESLint's current buffer replaces the on-disk text of this file.
+                if (other === resolve(file)) continue
+                if ([...references].some((reference) => sdkOf(hfs, inventory.dependencies, other, reference) === sdk)) owners.add(hfs.ownerOf(other))
+            }
+            if (owners.size > 1) context.report({ node: source, messageId: "multiple", data: { name: sdk, owners: [...owners].sort().map((owner) => `\`${owner}\``).join(", ") } })
+        })
+    },
+}
+
+/** The published rule and its required severity. */
+export const rules = { "third-party-import-owner": thirdPartyImportOwner }
+export const recommended = { "starci-be/third-party-import-owner": "error" }

package/transport.mjs

@@ -15,6 +15,7 @@ import { hfsOf } from "./lib/hfs.mjs"
 import { decoratorArguments, decoratorCallee, importOf, isImportedFrom, moduleReferences } from "./lib/import-source.mjs"
 import { isTransportSlot, KIND_DOOR_SLOTS } from "./lib/transport-slots.mjs"
 import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
+import { operationRouteEvidence, restExceptionEvidence } from "./operations.mjs"
 
 /** The HTTP route decorators of `@nestjs/common`. */
 const HTTP_ROUTES = ["Get", "Post", "Put", "Patch", "Delete", "All", "Options", "Head"]
@@ -395,47 +396,28 @@ export const noCapabilityImportsFeatures = {
 
 // -- rest-door-needs-a-reason ------------------------------------------------------------------------------------
 
-/** The `PublicReason` members that justify a REST door: a probe, a handshake and a signed webhook. */
-const REST_REASONS = new Set(["Health", "AuthHandshake", "SignedWebhook"])
-
-/** Nest and Express exports whose presence shows a byte stream or a redirect. */
-const BYTE_EVIDENCE = [
-    { source: "@nestjs/common", names: ["StreamableFile", "Redirect"] },
-    { source: "@nestjs/platform-express", names: ["FileInterceptor", "FilesInterceptor", "AnyFilesInterceptor", "FileFieldsInterceptor"] },
-    { source: "node:fs", names: ["createReadStream"] },
-    { source: "fs", names: ["createReadStream"] },
-]
-
-/** True when the class shows one of the four reasons a door is REST: a public reason, a byte stream, or an OAuth redirect. */
-const showsReason = (context, controller) => {
-    let shown = false
-    walk(controller, (node) => {
-        if (shown) return
-        if (node.type === "MemberExpression" && !node.computed && node.property.type === "Identifier" && REST_REASONS.has(node.property.name) && node.object.type === "Identifier" && importOf(context, node.object)?.imported === "PublicReason") shown = true
-        if (node.type === "Identifier" && !(node.parent?.type === "MemberExpression" && node.parent.property === node && !node.parent.computed)) {
-            const found = importOf(context, node)
-            if (found && BYTE_EVIDENCE.some((evidence) => evidence.source === found.source && evidence.names.includes(found.imported))) shown = true
-        }
-    })
-    return shown
-}
-
-/** A REST door exists only where GraphQL cannot go, and the class has to show which case it is. */
+/** A REST door exists only where GraphQL cannot go, and each route has to show which case it is. */
 export const restDoorNeedsAReason = {
     meta: {
         type: "problem",
-        docs: { description: "A `@Controller` shows a public reason (Health, AuthHandshake, SignedWebhook) or a byte stream or redirect." },
+        docs: { description: "Every REST route shows its own public reason (Health, AuthHandshake, SignedWebhook), byte transfer, redirect or declared operation table." },
         schema: [],
         messages: {
-            unjustified: "This REST door shows none of the reasons a door may not be GraphQL: a probe, an auth handshake (OAuth redirect) or a signed webhook (`@Public({ reason: PublicReason.X })`), or a byte stream. A plain JSON read belongs in the GraphQL schema, where the client already is.",
+            unjustified: "[BE_REST_DOOR_EVIDENCE] This REST route shows none of the reasons a door may not be GraphQL: a route-level probe, auth handshake or signed webhook (`@Public({ reason: PublicReason.X })`), a byte transfer, an OAuth redirect or a declared public v1 operation table. A plain JSON read belongs in the GraphQL schema, where the client already is.",
         },
     },
     create(context) {
         hfsOf(context)
+        const declared = operationRouteEvidence(context)
         return {
             ClassDeclaration(node) {
                 const controller = (node.decorators ?? []).find((decorator) => isController(context, decorator))
-                if (controller && !showsReason(context, node)) context.report({ node: controller, messageId: "unjustified" })
+                if (!controller) return
+                for (const method of node.body.body) {
+                    if (method.type !== "MethodDefinition" || method.kind !== "method" || method.static) continue
+                    const route = (method.decorators ?? []).find((decorator) => isImportedFrom(context, decoratorCallee(decorator), "@nestjs/common", HTTP_ROUTES))
+                    if (route && !restExceptionEvidence(context, method) && !declared(method)) context.report({ node: route, messageId: "unjustified" })
+                }
             },
         }
     },