@starci/hfs 4.2.17 → 4.4.0

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

@@ -0,0 +1,101 @@
+// Value flow for R280: the expressions an identifier, property or destructured element can hold,
+// 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';
+
+const ARRAY_CALLBACK = /^(?:map|flatMap|forEach|filter|find|some|every)$/u;
+
+export const symbolAt = (state, node) => {
+  const symbol = 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) {
+  const { ts } = state;
+  if (ts.isObjectLiteralExpression(owner)) return owner.properties.filter(entry => ts.isPropertyAssignment(entry) && nameOf(ts, entry.name) === name).map(entry => 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);
+}
+
+/** `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) {
+  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);
+  });
+}
+
+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] : []);
+}
+
+function parameterValues(state, declaration, seen) {
+  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);
+}
+
+function bindingValues(state, declaration, seen) {
+  const { ts } = state;
+  const pattern = declaration.parent;
+  if (declaration.dotDotDotToken) return [];
+  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);
+  }
+  const index = pattern.elements.indexOf(declaration);
+  return resolveAll(state, owners.flatMap(owner => ts.isArrayLiteralExpression(owner) && owner.elements[index] ? [owner.elements[index]] : []), seen);
+}
+
+function declarationValues(state, declaration, seen) {
+  const { ts } = state;
+  if (ts.isParameter(declaration)) return parameterValues(state, declaration, seen);
+  if (ts.isBindingElement(declaration)) return bindingValues(state, declaration, seen);
+  if (!ts.isVariableDeclaration(declaration)) return [];
+  const loop = declaration.parent?.parent;
+  if (loop && ts.isForOfStatement(loop)) return resolveAll(state, elementsOf(state, loop.expression, seen), seen);
+  return declaration.initializer ? valuesOf(state, declaration.initializer, seen) : [];
+}
+
+/** Leaf expressions `expression` may evaluate to. A translator variable and any unresolvable expression is its own leaf. */
+export function valuesOf(state, expression, visited = new Set()) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  if (!node || visited.has(node)) return [];
+  const seen = new Set([...visited, node]);
+  if (ts.isConditionalExpression(node)) return [...valuesOf(state, node.whenTrue, seen), ...valuesOf(state, node.whenFalse, 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.isIdentifier(node)) return [node];
+  const symbol = symbolAt(state, node);
+  if (!symbol?.valueDeclaration || state.translators.has(symbol)) return [node];
+  return declarationValues(state, symbol.valueDeclaration, seen);
+}
+
+/** The expressions a function returns: its expression body, or the operand of each return outside nested functions. */
+export function returnedExpressions(ts, fn) {
+  if (!fn.body) return [];
+  if (!ts.isBlock(fn.body)) return [fn.body];
+  const found = [];
+  const visit = node => {
+    if (ts.isReturnStatement(node) && node.expression) found.push(node.expression);
+    if (!ts.isFunctionLike(node)) ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(fn.body, visit);
+  return found;
+}

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

@@ -0,0 +1,77 @@
+// R280 safety net: the app-owned ledger of catalog keys the detector cannot see.
+// A side (fe or be) declares them in <side>/i18n-dynamic-keys.yaml; a key the ledger names counts as read, a stale
+// or malformed ledger is itself an HFS_UNUSED_SYMBOL finding, so the ledger cannot rot.
+import { isPlainObject } from '../../../engine/plain-object.mjs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { found, readText } from './read.mjs';
+
+const LEDGER_FILE = 'i18n-dynamic-keys.yaml';
+export const LEDGER_SCHEMA = 'starci/i18n-dynamic-keys@1';
+const CODE = 'HFS_UNUSED_SYMBOL';
+const MATCHERS = ['key', 'prefix', 'suffix'];
+const FIELDS = new Set([...MATCHERS, 'reason']);
+const SIDES = new Set(['fe', 'be']);
+const text = value => typeof value === 'string' && value.trim() !== '';
+const describe = entry => `${entry.kind} ${JSON.stringify(entry.value)}`;
+
+/** The catalog namespace (the dotted path before the leaf; '' when none) and the leaf of a candidate name. */
+function splitCatalogName(name) {
+  const at = name.lastIndexOf('.');
+  return at < 0 ? { namespace: '', leaf: name } : { namespace: name.slice(0, at), leaf: name.slice(at + 1) };
+}
+
+const MATCH = { key: (leaf, value) => leaf === value, prefix: (leaf, value) => leaf.startsWith(value), suffix: (leaf, value) => leaf.endsWith(value) };
+const matches = (entry, leaf) => MATCH[entry.kind](leaf, entry.value);
+
+function entryProblem(entry) {
+  if (!isPlainObject(entry)) return 'is not a mapping';
+  const unknown = Object.keys(entry).filter(field => !FIELDS.has(field));
+  if (unknown.length) return `has unknown field ${unknown.map(field => JSON.stringify(field)).join(', ')} (allowed: key, prefix, suffix, reason)`;
+  const given = MATCHERS.filter(field => field in entry);
+  if (given.length !== 1) return `must have exactly one of key, prefix or suffix (has ${given.length ? given.join(' and ') : 'none'})`;
+  if (!text(entry[given[0]])) return `${given[0]} must be a non-empty string`;
+  if (!text(entry.reason)) return 'must have a non-empty string reason';
+  return null;
+}
+
+/** Parse the ledger text: `{ entries, problems }`; a problem is one precise message about the file's shape. */
+function parseLedger(source) {
+  let doc;
+  try { doc = parseYaml(source); } catch { return { entries: [], problems: ['is not valid YAML'] }; }
+  if (!isPlainObject(doc)) return { entries: [], problems: ['must be a mapping with schema and namespaces'] };
+  const problems = [];
+  for (const field of Object.keys(doc)) if (!['schema', 'namespaces'].includes(field)) problems.push(`has unknown top-level field ${JSON.stringify(field)}`);
+  if (doc.schema !== LEDGER_SCHEMA) problems.push(`schema must be ${LEDGER_SCHEMA}`);
+  if (!isPlainObject(doc.namespaces)) { problems.push('namespaces must be a mapping of namespace to a list of entries'); return { entries: [], problems }; }
+  const entries = [];
+  for (const [namespace, list] of Object.entries(doc.namespaces)) {
+    if (!Array.isArray(list)) { problems.push(`namespace ${JSON.stringify(namespace)} must be a list of entries`); continue; }
+    list.forEach((entry, index) => {
+      const problem = entryProblem(entry);
+      if (problem) { problems.push(`namespace ${JSON.stringify(namespace)} entry ${index + 1} ${problem}`); return; }
+      const kind = MATCHERS.find(field => field in entry);
+      entries.push({ namespace, kind, value: entry[kind] });
+    });
+  }
+  return { entries, problems };
+}
+
+/**
+ * Mark every catalog key the side's ledger names as read, and return the ledger's own findings (malformed, or an entry
+ * matching no catalog key). No file means no ledger. Only a fe side reads its fe ledger and a be side its be ledger.
+ */
+export function applyDynamicKeysLedger(state, profile) {
+  if (!SIDES.has(profile)) return [];
+  const source = readText(state.repoRoot, LEDGER_FILE);
+  if (source === null) return [];
+  const { entries, problems } = parseLedger(source);
+  const own = (message, name) => found(CODE, LEDGER_FILE, `${LEDGER_FILE}: ${message}`, { line: 1, column: 1, kind: 'dynamic-keys ledger', name });
+  const findings = problems.map(problem => own(`malformed dynamic-keys ledger: ${problem}.`, 'ledger'));
+  const catalog = state.candidates.filter(candidate => candidate.kind === 'catalog key').map(candidate => ({ candidate, ...splitCatalogName(candidate.name) }));
+  for (const entry of entries) {
+    const hits = catalog.filter(({ namespace, leaf }) => namespace === entry.namespace && matches(entry, leaf));
+    for (const { candidate } of hits) candidate.used = true;
+    if (!hits.length) findings.push(own(`dynamic-keys ledger entry ${describe(entry)} in namespace ${JSON.stringify(entry.namespace)} matches no catalog key; delete it.`, `${entry.namespace}:${describe(entry)}`));
+  }
+  return findings;
+}

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

@@ -0,0 +1,165 @@
+// Translators of R280: which catalog namespace a `t(...)` call reads, followed through destructuring and props.
+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';
+
+const TRANSLATOR_NAME = /^(?:t|translate)$/u;
+
+function translationFactories(ts, source) {
+  const factories = new Set(['useTranslations', 'getTranslations']);
+  for (const statement of source.statements) {
+    if (!ts.isImportDeclaration(statement) || !/^(?:next-intl|next-intl\/server)$/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);
+    }
+  }
+  return factories;
+}
+
+function translatorNamespace(state, initializer, factories) {
+  const { ts } = state;
+  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;
+  let first = init.arguments[0];
+  if (first && ts.isObjectLiteralExpression(first)) first = first.properties.find(property => nameText(ts, property.name, { numbers: true }) === 'namespace')?.initializer;
+  return first ? staticStrings(state, first) : [''];
+}
+
+/** `Promise.all([...])` and a plain array literal hand each element to the binding at the same index. */
+function translatorList(ts, initializer) {
+  let list = unwrap(ts, initializer);
+  if (list && ts.isAwaitExpression(list)) list = unwrap(ts, list.expression);
+  if (list && ts.isCallExpression(list) && ts.isPropertyAccessExpression(list.expression) && list.expression.name.text === 'all') list = unwrap(ts, list.arguments[0]);
+  return list && ts.isArrayLiteralExpression(list) ? list.elements : [];
+}
+
+const isFunction = (ts, node) => Boolean(node) && (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node));
+
+/** A function whose result is a call on a bound translator with its own first parameter is that translator. */
+function forwardedNamespaces(state, fn) {
+  const { ts, checker } = state;
+  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);
+  });
+}
+
+/** useCallback(fn, deps) and useMemo(() => fn, deps) are the function fn. */
+function transparentFunction(state, expression) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  if (!node || !ts.isCallExpression(node)) return node;
+  const name = leafName(ts, node.expression);
+  const inner = /^(?:useCallback|useMemo)$/u.test(name) ? unwrap(ts, node.arguments[0]) : null;
+  if (!inner) return node;
+  if (name === 'useCallback') return inner;
+  if (!isFunction(ts, inner)) return node;
+  return returnedExpressions(ts, inner).map(returned => unwrap(ts, returned)).find(candidate => isFunction(ts, candidate)) ?? node;
+}
+
+/** A hook returns such a forwarding function, bare or wrapped in useCallback or useMemo. */
+function hookNamespaces(state, hook) {
+  const { ts } = state;
+  return returnedExpressions(ts, hook).flatMap(expression => {
+    const inner = transparentFunction(state, expression);
+    return isFunction(ts, inner) ? forwardedNamespaces(state, inner) : [];
+  });
+}
+
+function wrapperNamespaces(state, initializer) {
+  const { ts } = state;
+  let init = transparentFunction(state, initializer);
+  if (init && ts.isAwaitExpression(init)) init = unwrap(ts, init.expression);
+  if (isFunction(ts, init)) return forwardedNamespaces(state, init);
+  const target = init && ts.isCallExpression(init) ? callable(state, init.expression) : null;
+  return isFunction(ts, target) ? hookNamespaces(state, target) : [];
+}
+
+function bindTranslator(state, name, initializer, factories) {
+  const { ts, checker } = state;
+  if (ts.isIdentifier(name)) {
+    const namespaces = translatorNamespace(state, initializer, factories) ?? wrapperNamespaces(state, initializer);
+    if (namespaces?.length) state.translators.set(checker.getSymbolAtLocation(name), namespaces);
+  } else if (ts.isArrayBindingPattern(name)) {
+    const elements = translatorList(ts, initializer);
+    name.elements.forEach((element, index) => { if (ts.isBindingElement(element) && elements[index]) bindTranslator(state, element.name, elements[index], 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)]));
+  for (let pass = 0, size = -1; pass < 4 && size !== state.translators.size; pass++) {
+    size = state.translators.size;
+    for (const source of sources.values()) {
+      const visit = node => {
+        if (state.ts.isVariableDeclaration(node) && node.initializer) bindTranslator(state, node.name, node.initializer, factories.get(source));
+        state.ts.forEachChild(node, visit);
+      };
+      visit(source);
+    }
+  }
+}
+
+/** 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;
+  const direct = state.translators.get(checker.getSymbolAtLocation(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())) ?? [];
+    return ts.isIdentifier(leaf) ? state.translators.get(checker.getSymbolAtLocation(leaf)) ?? [] : [];
+  });
+}
+
+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 : '';
+}
+
+/** A callback typed (string, ...) => string: the shape of a translator whatever its name. */
+function translatorShaped(state, receiver) {
+  const { checker } = state;
+  const [signature] = checker.getTypeAtLocation(receiver).getCallSignatures();
+  const first = signature?.getParameters()[0];
+  if (!first) return false;
+  const isString = type => Boolean(type.flags & state.ts.TypeFlags.String);
+  return isString(checker.getTypeOfSymbolAtLocation(first, receiver)) && isString(signature.getReturnType());
+}
+
+/**
+ * Namespaces read by a call of `callee`; `null` stands for a translator handed in whose namespace cannot be followed
+ * (R106 reads such a key by its leaf), and no result means the call is no catalog read.
+ */
+export function catalogNamespace(state, callee) {
+  const { ts } = state;
+  let receiver = 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 [''];
+  return [];
+}

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

@@ -0,0 +1,103 @@
+// Static values used at runtime by catalog consumers. A declaration alone is never a read.
+import path from 'node:path';
+import { unwrapCatalogExpression as unwrap } from '../../lib/ts-analysis.mjs';
+import { 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;
+}
+
+function bindArgument(state, parameter, argument) {
+  if (!parameter || !argument) return;
+  const key = state.ts.isIdentifier(parameter.name) ? state.checker.getSymbolAtLocation(parameter.name) : parameter;
+  state.arguments.set(key, [...state.arguments.get(key) ?? [], argument]);
+}
+
+/** Record the actual arguments of local functions, including imported functions and arrow exports. */
+export function argumentBindings(state, sources) {
+  for (const source of sources.values()) {
+    const visit = node => {
+      if (state.ts.isCallExpression(node)) {
+        const target = callable(state, node.expression);
+        for (const [index, parameter] of (target?.parameters ?? []).entries()) bindArgument(state, parameter, node.arguments[index]);
+      } else if (state.ts.isJsxSelfClosingElement(node) || state.ts.isJsxOpeningElement(node)) {
+        // A component's props parameter receives the attribute list of every element that renders it.
+        bindArgument(state, callable(state, node.tagName)?.parameters?.[0], node.attributes);
+      }
+      state.ts.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+}
+
+function typeStrings(state, node) {
+  const type = state.checker.getTypeAtLocation(node);
+  const types = type.isUnion() ? type.types : [type];
+  return types.length && types.every(part => part.isStringLiteral()) ? types.map(part => part.value) : [];
+}
+
+/** Follow finite literals only; a broad string or an unbounded dynamic expression gives no evidence. */
+export function staticStrings(state, expression, visited = new Set()) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  if (!node || visited.has(node)) 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)];
+  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);
+  const bound = declaration && ts.isParameter(declaration) ? state.arguments.get(symbolAt(state, node)) ?? [] : [];
+  if (bound.length) return bound.flatMap(argument => staticStrings(state, argument, seen));
+  // 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));
+}
+
+/** JSON imports are catalog owners; their runtime member reads survive named aliases and re-exports. */
+export function jsonCatalogBindings(state, sources, files) {
+  const tracked = new Set(files);
+  for (const source of sources.values()) for (const statement of source.statements) {
+    if (!state.ts.isImportDeclaration(statement) || !statement.importClause?.name) continue;
+    const specifier = statement.moduleSpecifier.text;
+    if (!specifier?.endsWith('.json')) continue;
+    const target = state.resolveModule(specifier, source.fileName)?.resolvedFileName;
+    if (!target) continue;
+    const relative = path.relative(state.repoRoot, target).replaceAll('\\', '/');
+    if (!tracked.has(relative) || !JSON_CATALOG.test(relative)) continue;
+    state.catalogObjects.set(state.checker.getSymbolAtLocation(statement.importClause.name), '');
+  }
+}
+
+function catalogObjectPath(state, expression, seen = new Set()) {
+  const { ts } = state;
+  const node = unwrap(ts, expression);
+  if (!node || seen.has(node)) return null;
+  seen.add(node);
+  if (ts.isPropertyAccessExpression(node)) {
+    const prefix = catalogObjectPath(state, node.expression, seen);
+    return prefix === null ? null : `${prefix}${node.name.text}.`;
+  }
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) {
+    const prefix = catalogObjectPath(state, node.expression, seen);
+    return prefix === null ? null : `${prefix}${node.argumentExpression.text}.`;
+  }
+  const direct = state.catalogObjects.get(state.checker.getSymbolAtLocation(node));
+  if (direct !== undefined) return direct;
+  const declaration = symbolAt(state, node)?.valueDeclaration;
+  return declaration && ts.isVariableDeclaration(declaration) ? catalogObjectPath(state, declaration.initializer, seen) : null;
+}
+
+export function jsonCatalogRead(state, node) {
+  if (!state.ts.isPropertyAccessExpression(node) && !state.ts.isElementAccessExpression(node)) return;
+  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)) {
+    const base = catalogObjectPath(state, node.expression);
+    if (base !== null) for (const value of staticStrings(state, node.argumentExpression)) state.catalogReads.add(`${base}${value}`);
+  }
+}