@starci/hfs 4.7.7 → 4.7.8

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.7.8 - 2026-10-19
+- Fixed: catalog usage follows ordered object and JSX spreads, readonly class translator fields and their declared forwarding methods while unknown or overwritten producers remain barriers.
+- Fixed: strict-null narrowing retains initializer provenance only for an unmodified const reference; destructuring writes and ancestor replacements invalidate the proof across the containing evaluation frame.
+- Fixed: finite template catalog keys resolve from bounded tuple and callback values, with unknown spans and excessive products rejected; a proven catalog leaf consumes only its same-bundle locale siblings.
+
 ## 4.7.7 - 2026-10-19
 - Changed: bundled canon pins follow the front-end canon's module classification correction in 8.4.13; HFS command behavior is unchanged.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.7",
+  "version": "4.7.8",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.13
+    version: 3.4.14
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.13
+    version: 8.4.14
     group: starci
     install: registry
     side: fe
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.7
+    version: 1.7.8
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.7
+    version: 4.7.8
     group: starci
     install: registry
     side: both

package/runtime/scripts/hfs/rules/unused-symbol-flow.mjs

@@ -2,52 +2,110 @@
 // followed through variables, parameters (state.arguments), array callbacks, for-of and literal tables.
 import { nameText as nameOf } from '../../lib/ts-ast.mjs';
 import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
+import { excludesNull, propertiesOf, propertyValues, writesTarget } from './unused-symbol-properties.mjs';
 
 const ARRAY_CALLBACK = /^(?:map|flatMap|forEach|filter|find|some|every)$/u;
 
+/** A forwarded parameter must retain its value, including in a conditional guard. */
+export function writesBinding(state, node, symbol) {
+  return writesTarget(state, node, target => state.ts.isIdentifier(target) && state.checker.getSymbolAtLocation(target) === symbol);
+}
+
 export const symbolAt = (state, node) => {
   const symbol = state.ts.isShorthandPropertyAssignment(node.parent) && node.parent.name === node
     ? state.checker.getShorthandAssignmentValueSymbol(node.parent) : state.checker.getSymbolAtLocation(node);
   return symbol?.flags === state.ts.SymbolFlags.Alias ? state.checker.getAliasedSymbol(symbol) : symbol;
 };
 
-/** The expression bound to `name` in an object literal or a JSX attribute list. */
-function propertyValues(state, owner, name) {
+/** Only a declared, unmodified class method or readonly field supplies instance-member provenance. */
+function classMemberValue(state, declaration) {
   const { ts } = state;
-  if (ts.isObjectLiteralExpression(owner)) return owner.properties.filter(entry => (ts.isPropertyAssignment(entry) || ts.isShorthandPropertyAssignment(entry)) && nameOf(ts, entry.name) === name).map(entry => ts.isShorthandPropertyAssignment(entry) ? entry.name : entry.initializer);
-  if (!ts.isJsxAttributes(owner)) return [];
-  const attributes = owner.properties.filter(entry => ts.isJsxAttribute(entry) && entry.name.text === name && entry.initializer);
-  return attributes.map(entry => ts.isJsxExpression(entry.initializer) ? entry.initializer.expression : entry.initializer).filter(Boolean);
+  if (!declaration || !ts.isClassLike(declaration.parent)) return null;
+  const field = ts.isPropertyDeclaration(declaration);
+  if (!ts.isMethodDeclaration(declaration) && (!field || !declaration.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ReadonlyKeyword))) return null;
+  const mutations = state.memberMutations ??= new Map();
+  if (!mutations.has(declaration)) mutations.set(declaration, [...(state.flowSources?.values() ?? [declaration.getSourceFile()])]
+    .some(source => writesTarget(state, source, target => symbolAt(state, target)?.valueDeclaration === declaration)));
+  if (mutations.get(declaration)) return null;
+  return field ? unwrap(ts, declaration.initializer) : declaration;
 }
 
-/** `TABLE[key]`: the entry of a literal key, else every value of the table (any of them can be read). */
-function tableValues(state, node, seen) {
+/** Local callable declarations and supported class fields share the same declaration resolution. */
+export function callableValue(state, node) {
+  const declaration = symbolAt(state, node)?.valueDeclaration;
+  if (!declaration) return null;
+  if (state.ts.isVariableDeclaration(declaration)) return unwrap(state.ts, declaration.initializer);
+  return state.ts.isClassLike(declaration.parent) ? classMemberValue(state, declaration) : declaration;
+}
+
+/** Selected initializers retain their declaration identity for exact catalog consumption. */
+export function propertyInitializers(state, expression, name) {
+  return propertiesOf(state, valuesOf(state, expression), name, new Set(), valuesOf);
+}
+
+function tableOwnerValues(state, owner, literal, seen) {
   const { ts } = state;
-  const literal = ts.isStringLiteralLike(node.argumentExpression) ? node.argumentExpression.text : null;
-  return valuesOf(state, node.expression, seen).flatMap(owner => {
-    if (ts.isArrayLiteralExpression(owner)) return [...owner.elements];
-    if (!ts.isObjectLiteralExpression(owner)) return [];
-    if (literal !== null) return propertyValues(state, owner, literal);
-    return owner.properties.filter(entry => ts.isPropertyAssignment(entry)).map(entry => entry.initializer);
-  });
+  if (ts.isArrayLiteralExpression(owner)) return [...owner.elements];
+  if (!ts.isObjectLiteralExpression(owner)) return [];
+  if (literal !== null) return propertyValues(state, owner, literal, seen, valuesOf);
+  // A dynamic selection from a table with spread or computed members has unknown provenance.
+  if (owner.properties.some(entry => !ts.isPropertyAssignment(entry) || nameOf(ts, entry.name, { numbers: true }) === null)) return [];
+  return owner.properties.map(entry => entry.initializer);
+}
+
+/** A literal table key selects its property; a dynamic key admits only a completely known table. */
+function tableValues(state, node, seen) {
+  const literal = nameOf(state.ts, node.argumentExpression, { identifiers: false, numbers: true });
+  const groups = valuesOf(state, node.expression, seen).map(owner => tableOwnerValues(state, owner, literal, seen));
+  return groups.length && groups.every(group => group.length) ? groups.flat() : [];
 }
 
 const resolveAll = (state, nodes, seen) => nodes.flatMap(node => valuesOf(state, node, seen));
 
 function elementsOf(state, expression, seen) {
-  return valuesOf(state, expression, seen).flatMap(owner => state.ts.isArrayLiteralExpression(owner) ? [...owner.elements] : []);
+  const owners = valuesOf(state, expression, seen);
+  if (owners.some(owner => !state.ts.isArrayLiteralExpression(owner))) return [];
+  return owners.flatMap(owner => [...owner.elements]);
 }
 
-function parameterValues(state, declaration, seen) {
+const parameterKey = (state, declaration) => state.ts.isIdentifier(declaration.name)
+  ? state.checker.getSymbolAtLocation(declaration.name) : declaration;
+
+/** A recognized array callback binds its first parameter even when its collection values are unknown. */
+function arrayCallbackSource(state, declaration) {
   const { ts } = state;
   const callback = declaration.parent;
   const call = callback.parent;
-  if (ts.isCallExpression(call) && call.arguments[0] === callback && callback.parameters[0] === declaration
-    && ts.isPropertyAccessExpression(call.expression) && ARRAY_CALLBACK.test(call.expression.name.text)) {
-    return resolveAll(state, elementsOf(state, call.expression.expression, seen), seen);
-  }
-  const key = ts.isIdentifier(declaration.name) ? state.checker.getSymbolAtLocation(declaration.name) : declaration;
-  return resolveAll(state, state.arguments.get(key) ?? [], seen);
+  if (!ts.isCallExpression(call) || call.arguments[0] !== callback || callback.parameters[0] !== declaration) return null;
+  const expression = call.expression;
+  return ts.isPropertyAccessExpression(expression) && ARRAY_CALLBACK.test(expression.name.text) ? expression.expression : null;
+}
+
+function parameterValues(state, declaration, seen) {
+  const collection = arrayCallbackSource(state, declaration);
+  if (collection) return resolveAll(state, elementsOf(state, collection, seen), seen);
+  return resolveAll(state, state.arguments.get(parameterKey(state, declaration)) ?? [], seen);
+}
+
+function declarationEvidence(state, declaration) {
+  if (!declaration) return false;
+  if (state.ts.isParameter(declaration))
+    return state.arguments.has(parameterKey(state, declaration)) || arrayCallbackSource(state, declaration) !== null;
+  if (!state.ts.isVariableDeclaration(declaration)) return false;
+  const loop = declaration.parent?.parent;
+  return Boolean(declaration.initializer) || Boolean(loop && state.ts.isForOfStatement(loop));
+}
+
+/** Separate unbound generic receivers from receivers whose observed producers failed namespace resolution. */
+export function receiverBinding(state, expression) {
+  const { ts } = state;
+  let root = unwrap(ts, expression);
+  while (root && (ts.isPropertyAccessExpression(root) || ts.isElementAccessExpression(root))) root = unwrap(ts, root.expression);
+  const declaration = root && ts.isIdentifier(root) ? symbolAt(state, root)?.valueDeclaration : null;
+  const handedIn = Boolean(declaration) && (ts.isParameter(declaration) || ts.isBindingElement(declaration));
+  let owner = declaration;
+  while (owner && ts.isBindingElement(owner)) owner = owner.parent?.parent;
+  return { handedIn, observed: declarationEvidence(state, owner) };
 }
 
 function bindingValues(state, declaration, seen) {
@@ -57,10 +115,11 @@ function bindingValues(state, declaration, seen) {
   const owners = declarationValues(state, pattern.parent, seen);
   if (ts.isObjectBindingPattern(pattern)) {
     const name = nameOf(ts, declaration.propertyName ?? declaration.name);
-    return resolveAll(state, owners.flatMap(owner => propertyValues(state, owner, name)), seen);
+    return resolveAll(state, propertiesOf(state, owners, name, seen, valuesOf), seen);
   }
   const index = pattern.elements.indexOf(declaration);
-  return resolveAll(state, owners.flatMap(owner => ts.isArrayLiteralExpression(owner) && owner.elements[index] ? [owner.elements[index]] : []), seen);
+  if (owners.some(owner => !ts.isArrayLiteralExpression(owner) || !owner.elements[index])) return [];
+  return resolveAll(state, owners.map(owner => owner.elements[index]), seen);
 }
 
 function declarationValues(state, declaration, seen) {
@@ -76,11 +135,10 @@ function declarationValues(state, declaration, seen) {
 /** Resolve local function and memo callback returns; an unknown call remains its own leaf. */
 function callValues(state, node, seen) {
   const { ts } = state;
-  const declaration = symbolAt(state, node.expression)?.valueDeclaration;
-  const target = declaration && ts.isVariableDeclaration(declaration) ? unwrap(ts, declaration.initializer) : declaration;
+  const target = callableValue(state, node.expression);
   const memo = ts.isIdentifier(node.expression) && node.expression.text === 'useMemo' ? unwrap(ts, node.arguments[0]) : null;
   const fn = memo ?? target;
-  return fn && (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn) || ts.isFunctionDeclaration(fn))
+  return fn && (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn) || ts.isFunctionDeclaration(fn) || ts.isMethodDeclaration(fn))
     ? resolveAll(state, returnedExpressions(ts, fn), seen) : [node];
 }
 
@@ -88,16 +146,24 @@ function callValues(state, node, seen) {
 export function valuesOf(state, expression, visited = new Set()) {
   const { ts } = state;
   const node = unwrap(ts, expression);
-  if (!node || visited.has(node)) return [];
+  if (!node) return [];
+  if (visited.has(node)) return [node];
   const seen = new Set([...visited, node]);
+  const orLeaf = values => values.length ? values : [node];
+  const narrowed = values => orLeaf(excludesNull(state, node) ? values.filter(value => value.kind !== ts.SyntaxKind.NullKeyword) : values);
   if (ts.isConditionalExpression(node)) return [...valuesOf(state, node.whenTrue, seen), ...valuesOf(state, node.whenFalse, seen)];
-  if (ts.isCallExpression(node)) return callValues(state, node, seen);
-  if (ts.isPropertyAccessExpression(node)) return resolveAll(state, valuesOf(state, node.expression, seen).flatMap(owner => propertyValues(state, owner, node.name.text)), seen);
-  if (ts.isElementAccessExpression(node)) return resolveAll(state, tableValues(state, node, seen), seen);
+  if (ts.isCallExpression(node)) return orLeaf(callValues(state, node, seen));
+  if (ts.isPropertyAccessExpression(node)) {
+    const member = classMemberValue(state, symbolAt(state, node)?.valueDeclaration);
+    if (member) return [member];
+  }
+  if (ts.isPropertyAccessExpression(node)) return narrowed(resolveAll(state, propertiesOf(state, valuesOf(state, node.expression, seen), node.name.text, seen, valuesOf), seen));
+  if (ts.isElementAccessExpression(node)) return orLeaf(resolveAll(state, tableValues(state, node, seen), seen));
   if (!ts.isIdentifier(node)) return [node];
   const symbol = symbolAt(state, node);
   if (!symbol?.valueDeclaration || state.translators.has(symbol)) return [node];
-  return declarationValues(state, symbol.valueDeclaration, seen);
+  const values = declarationValues(state, symbol.valueDeclaration, seen);
+  return narrowed(values);
 }
 
 /** The expressions a function returns: its expression body, or the operand of each return outside nested functions. */

package/runtime/scripts/hfs/rules/unused-symbol-properties.mjs

@@ -0,0 +1,162 @@
+// Ordered object and JSX property provenance for R280; unknown writers remain barriers.
+import { nameText } from '../../lib/ts-ast.mjs';
+import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
+
+const ABSENT_PROPERTY = { values: [], missing: true };
+
+/** A definite write replaces earlier provenance; a missing branch keeps it, and an unknown branch is a barrier. */
+function mergeProperty(before, after) {
+  if (after === null || !after.missing) return after;
+  if (before === null) return null;
+  return { values: [...before.values, ...after.values], missing: before.missing };
+}
+
+/** Every possible spread owner must be known before its property provenance is admitted. */
+function spreadProperty(state, expression, name, seen, resolve) {
+  const choices = resolve(state, expression, seen).map(owner => ownerProperty(state, owner, name, seen, resolve));
+  if (!choices.length || choices.some(choice => choice === null)) return null;
+  return { values: choices.flatMap(choice => choice.values), missing: choices.some(choice => choice.missing) };
+}
+
+function entryProperty(state, entry, name, seen, resolve) {
+  const { ts } = state;
+  if (ts.isSpreadAssignment(entry) || ts.isJsxSpreadAttribute(entry)) return spreadProperty(state, entry.expression, name, seen, resolve);
+  const key = nameText(ts, entry.name, { numbers: true });
+  if (key === null) return null;
+  if (key !== name) return ABSENT_PROPERTY;
+  if (ts.isPropertyAssignment(entry)) return { values: [entry.initializer], missing: false };
+  if (ts.isShorthandPropertyAssignment(entry)) return { values: [entry.name], missing: false };
+  if (ts.isJsxAttribute(entry)) {
+    const value = entry.initializer && (ts.isJsxExpression(entry.initializer) ? entry.initializer.expression : entry.initializer);
+    return value ? { values: [value], missing: false } : null;
+  }
+  // A method or accessor owns the name, but does not establish a supported translator value.
+  return null;
+}
+
+/** Fold writes in source order, with branch-local cycle detection and explicit absence. */
+function ownerProperty(state, owner, name, visited, resolve) {
+  if ((!state.ts.isObjectLiteralExpression(owner) && !state.ts.isJsxAttributes(owner)) || visited.has(owner)) return null;
+  const seen = new Set([...visited, owner]);
+  return owner.properties.reduce((before, entry) => mergeProperty(before, entryProperty(state, entry, name, seen, resolve)), ABSENT_PROPERTY);
+}
+
+/** The expression bound to name in a known object literal or a JSX attribute list. */
+export function propertyValues(state, owner, name, seen, resolve) {
+  const property = ownerProperty(state, owner, name, seen, resolve);
+  return property && !property.missing ? property.values : [];
+}
+
+/** Unknown or missing owner branches cannot disappear beside a known property branch. */
+export function propertiesOf(state, owners, name, seen, resolve) {
+  const groups = owners.map(owner => propertyValues(state, owner, name, seen, resolve));
+  return groups.length && groups.every(group => group.length) ? groups.flat() : [];
+}
+
+function returnsAbruptly(ts, statement) {
+  const own = ts.isBlock(statement) && statement.statements.length === 1 ? statement.statements[0] : statement;
+  return ts.isReturnStatement(own) || ts.isThrowStatement(own);
+}
+
+function sameReference(state, left, right) {
+  const { ts, checker } = state;
+  const a = unwrap(ts, left), b = unwrap(ts, right);
+  if (!a || !b) return false;
+  if (ts.isIdentifier(a) && ts.isIdentifier(b)) return checker.getSymbolAtLocation(a) === checker.getSymbolAtLocation(b);
+  return ts.isPropertyAccessExpression(a) && ts.isPropertyAccessExpression(b)
+    && a.name.text === b.name.text && sameReference(state, a.expression, b.expression);
+}
+
+function comparesNull(state, expression, reference, negative = false) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  const operator = negative ? ts.SyntaxKind.ExclamationEqualsEqualsToken : ts.SyntaxKind.EqualsEqualsEqualsToken;
+  if (!node || !ts.isBinaryExpression(node) || node.operatorToken.kind !== operator) return false;
+  return [[node.left, node.right], [node.right, node.left]].some(([value, nil]) =>
+    nil.kind === ts.SyntaxKind.NullKeyword && sameReference(state, value, reference));
+}
+
+function immutableReference(state, expression) {
+  const { ts } = state;
+  let root = unwrap(ts, expression);
+  while (root && ts.isPropertyAccessExpression(root)) root = root.expression;
+  if (!root || !ts.isIdentifier(root)) return false;
+  let declaration = state.checker.getSymbolAtLocation(root)?.valueDeclaration;
+  while (declaration && ts.isBindingElement(declaration)) declaration = declaration.parent.parent;
+  return Boolean(declaration && ts.isVariableDeclaration(declaration) && (declaration.parent.flags & ts.NodeFlags.Const));
+}
+
+function assignmentTarget(state, expression, matches) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  if (!node) return false;
+  if (matches(node)) return true;
+  if (ts.isArrayLiteralExpression(node)) return node.elements.some(element => assignmentTarget(state, element, matches));
+  if (ts.isObjectLiteralExpression(node)) return node.properties.some(entry => assignmentTarget(state,
+    ts.isShorthandPropertyAssignment(entry) ? entry.name : entry.initializer ?? entry.expression, matches));
+  if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) return assignmentTarget(state, node.left, matches);
+  return (ts.isSpreadElement(node) || ts.isSpreadAssignment(node)) && assignmentTarget(state, node.expression, matches);
+}
+
+/** All assignment forms share one target traversal; each consumer owns the reference it invalidates. */
+export function writesTarget(state, node, matches) {
+  const { ts } = state;
+  let written = false;
+  const visit = own => {
+    const assignment = ts.isBinaryExpression(own) && own.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && own.operatorToken.kind <= ts.SyntaxKind.LastAssignment;
+    const unary = (ts.isPrefixUnaryExpression(own) || ts.isPostfixUnaryExpression(own)) && [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(own.operator);
+    if ((assignment && assignmentTarget(state, own.left, matches)) || (unary && assignmentTarget(state, own.operand, matches))
+      || ((ts.isForOfStatement(own) || ts.isForInStatement(own)) && assignmentTarget(state, own.initializer, matches))) written = true;
+    if (!written) ts.forEachChild(own, visit);
+  };
+  if (node) visit(node);
+  return written;
+}
+
+function writesReference(state, node, reference) {
+  return writesTarget(state, node, target => {
+    for (let own = unwrap(state.ts, reference); own; own = state.ts.isPropertyAccessExpression(own) ? unwrap(state.ts, own.expression) : null) {
+      if (sameReference(state, target, own)) return true;
+    }
+    return false;
+  });
+}
+
+function priorReferenceWrite(state, node) {
+  const { ts } = state;
+  for (let child = node; child.parent; child = child.parent) {
+    const parent = child.parent;
+    if (ts.isClassLike(parent)) break;
+    if (ts.isFunctionLike(parent)) return !ts.isBlock(child) && writesReference(state, child, node);
+    if (ts.isBlock(parent) && parent.statements.slice(0, parent.statements.indexOf(child) + 1).some(statement => writesReference(state, statement, node))) return true;
+  }
+  return false;
+}
+
+function conditionalExcludesNull(state, node) {
+  const { ts } = state;
+  for (let child = node; child.parent; child = child.parent) {
+    const parent = child.parent;
+    if (ts.isFunctionLike(parent) || ts.isClassLike(parent)) return false;
+    if (ts.isConditionalExpression(parent) && child !== parent.condition
+      && comparesNull(state, parent.condition, node, child === parent.whenTrue) && !writesReference(state, parent, node)) return true;
+  }
+  return false;
+}
+
+/** Strict-null guards narrow only an immutable reference at its actual guarded use site. */
+export function excludesNull(state, node) {
+  const { ts } = state;
+  if (!immutableReference(state, node) || priorReferenceWrite(state, node)) return false;
+  if (conditionalExcludesNull(state, node)) return true;
+  if (!ts.isIdentifier(node)) return false;
+  let statement = node;
+  while (statement.parent && !ts.isBlock(statement.parent)) {
+    if (ts.isFunctionLike(statement.parent) || ts.isClassLike(statement.parent)) return false;
+    statement = statement.parent;
+  }
+  if (!statement.parent || !ts.isBlock(statement.parent)) return false;
+  const previous = statement.parent.statements.slice(0, statement.parent.statements.indexOf(statement));
+  return previous.some(guard => ts.isIfStatement(guard) && !guard.elseStatement
+    && comparesNull(state, guard.expression, node) && returnsAbruptly(ts, guard.thenStatement));
+}

package/runtime/scripts/hfs/rules/unused-symbol-translators.mjs

@@ -2,17 +2,20 @@
 import { nameText } from '../../lib/ts-ast.mjs';
 import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
 import { callable, staticStrings } from './unused-symbol-values.mjs';
-import { returnedExpressions, symbolAt, valuesOf } from './unused-symbol-flow.mjs';
+import { receiverBinding, returnedExpressions, symbolAt, valuesOf, writesBinding } from './unused-symbol-flow.mjs';
 
 const TRANSLATOR_NAME = /^(?:t|translate)$/u;
 
-function translationFactories(ts, source) {
-  const factories = new Set(['useTranslations', 'getTranslations']);
+function translationFactories(state, source) {
+  const { ts, checker } = state;
+  const factories = new Map(['useTranslations', 'getTranslations'].map(name => [name, {}]));
   for (const statement of source.statements) {
-    if (!ts.isImportDeclaration(statement) || !/^(?:next-intl|next-intl\/server)$/u.test(statement.moduleSpecifier.text)) continue;
+    if (!ts.isImportDeclaration(statement) || !/^(?:next-intl(?:\/server)?|use-intl\/core)$/u.test(statement.moduleSpecifier.text)) continue;
     const named = statement.importClause?.namedBindings;
     if (named && ts.isNamedImports(named)) for (const element of named.elements) {
-      if (factories.has((element.propertyName ?? element.name).text)) factories.add(element.name.text);
+      const name = (element.propertyName ?? element.name).text;
+      if (/^(?:useTranslations|getTranslations|createTranslator)$/u.test(name))
+        factories.set(element.name.text, { options: name === 'createTranslator', symbol: checker.getSymbolAtLocation(element.name) });
     }
   }
   return factories;
@@ -23,8 +26,14 @@ function translatorNamespace(state, initializer, factories) {
   let init = unwrap(ts, initializer);
   if (init && ts.isAwaitExpression(init)) init = unwrap(ts, init.expression);
   if (!init || !ts.isCallExpression(init) || !ts.isIdentifier(init.expression) || !factories.has(init.expression.text)) return null;
+  const factory = factories.get(init.expression.text);
+  if (factory.symbol && state.checker.getSymbolAtLocation(init.expression) !== factory.symbol) return null;
   let first = init.arguments[0];
-  if (first && ts.isObjectLiteralExpression(first)) first = first.properties.find(property => nameText(ts, property.name, { numbers: true }) === 'namespace')?.initializer;
+  if (factory.options && (!first || !ts.isObjectLiteralExpression(first))) return [];
+  if (first && ts.isObjectLiteralExpression(first)) {
+    if (first.properties.some(property => ts.isSpreadAssignment(property) || nameText(ts, property.name, { numbers: true }) === null)) return [];
+    first = first.properties.findLast(property => nameText(ts, property.name, { numbers: true }) === 'namespace')?.initializer;
+  }
   return first ? staticStrings(state, first) : [''];
 }
 
@@ -36,7 +45,23 @@ function translatorList(ts, initializer) {
   return list && ts.isArrayLiteralExpression(list) ? list.elements : [];
 }
 
-const isFunction = (ts, node) => Boolean(node) && (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node));
+const isFunction = (ts, node) => ts.isFunctionLike(node)
+  && (ts.isExpression(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node));
+
+/** A branch may forward the same key or return it unchanged; an unrelated result proves no translator. */
+function forwardedExpression(state, expression, parameter) {
+  const { ts, checker } = state;
+  const node = unwrap(ts, expression);
+  if (node && ts.isIdentifier(node) && checker.getSymbolAtLocation(node) === parameter) return [];
+  if (node && ts.isConditionalExpression(node)) {
+    const choices = [node.whenTrue, node.whenFalse].map(branch => forwardedExpression(state, branch, parameter));
+    return choices.every(choice => choice !== null) ? choices.flat() : null;
+  }
+  const first = node && ts.isCallExpression(node) ? unwrap(ts, node.arguments[0]) : null;
+  if (!first || !ts.isIdentifier(first) || checker.getSymbolAtLocation(first) !== parameter) return null;
+  const namespaces = receiverNamespaces(state, node.expression);
+  return namespaces.length ? namespaces : null;
+}
 
 /** A function whose result is a call on a bound translator with its own first parameter is that translator. */
 function forwardedNamespaces(state, fn) {
@@ -44,12 +69,9 @@ function forwardedNamespaces(state, fn) {
   const parameter = fn.parameters[0];
   if (!parameter || !ts.isIdentifier(parameter.name)) return [];
   const own = checker.getSymbolAtLocation(parameter.name);
-  return returnedExpressions(ts, fn).flatMap(expression => {
-    const call = unwrap(ts, expression);
-    const first = call && ts.isCallExpression(call) ? unwrap(ts, call.arguments[0]) : null;
-    if (!first || !ts.isIdentifier(first) || checker.getSymbolAtLocation(first) !== own) return [];
-    return receiverNamespaces(state, call.expression);
-  });
+  if (writesBinding(state, fn.body, own)) return [];
+  const choices = returnedExpressions(ts, fn).map(expression => forwardedExpression(state, expression, own));
+  return choices.every(choice => choice !== null) ? choices.flat() : [];
 }
 
 /** useCallback(fn, deps) and useMemo(() => fn, deps) are the function fn. */
@@ -96,7 +118,7 @@ function bindTranslator(state, name, initializer, factories) {
 
 /** Wrappers depend on translators bound in other modules, so bind until nothing new appears. */
 export function translationBindings(state, sources) {
-  const factories = new Map([...sources.values()].map(source => [source, translationFactories(state.ts, source)]));
+  const factories = new Map([...sources.values()].map(source => [source, translationFactories(state, source)]));
   for (let pass = 0, size = -1; pass < 4 && size !== state.translators.size; pass++) {
     size = state.translators.size;
     for (const source of sources.values()) {
@@ -112,6 +134,7 @@ export function translationBindings(state, sources) {
 /** Namespaces of the translators a receiver can be: declared here, or handed in through arguments and props. */
 function receiverNamespaces(state, receiver) {
   const { ts, checker } = state;
+  if (explicitCatalogGet(ts, receiver)) return [''];
   const resolving = state.resolvingReceivers ??= new Set();
   if (resolving.has(receiver)) return [];
   resolving.add(receiver);
@@ -120,26 +143,25 @@ function receiverNamespaces(state, receiver) {
     if (direct !== undefined) return direct;
     return valuesOf(state, receiver).flatMap(leaf => {
       // A translator factory called in place as an argument: f(useTranslations("admin")).
-      if (ts.isCallExpression(leaf)) return translatorNamespace(state, leaf, translationFactories(ts, leaf.getSourceFile())) ?? [];
+      if (ts.isCallExpression(leaf)) return translatorNamespace(state, leaf, translationFactories(state, leaf.getSourceFile())) ?? [];
       if (isFunction(ts, leaf)) return forwardedNamespaces(state, leaf);
       return ts.isIdentifier(leaf) ? state.translators.get(symbolAt(state, leaf)) ?? [] : [];
     });
   } finally { resolving.delete(receiver); }
 }
 
-function handedIn(state, receiver) {
-  const { ts } = state;
-  let root = receiver;
-  while (ts.isPropertyAccessExpression(root)) root = root.expression;
-  const declaration = ts.isIdentifier(root) ? symbolAt(state, root)?.valueDeclaration : null;
-  return Boolean(declaration) && (ts.isParameter(declaration) || ts.isBindingElement(declaration));
-}
-
 function leafName(ts, node) {
   if (ts.isPropertyAccessExpression(node)) return node.name.text;
   return ts.isIdentifier(node) ? node.text : '';
 }
 
+function explicitCatalogGet(ts, callee) {
+  if (!ts.isPropertyAccessExpression(callee) || callee.name.text !== 'get') return false;
+  const owner = callee.expression;
+  const name = nameText(ts, ts.isPropertyAccessExpression(owner) ? owner.name : owner, { numbers: true }) ?? '';
+  return /message|catalog/iu.test(name);
+}
+
 /** A callback typed (string, ...) => string: the shape of a translator whatever its name. */
 function translatorShaped(state, receiver) {
   const { checker } = state;
@@ -160,12 +182,10 @@ export function catalogNamespace(state, callee) {
   if (ts.isPropertyAccessExpression(callee) && /^(?:rich|raw|markup)$/u.test(callee.name.text)) receiver = callee.expression;
   const resolved = receiverNamespaces(state, receiver);
   if (resolved.length) return resolved;
-  if (handedIn(state, receiver) && (TRANSLATOR_NAME.test(leafName(ts, receiver)) || translatorShaped(state, receiver))) return [null];
-  if (ts.isPropertyAccessExpression(callee) && callee.name.text === 'get') {
-    const owner = callee.expression;
-    const name = nameText(ts, ts.isPropertyAccessExpression(owner) ? owner.name : owner, { numbers: true }) ?? '';
-    if (/message|catalog/iu.test(name)) return [''];
-  }
-  if (ts.isIdentifier(callee) && TRANSLATOR_NAME.test(callee.text)) return [''];
+  const binding = receiverBinding(state, receiver);
+  // Observed unresolved producers cannot use the generic namespace fallback.
+  if (binding.handedIn && (TRANSLATOR_NAME.test(leafName(ts, receiver)) || translatorShaped(state, receiver)))
+    return binding.observed ? [] : [null];
+  if (ts.isIdentifier(callee) && TRANSLATOR_NAME.test(callee.text)) return binding.observed ? [] : [''];
   return [];
 }

package/runtime/scripts/hfs/rules/unused-symbol-values.mjs

@@ -1,14 +1,13 @@
 // Static values used at runtime by catalog consumers. A declaration alone is never a read.
 import path from 'node:path';
+import { nameText } from '../../lib/ts-ast.mjs';
 import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
-import { symbolAt, valuesOf } from './unused-symbol-flow.mjs';
+import { callableValue, propertyInitializers, symbolAt, valuesOf } from './unused-symbol-flow.mjs';
 
 const JSON_CATALOG = /(?:^|\/)(?:messages|locales)\/[^/]+\.json$|\.catalog\.json$/u;
 
 export function callable(state, node) {
-  const declaration = symbolAt(state, node)?.valueDeclaration;
-  if (declaration && state.ts.isVariableDeclaration(declaration)) return unwrap(state.ts, declaration.initializer);
-  return declaration;
+  return callableValue(state, node);
 }
 
 function bindArgument(state, parameter, argument) {
@@ -19,6 +18,7 @@ function bindArgument(state, parameter, argument) {
 
 /** Record the actual arguments of local functions, including imported functions and arrow exports. */
 export function argumentBindings(state, sources) {
+  state.flowSources = sources;
   for (const source of sources.values()) {
     const visit = node => {
       if (state.ts.isCallExpression(node)) {
@@ -40,22 +40,38 @@ function typeStrings(state, node) {
   return types.length && types.every(part => part.isStringLiteral()) ? types.map(part => part.value) : [];
 }
 
+const STATIC_CHOICE_LIMIT = 256;
+const STATIC_DEPTH_LIMIT = 64;
+const stringChoices = (groups, strict) => strict && groups.some(group => !group.length) ? [] : groups.flat();
+
+/** Expand only a finite product; an unknown span or an excessive product keeps the template opaque. */
+function templateStrings(state, node, seen) {
+  let choices = [node.head.text];
+  for (const span of node.templateSpans) {
+    const values = staticStrings(state, span.expression, seen, true);
+    if (!values.length || choices.length * values.length > STATIC_CHOICE_LIMIT) return [];
+    choices = choices.flatMap(prefix => values.map(value => prefix + value + span.literal.text));
+  }
+  return choices;
+}
+
 /** Follow finite literals only; a broad string or an unbounded dynamic expression gives no evidence. */
-export function staticStrings(state, expression, visited = new Set()) {
+export function staticStrings(state, expression, visited = new Set(), strict = false) {
   const { ts } = state;
   const node = unwrap(ts, expression);
-  if (!node || visited.has(node)) return [];
+  if (!node || visited.has(node) || visited.size >= STATIC_DEPTH_LIMIT) return [];
   const seen = new Set([...visited, node]);
   if (ts.isStringLiteralLike(node)) return [node.text];
-  if (ts.isConditionalExpression(node)) return [...staticStrings(state, node.whenTrue, seen), ...staticStrings(state, node.whenFalse, seen)];
+  if (ts.isTemplateExpression(node)) return templateStrings(state, node, seen);
+  if (ts.isConditionalExpression(node)) return stringChoices([node.whenTrue, node.whenFalse].map(branch => staticStrings(state, branch, seen, strict)), strict);
   const typed = typeStrings(state, node);
   if (typed.length) return typed;
   const declaration = symbolAt(state, node)?.valueDeclaration;
-  if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) return staticStrings(state, declaration.initializer, seen);
+  if (declaration && ts.isVariableDeclaration(declaration) && declaration.initializer) return staticStrings(state, declaration.initializer, seen, strict);
   const bound = declaration && ts.isParameter(declaration) ? state.arguments.get(symbolAt(state, node)) ?? [] : [];
-  if (bound.length) return bound.flatMap(argument => staticStrings(state, argument, seen));
+  if (bound.length) return stringChoices(bound.map(argument => staticStrings(state, argument, seen, strict)), strict);
   // Tables, tuples, nested maps, for-of and destructured elements resolve to the literals they hold.
-  return valuesOf(state, node, visited).flatMap(leaf => leaf === node ? [] : staticStrings(state, leaf, seen));
+  return stringChoices(valuesOf(state, node, visited).map(leaf => leaf === node ? [] : staticStrings(state, leaf, seen, strict)), strict);
 }
 
 /** JSON imports are catalog owners; their runtime member reads survive named aliases and re-exports. */
@@ -92,8 +108,55 @@ function catalogObjectPath(state, expression, seen = new Set()) {
   return declaration && ts.isVariableDeclaration(declaration) ? catalogObjectPath(state, declaration.initializer, seen) : null;
 }
 
+function initializersAt(state, root, keys) {
+  let owners = [root];
+  for (const key of keys) {
+    const groups = owners.map(owner => propertyInitializers(state, owner, key));
+    if (groups.some(group => !group.length)) return [];
+    owners = groups.flat();
+  }
+  return owners;
+}
+
+/** Locale siblings belong to the same authored bundle, never to unrelated catalogs with matching keys. */
+function localeInitializers(state, initializer) {
+  const { ts } = state;
+  const keys = [];
+  let property = initializer.parent;
+  while (property && ts.isPropertyAssignment(property) && ts.isObjectLiteralExpression(property.parent)) {
+    const key = nameText(ts, property.name, { numbers: true });
+    if (key === null) return [];
+    keys.unshift(key);
+    const locale = property.parent.parent;
+    if (ts.isPropertyAssignment(locale) && /^(?:vi|en)$/u.test(nameText(ts, locale.name) ?? '')
+      && ts.isObjectLiteralExpression(locale.parent) && ts.isVariableDeclaration(locale.parent.parent)) {
+      const groups = ['vi', 'en'].map(language => initializersAt(state, locale.parent, [language, ...keys]));
+      return groups.every(group => group.length) ? groups.flat() : [];
+    }
+    property = locale;
+  }
+  return [];
+}
+
+function consumeCandidate(state, initializer) {
+  const candidate = state.decls.get(initializer.parent);
+  if (candidate?.kind !== 'catalog key') return;
+  candidate.used = true;
+  for (const peer of localeInitializers(state, initializer)) {
+    const sibling = state.decls.get(peer.parent);
+    if (sibling?.kind === 'catalog key') sibling.used = true;
+  }
+}
+
+/** A real finite member read consumes the selected authored key and its proven same-bundle locale siblings. */
+function typedCatalogRead(state, node) {
+  const keys = state.ts.isPropertyAccessExpression(node) ? [node.name.text] : staticStrings(state, node.argumentExpression);
+  for (const key of keys) for (const initializer of propertyInitializers(state, node.expression, key)) consumeCandidate(state, initializer);
+}
+
 export function jsonCatalogRead(state, node) {
   if (!state.ts.isPropertyAccessExpression(node) && !state.ts.isElementAccessExpression(node)) return;
+  typedCatalogRead(state, node);
   const key = catalogObjectPath(state, node);
   if (key !== null) state.catalogReads.add(key.slice(0, -1));
   if (state.ts.isElementAccessExpression(node) && !state.ts.isStringLiteralLike(node.argumentExpression)) {