@starci/eslint-canon-fe 8.3.0 → 8.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/served-locale.mjs

@@ -14,7 +14,7 @@
  *
  * WHAT THEY CANNOT HOLD, stated rather than implied. Neither rule can tell whether the value the link
  * computes is CORRECT - whether it reads the address, the cookie or a constant - because that is
- * inside a function these rules only see the name of. A link that attaches `x-locale: "en"`
+ * inside a function these rules only see the name of. A link that attaches `Accept-Language: "en"`
  * unconditionally satisfies both and is wrong. That case is a review question and LOCALE-2 is where
  * it is argued; pretending otherwise would be the rule claiming a guarantee it does not have.
  *
@@ -73,8 +73,11 @@ const isLocaleLinkFile = (context) => {
  */
 const isLinkImplementationFile = (context) => linkFileName(context) !== null
 
-/** The header a request declares its language in (HTTP header names are case-insensitive: `X-Locale` is the same header). */
-export const LOCALE_HEADER = "x-locale"
+/** The header a request declares its language in; HTTP header names are case-insensitive. */
+export const LOCALE_HEADER = "Accept-Language"
+
+/** The retired locale header is refused everywhere, including the locale link. */
+const RETIRED_LOCALE_HEADER = "x-locale"
 
 /** Callee names that construct the terminal link - the one that actually reaches the network. */
 const TERMINAL_LINK_CALLEES = new Set(["createHttpLink", "HttpLink", "createUploadLink", "BatchHttpLink"])
@@ -93,16 +96,59 @@ const calleeName = (node) => {
   return null
 }
 
-/** Every string-ish key a property can carry, so `"x-locale"` and `["x-locale"]` read the same. */
+/** Literal and expression-free template spellings identify the same header. */
+const stringOf = (node) => {
+  if (node?.type === "Literal" && typeof node.value === "string") return node.value
+  if (node?.type === "TemplateLiteral" && node.expressions.length === 0) return node.quasis[0].value.cooked
+  return null
+}
+
+/** Every static property spelling, without treating a computed variable as its identifier's name. */
+const keyOf = (node) => node?.property?.type === "Identifier" && !node.computed ? node.property.name : stringOf(node?.property)
+
+/** Every string-ish key a property can carry, so `"Accept-Language"` and `["Accept-Language"]` read the same. */
 const propertyKeyOf = (property) => {
   if (!property || property.type !== "Property") return null
   const key = property.key
   if (!key) return null
   if (key.type === "Identifier" && !property.computed) return key.name
-  if (key.type === "Literal" && typeof key.value === "string") return key.value
+  return stringOf(key)
+}
+
+/** Resolve a receiver's binding, so an unrelated local `Headers` or `set` method stays unrelated. */
+const variableOf = (node, sourceCode) => {
+  for (let scope = sourceCode.getScope(node); scope; scope = scope.upper) {
+    const variable = scope.set.get(node.name)
+    if (variable) return variable
+  }
   return null
 }
 
+/** Global browser constructors and globals may be qualified, but cannot be shadowed. */
+const isNativeName = (node, name, sourceCode) => {
+  if (node?.type === "Identifier") return node.name === name && !variableOf(node, sourceCode)?.defs.length
+  return node?.type === "MemberExpression" && keyOf(node) === name &&
+    ["globalThis", "window"].some((global) => isNativeName(node.object, global, sourceCode))
+}
+
+/** Syntax establishes native Headers values and stable aliases; unknown or reassigned receivers are left alone. */
+const isNativeInstance = (node, name, sourceCode, seen = new Set()) => {
+  if (!node || seen.has(node)) return false
+  seen.add(node)
+  const annotation = node.typeAnnotation?.typeAnnotation ?? node.typeAnnotation
+  if (annotation?.type === "TSTypeReference" && isNativeName(annotation.typeName, name, sourceCode)) return true
+  if (["TSAsExpression", "TSNonNullExpression", "ChainExpression"].includes(node.type)) return isNativeInstance(node.expression, name, sourceCode, seen)
+  if (node.type === "NewExpression") return isNativeName(node.callee, name, sourceCode)
+  if (name === "Headers" && node.type === "MemberExpression" && keyOf(node) === "headers") {
+    return ["Request", "Response"].some((owner) => isNativeInstance(node.object, owner, sourceCode, new Set(seen)))
+  }
+  if (node.type !== "Identifier") return false
+  const variable = variableOf(node, sourceCode)
+  if (variable?.references.some((reference) => reference.isWrite() && !reference.init)) return false
+  return (variable?.identifiers ?? []).some((identifier) => isNativeInstance(identifier, name, sourceCode, seen)) ||
+    (variable?.defs ?? []).some((definition) => definition.type === "Variable" && isNativeInstance(definition.node.init, name, sourceCode, seen))
+}
+
 export const rules = {
   "api-client-attaches-the-locale": {
     meta: {
@@ -152,15 +198,40 @@ export const rules = {
       schema: [],
       messages: {
         elsewhere:
-          "Only the locale link may write `x-locale`. Setting it here is a second answer to which language this request is in, and the two diverge the first time one of them is updated - usually leaving a single hook correct and the rest of the surface on the server's default. Let the transport attach it.",
+          "Only the locale link may write `Accept-Language`. Setting it here is a second answer to which language this request is in, and the two diverge the first time one of them is updated - usually leaving a single hook correct and the rest of the surface on the server's default. Let the transport attach it.",
+        retired:
+          "The `x-locale` header is retired. Declare the reader's language with `Accept-Language` in the locale link, the one place that owns it.",
       },
     },
     create(context) {
-      if (isLocaleLinkFile(context)) return {}
+      const ownsLocale = isLocaleLinkFile(context)
+      const sourceCode = context.sourceCode ?? context.getSourceCode()
+      const checkHeader = (node, key) => {
+        const header = key?.toLowerCase()
+        if (header === RETIRED_LOCALE_HEADER) {
+          context.report({ node, messageId: "retired" })
+        } else if (header === LOCALE_HEADER.toLowerCase() && !ownsLocale) {
+          context.report({ node, messageId: "elsewhere" })
+        }
+      }
       return {
         Property(node) {
-          if (propertyKeyOf(node)?.toLowerCase() === LOCALE_HEADER) {
-            context.report({ node, messageId: "elsewhere" })
+          checkHeader(node, propertyKeyOf(node))
+        },
+        AssignmentExpression(node) {
+          if (node.left.type === "MemberExpression") checkHeader(node, keyOf(node.left))
+        },
+        NewExpression(node) {
+          const initial = node.arguments[0]
+          if (!isNativeName(node.callee, "Headers", sourceCode) || initial?.type !== "ArrayExpression") return
+          for (const entry of initial.elements) {
+            if (entry?.type === "ArrayExpression") checkHeader(entry, stringOf(entry.elements[0]))
+          }
+        },
+        CallExpression(node) {
+          const callee = node.callee
+          if (callee.type === "MemberExpression" && ["set", "append"].includes(keyOf(callee)) && isNativeInstance(callee.object, "Headers", sourceCode)) {
+            checkHeader(node, stringOf(node.arguments[0]))
           }
         },
       }

package/size-growth.mjs

@@ -4,8 +4,9 @@
  * A source file has a hard-growth budget of `fileLines.soft` lines while `fileLines.hardGrowth` holds
  * (`ruleParams.fe.fileLines` of the slot manifest, read through the slot view `hfsOf(context).ruleParams`). `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 as it is; it may not grow, and it may not be born large. The rule
+ * is longer than its recorded size. The recorded size is the line count at `merge-base HEAD <base>`
+ * (STARCI_BASE_REF, origin/main, then main); only staged lint text in a commit hook uses 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.
  *
  * There is no baseline file and no allowlist: the record is the repository's own history. A declaration file (`*.d.ts`) carries no behaviour and is not governed. Component,
@@ -27,7 +28,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) {
@@ -36,11 +38,13 @@ export const fileSizeGrowth = {
     const max = hardGrowthLines(hfsOf(context).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 } })
       },
     }