@trackunit/eslint-plugin-trackunit 0.6.98 → 0.6.100-alpha-770d9994af7.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.6.99 (2026-08-11)
+
+### 🧱 Updated Dependencies
+
+- Updated css-classname-utils to 0.0.5
+- Updated shared-utils to 1.16.2
+
 ## 0.6.98 (2026-08-10)
 
 ### 🧱 Updated Dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/eslint-plugin-trackunit",
-  "version": "0.6.98",
+  "version": "0.6.100-alpha-770d9994af7.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "repository": "https://github.com/Trackunit/manager",
   "engines": {
@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@nx/eslint-plugin": "23.1.0",
-    "@trackunit/css-classname-utils": "0.0.4",
+    "@trackunit/css-classname-utils": "0.0.6-alpha-770d9994af7.0",
     "@typescript-eslint/eslint-plugin": "8.58.1",
     "@typescript-eslint/utils": "8.58.1",
     "eslint-config-prettier": "^10.1.8",

package/src/lib/rules/no-dynamic-translation-key/no-dynamic-translation-key.js

@@ -21,9 +21,30 @@ exports.noDynamicTranslationKey = void 0;
  * t(categoryKey[category]);
  */
 const utils_1 = require("@typescript-eslint/utils");
+const translation_key_types_1 = require("../../utils/translation-key-types");
 const createRule = utils_1.ESLintUtils.RuleCreator(name => `https://github.com/trackunit/manager/blob/main/libs/eslint/plugin-trackunit/src/lib/rules/${name}/${name}.ts`);
 /** A template literal that actually interpolates a value, e.g. `foo.${bar}` (not a plain `foo`). */
 const isInterpolatedTemplate = (node) => node.type === utils_1.AST_NODE_TYPES.TemplateLiteral && node.expressions.length > 0;
+/**
+ * Whether a template literal's interpolations should be flagged: true unless every
+ * interpolated expression's TypeScript type is a finite string-literal union (in which
+ * case every possible resulting key is statically enumerable). If type resolution fails
+ * for any reason (e.g. a non-type-aware lint run), fails safe by flagging the template.
+ */
+const hasWidenedInterpolation = (context, templateLiteral) => {
+    try {
+        const services = utils_1.ESLintUtils.getParserServices(context);
+        const checker = services.program.getTypeChecker();
+        return templateLiteral.expressions.some(expr => {
+            const tsNode = services.esTreeNodeToTSNodeMap.get(expr);
+            const type = checker.getTypeAtLocation(tsNode);
+            return (0, translation_key_types_1.classifyInterpolationType)(type) === "widened";
+        });
+    }
+    catch {
+        return true;
+    }
+};
 /** A call to the translation function: either a bare `t(...)` or a member call like `i18n.t(...)`. */
 const isTranslationCallee = (callee) => {
     if (callee.type === utils_1.AST_NODE_TYPES.Identifier) {
@@ -42,7 +63,7 @@ exports.noDynamicTranslationKey = createRule({
             description: "Disallow building i18next translation keys dynamically with template strings; map values to explicit keys with a switch or Record instead.",
         },
         messages: {
-            dynamicKey: "Avoid building translation keys dynamically with template strings. Map the value to an explicit key using a switch statement or a Record so keys stay statically analysable and unused keys can be detected.",
+            dynamicKey: "Avoid building translation keys dynamically with template strings unless every interpolated value has a finite string-literal union type (TypeScript can then enumerate every possible key). Otherwise, map the value to an explicit key using a switch statement or a Record so keys stay statically analysable and unused keys can be detected.",
         },
         schema: [],
     },
@@ -54,7 +75,7 @@ exports.noDynamicTranslationKey = createRule({
                     return;
                 }
                 const [firstArg] = node.arguments;
-                if (firstArg && isInterpolatedTemplate(firstArg)) {
+                if (firstArg && isInterpolatedTemplate(firstArg) && hasWidenedInterpolation(context, firstArg)) {
                     context.report({ node: firstArg, messageId: "dynamicKey" });
                 }
             },
@@ -63,7 +84,9 @@ exports.noDynamicTranslationKey = createRule({
                     return;
                 }
                 const { value } = node;
-                if (value?.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer && isInterpolatedTemplate(value.expression)) {
+                if (value?.type === utils_1.AST_NODE_TYPES.JSXExpressionContainer &&
+                    isInterpolatedTemplate(value.expression) &&
+                    hasWidenedInterpolation(context, value.expression)) {
                     context.report({ node: value.expression, messageId: "dynamicKey" });
                 }
             },

package/src/lib/rules/no-unused-translation-key/expand-dynamic-key.d.ts

@@ -0,0 +1,28 @@
+import * as ts from "typescript";
+/**
+ * The result of expanding one direct `t(...)`/`i18nKey={...}` template-literal call:
+ * - `concrete` — every interpolation was a finite string-literal union, so every possible key is
+ *   enumerated exactly.
+ * - `pattern` — at least one interpolation widened to `string`/`any`/`unknown`/an enum, so we fall
+ *   back to today's conservative prefix/suffix wildcard.
+ */
+export type ExpandedDynamicKey = {
+    kind: "concrete";
+    keys: Array<string>;
+} | {
+    kind: "pattern";
+    prefix: string;
+    suffix: string;
+};
+/**
+ * Walks every real source file belonging to `projectDir` within `program`, expanding each direct
+ * `t(...)`/`i18nKey={...}` template-literal call into either its exact concrete keys or a
+ * conservative prefix/suffix pattern (see `ExpandedDynamicKey`).
+ *
+ * `program` may contain many more files than just this library's own — see `isScannableSourceFile` —
+ * so `projectDir` scopes the walk to the library actually being linted.
+ *
+ * Indirect/variable-built keys (`const key = \`a.${x}\`; t(key)`) are not matched — only template
+ * literals written directly inside the call/attribute are.
+ */
+export declare const expandDynamicKeysInProgram: (program: ts.Program, checker: ts.TypeChecker, projectDir: string) => Array<ExpandedDynamicKey>;

package/src/lib/rules/no-unused-translation-key/expand-dynamic-key.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandDynamicKeysInProgram = void 0;
+const tslib_1 = require("tslib");
+/**
+ * Type-aware expansion of dynamic (template-literal) translation keys.
+ *
+ * `used-strings.ts` detects dynamic keys via regex over raw source text, producing a
+ * `{ prefix, suffix }` wildcard pattern that conservatively treats every key matching that
+ * prefix/suffix as "used". This module replaces that conservative pattern with the exact set of
+ * concrete keys whenever every interpolation in a direct `t(...)`/`i18nKey={...}` template
+ * literal is a finite string-literal union — `` t(`cat.${category}`) `` with
+ * `category: "A" | "B"` becomes `["cat.A", "cat.B"]` instead of `{ prefix: "cat.", suffix: "" }`.
+ *
+ * This walks a real `ts.Program` (see `program-utils.ts`) directly, independent of ESLint's own
+ * per-file visitor, because it needs to examine every file in a library — not just the one file
+ * ESLint happens to be linting when it asks "is this key used?".
+ *
+ * Indirect/variable-built keys (`const key = \`a.${x}\`; t(key)`) are out of scope here and stay on
+ * the existing regex path in `used-strings.ts` — this only matches template literals written
+ * directly inside the call/attribute, mirroring the restriction `no-dynamic-translation-key`
+ * itself enforces.
+ */
+const path = tslib_1.__importStar(require("path"));
+const ts = tslib_1.__importStar(require("typescript"));
+const translation_key_types_1 = require("../../utils/translation-key-types");
+const EXCLUDED_PATH_SEGMENTS = ["/node_modules/", "/dist/", "/generated/", "/coverage/", "/.git/"];
+function isFiniteStringLiteralType(type) {
+    const flags = type.getFlags();
+    return (flags & ts.TypeFlags.StringLiteral) !== 0 && (flags & ts.TypeFlags.EnumLiteral) === 0;
+}
+/**
+ * Extracts the exact string values of a finite string-literal type or union thereof.
+ *
+ * A union may also carry an `undefined` member (see `classifyInterpolationType`, which still
+ * classifies such a union as `literalUnion` as long as every *other* member is a string literal).
+ * A real call site with that interpolation `undefined` produces the runtime string `"undefined"` --
+ * JS template literals stringify `undefined` to the text "undefined" -- so that literal string is
+ * included as one of the concrete values, alongside the real string-literal members.
+ */
+const getLiteralStringValues = (type) => {
+    if (type.isUnion()) {
+        const literalValues = type.types.filter(isFiniteStringLiteralType).map(member => member.value);
+        const hasUndefinedMember = type.types.some(member => (member.getFlags() & ts.TypeFlags.Undefined) !== 0);
+        return hasUndefinedMember ? [...literalValues, "undefined"] : literalValues;
+    }
+    return isFiniteStringLiteralType(type) ? [type.value] : [];
+};
+/** A call to the translation function: either a bare `t(...)` or a member call like `i18n.t(...)`. */
+const isTranslationCalleeNode = (callee) => {
+    if (ts.isIdentifier(callee)) {
+        return callee.text === "t";
+    }
+    return ts.isPropertyAccessExpression(callee) && callee.name.text === "t";
+};
+/** Today's conservative prefix/suffix wildcard: the static text before the first, and after the last, interpolation. */
+const buildPatternFallback = (template) => {
+    const spans = template.templateSpans;
+    const lastSpan = spans[spans.length - 1];
+    return {
+        kind: "pattern",
+        prefix: template.head.text,
+        suffix: lastSpan ? lastSpan.literal.text : "",
+    };
+};
+/**
+ * Expands one direct template-literal call: concrete cross-product if every interpolation is a
+ * finite string-literal union, otherwise the prefix/suffix fallback. Fails safe to the fallback
+ * if type resolution throws for this call site, so one bad call can't crash the whole scan.
+ */
+const expandTemplate = (template, checker) => {
+    try {
+        const interpolations = [];
+        for (const span of template.templateSpans) {
+            const type = checker.getTypeAtLocation(span.expression);
+            if ((0, translation_key_types_1.classifyInterpolationType)(type) !== "literalUnion") {
+                return buildPatternFallback(template);
+            }
+            const values = getLiteralStringValues(type);
+            if (values.length === 0) {
+                return buildPatternFallback(template);
+            }
+            interpolations.push({ values, literalText: span.literal.text });
+        }
+        let keys = [template.head.text];
+        for (const { values, literalText } of interpolations) {
+            const next = [];
+            for (const key of keys) {
+                for (const value of values) {
+                    next.push(key + value + literalText);
+                }
+            }
+            keys = next;
+        }
+        return { kind: "concrete", keys };
+    }
+    catch {
+        return buildPatternFallback(template);
+    }
+};
+/**
+ * Unwraps `as`/`satisfies`/parenthesized wrappers to find a `TemplateExpression` underneath.
+ *
+ * `` t(`cat.${x}` as const) `` parses as an `AsExpression` whose `.expression` is the actual
+ * `TemplateExpression` — the wrapper is invisible to a direct `ts.isTemplateExpression(node)` check,
+ * even though the checker still reports a type for the inner expression regardless of the wrapper
+ * (see `expandTemplate`'s use of `checker.getTypeAtLocation(span.expression)`, which is unaffected by
+ * unwrapping here since spans live inside the returned node either way).
+ */
+const unwrapToTemplateExpression = (node) => {
+    let current = node;
+    while (ts.isAsExpression(current) || ts.isSatisfiesExpression(current) || ts.isParenthesizedExpression(current)) {
+        current = current.expression;
+    }
+    return ts.isTemplateExpression(current) ? current : null;
+};
+/**
+ * Whether a JSX attribute is `i18nKey={...}` with a template-literal expression inside the braces.
+ */
+const getI18nKeyTemplate = (node) => {
+    if (!ts.isIdentifier(node.name) || node.name.text !== "i18nKey") {
+        return null;
+    }
+    const { initializer } = node;
+    if (initializer && ts.isJsxExpression(initializer) && initializer.expression) {
+        return unwrapToTemplateExpression(initializer.expression);
+    }
+    return null;
+};
+/** Finds every direct `t(`...${...}...`)`/`i18nKey={`...${...}...`}` template literal in a source file. */
+const collectDirectTemplates = (sourceFile) => {
+    const templates = [];
+    const visit = (node) => {
+        if (ts.isCallExpression(node) && isTranslationCalleeNode(node.expression)) {
+            const [firstArg] = node.arguments;
+            const template = firstArg && unwrapToTemplateExpression(firstArg);
+            if (template) {
+                templates.push(template);
+            }
+        }
+        else if (ts.isJsxAttribute(node)) {
+            const template = getI18nKeyTemplate(node);
+            if (template) {
+                templates.push(template);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return templates;
+};
+/**
+ * Whether a source file belongs to the library's own real source — not a declaration file, a
+ * vendored/build artifact, or a file pulled into the `Program` only because the library imports it
+ * (`ts.createProgram` includes every file transitively reachable from `rootNames`, which in this
+ * monorepo's path-mapped setup means every other library the library under scan depends on).
+ * `projectDirPrefix` restricts the scan back to files actually inside the library being linted, so a
+ * dependency's own `t(...)` calls aren't misattributed as this library's usage (and aren't re-walked
+ * on every dependent library's lint pass).
+ */
+const isScannableSourceFile = (sourceFile, projectDirPrefix) => {
+    if (sourceFile.isDeclarationFile) {
+        return false;
+    }
+    const fileName = sourceFile.fileName.replace(/\\/g, "/");
+    if (!/\.tsx?$/.test(fileName)) {
+        return false;
+    }
+    if (!fileName.startsWith(projectDirPrefix)) {
+        return false;
+    }
+    return !EXCLUDED_PATH_SEGMENTS.some(segment => fileName.includes(segment));
+};
+/**
+ * Walks every real source file belonging to `projectDir` within `program`, expanding each direct
+ * `t(...)`/`i18nKey={...}` template-literal call into either its exact concrete keys or a
+ * conservative prefix/suffix pattern (see `ExpandedDynamicKey`).
+ *
+ * `program` may contain many more files than just this library's own — see `isScannableSourceFile` —
+ * so `projectDir` scopes the walk to the library actually being linted.
+ *
+ * Indirect/variable-built keys (`const key = \`a.${x}\`; t(key)`) are not matched — only template
+ * literals written directly inside the call/attribute are.
+ */
+const expandDynamicKeysInProgram = (program, checker, projectDir) => {
+    const resolvedProjectDir = path.resolve(projectDir).replace(/\\/g, "/");
+    const projectDirPrefix = resolvedProjectDir.endsWith("/") ? resolvedProjectDir : `${resolvedProjectDir}/`;
+    const results = [];
+    for (const sourceFile of program.getSourceFiles()) {
+        if (!isScannableSourceFile(sourceFile, projectDirPrefix)) {
+            continue;
+        }
+        for (const template of collectDirectTemplates(sourceFile)) {
+            results.push(expandTemplate(template, checker));
+        }
+    }
+    return results;
+};
+exports.expandDynamicKeysInProgram = expandDynamicKeysInProgram;
+//# sourceMappingURL=expand-dynamic-key.js.map

package/src/lib/rules/no-unused-translation-key/used-strings.d.ts

@@ -18,11 +18,20 @@ export type DynamicPattern = {
  *   `` t(`pages.categories.${x}`) `` contributes `{ prefix: "pages.categories.", suffix: "" }` and
  *   `` t(`${root}.title`) `` contributes `{ prefix: "", suffix: ".title" }`. A key is treated as used
  *   when it both starts with the prefix and ends with the suffix of some pattern — the smallest set of
- *   keys the interpolation could possibly produce.
+ *   keys the interpolation could possibly produce. Populated both by the regex scan below (for
+ *   indirect/variable-built templates, and for direct templates when a type-aware `ts.Program`
+ *   couldn't be built) and by `expandDynamicKeysInProgram`'s `"pattern"` results (for direct
+ *   templates whose interpolation type widened past a finite literal union).
+ * - `concreteDynamicKeys` — exact keys a direct `` t(`...${x}...`) ``/`i18nKey={...}` template can
+ *   produce, when every interpolation resolves to a finite string-literal union. Computed by
+ *   `expandDynamicKeysInProgram` walking a real type-checked `ts.Program` (see `program-utils.ts`).
+ *   Precise, unlike `dynamicPatterns`: a key under the same static prefix that isn't one of these
+ *   exact keys is correctly reported as unused.
  */
 export type UsedStrings = {
     sourceText: string;
     dynamicPatterns: Array<DynamicPattern>;
+    concreteDynamicKeys: Set<string>;
 };
 /**
  * Build the used-strings summary from already-read source file contents.
@@ -30,14 +39,36 @@ export type UsedStrings = {
  * Kept free of filesystem access so the ESLint rule and the
  * `devtools/translations/remove-unused-translation-keys` script share one implementation of what
  * "used" means, each doing its own IO.
+ *
+ * `skipTrustedTemplates` — when a type-aware `ts.Program` was available and already produced precise
+ * results for every direct `t(...)`/`i18nKey={...}` template (see `getUsedTranslationStrings`), the
+ * regex-based "trusted" detection is redundant and would only re-introduce the conservative
+ * prefix/suffix wildcard the Program-based scan was meant to replace. When `true`, the trusted regex
+ * pass is skipped, and any template body it would have matched is also excluded from the "untrusted"
+ * pass (which otherwise re-discovers the same body via `ANY_TEMPLATE_REGEX` and — for a namespaced,
+ * dotted key — records the same wildcard pattern anyway). Defaults to `false`, preserving today's
+ * behavior exactly for libraries with no resolvable tsconfig.
  */
-export declare const buildUsedStrings: (contents: Array<string>) => UsedStrings;
+export declare const buildUsedStrings: (contents: Array<string>, options?: {
+    skipTrustedTemplates?: boolean;
+}) => UsedStrings;
 /**
  * Read a library's `.ts`/`.tsx` source, keeping the raw text plus any dynamic key patterns it builds.
+ *
+ * Also attempts a type-aware pass: `getLibraryProgram` builds (and caches) a `ts.Program` scoped to
+ * the library, and `expandDynamicKeysInProgram` walks it to resolve every direct
+ * `t(...)`/`i18nKey={...}` template literal into either its exact concrete keys (when every
+ * interpolation is a finite string-literal union) or today's conservative `{prefix, suffix}` pattern
+ * (when any interpolation widened). When that succeeds, it fully replaces the regex-based "trusted"
+ * template detection (see `buildUsedStrings`'s `skipTrustedTemplates`), since it covers the same call
+ * sites more precisely. When no tsconfig can be resolved, or anything throws, this step is skipped
+ * entirely and behavior falls back to the regex-only detection that ran before this rule was made
+ * type-aware.
  */
 export declare const getUsedTranslationStrings: (projectDir: string) => UsedStrings;
 /**
  * Whether a translation key is referenced by the scanned source — quoted verbatim, through a dynamic
- * template's static bookends, or as the plural form of a referenced base key.
+ * template's static bookends, as one of the exact keys a type-aware dynamic template can produce, or
+ * as the plural form of a referenced base key.
  */
 export declare const isTranslationKeyUsed: (used: UsedStrings, key: string) => boolean;

package/src/lib/rules/no-unused-translation-key/used-strings.js

@@ -4,6 +4,8 @@ exports.isTranslationKeyUsed = exports.getUsedTranslationStrings = exports.build
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
+const program_utils_1 = require("../../utils/program-utils");
+const expand_dynamic_key_1 = require("./expand-dynamic-key");
 const EXCLUDED_DIRS = new Set(["node_modules", "dist", "generated", "coverage", ".git"]);
 const SCANNED_EXTENSIONS = [".ts", ".tsx"];
 /**
@@ -67,24 +69,53 @@ const collectSourceFiles = (dir, files = []) => {
  * Kept free of filesystem access so the ESLint rule and the
  * `devtools/translations/remove-unused-translation-keys` script share one implementation of what
  * "used" means, each doing its own IO.
+ *
+ * `skipTrustedTemplates` — when a type-aware `ts.Program` was available and already produced precise
+ * results for every direct `t(...)`/`i18nKey={...}` template (see `getUsedTranslationStrings`), the
+ * regex-based "trusted" detection is redundant and would only re-introduce the conservative
+ * prefix/suffix wildcard the Program-based scan was meant to replace. When `true`, the trusted regex
+ * pass is skipped, and any template body it would have matched is also excluded from the "untrusted"
+ * pass (which otherwise re-discovers the same body via `ANY_TEMPLATE_REGEX` and — for a namespaced,
+ * dotted key — records the same wildcard pattern anyway). Defaults to `false`, preserving today's
+ * behavior exactly for libraries with no resolvable tsconfig.
  */
-const buildUsedStrings = (contents) => {
+const buildUsedStrings = (contents, options = {}) => {
+    const { skipTrustedTemplates = false } = options;
     const patterns = new Map();
     for (const content of contents) {
+        const trustedBodies = new Set();
         let translationTemplate;
         while ((translationTemplate = TRANSLATION_TEMPLATE_REGEX.exec(content)) !== null) {
-            recordTemplatePattern(translationTemplate[1] ?? "", true, patterns);
+            const body = translationTemplate[1] ?? "";
+            trustedBodies.add(body);
+            if (!skipTrustedTemplates) {
+                recordTemplatePattern(body, true, patterns);
+            }
         }
         let anyTemplate;
         while ((anyTemplate = ANY_TEMPLATE_REGEX.exec(content)) !== null) {
-            recordTemplatePattern(anyTemplate[1] ?? "", false, patterns);
+            const body = anyTemplate[1] ?? "";
+            if (skipTrustedTemplates && trustedBodies.has(body)) {
+                continue;
+            }
+            recordTemplatePattern(body, false, patterns);
         }
     }
-    return { sourceText: contents.join("\n"), dynamicPatterns: [...patterns.values()] };
+    return { sourceText: contents.join("\n"), dynamicPatterns: [...patterns.values()], concreteDynamicKeys: new Set() };
 };
 exports.buildUsedStrings = buildUsedStrings;
 /**
  * Read a library's `.ts`/`.tsx` source, keeping the raw text plus any dynamic key patterns it builds.
+ *
+ * Also attempts a type-aware pass: `getLibraryProgram` builds (and caches) a `ts.Program` scoped to
+ * the library, and `expandDynamicKeysInProgram` walks it to resolve every direct
+ * `t(...)`/`i18nKey={...}` template literal into either its exact concrete keys (when every
+ * interpolation is a finite string-literal union) or today's conservative `{prefix, suffix}` pattern
+ * (when any interpolation widened). When that succeeds, it fully replaces the regex-based "trusted"
+ * template detection (see `buildUsedStrings`'s `skipTrustedTemplates`), since it covers the same call
+ * sites more precisely. When no tsconfig can be resolved, or anything throws, this step is skipped
+ * entirely and behavior falls back to the regex-only detection that ran before this rule was made
+ * type-aware.
  */
 const getUsedTranslationStrings = (projectDir) => {
     const contents = [];
@@ -96,17 +127,46 @@ const getUsedTranslationStrings = (projectDir) => {
             continue;
         }
     }
-    return (0, exports.buildUsedStrings)(contents);
+    let expandedResults = null;
+    try {
+        const libraryProgram = (0, program_utils_1.getLibraryProgram)(projectDir);
+        if (libraryProgram) {
+            expandedResults = (0, expand_dynamic_key_1.expandDynamicKeysInProgram)(libraryProgram.program, libraryProgram.checker, projectDir);
+        }
+    }
+    catch {
+        expandedResults = null;
+    }
+    const used = (0, exports.buildUsedStrings)(contents, { skipTrustedTemplates: expandedResults !== null });
+    if (expandedResults) {
+        const patternKeys = new Set(used.dynamicPatterns.map(({ prefix, suffix }) => JSON.stringify([prefix, suffix])));
+        for (const result of expandedResults) {
+            if (result.kind === "concrete") {
+                for (const key of result.keys) {
+                    used.concreteDynamicKeys.add(key);
+                }
+                continue;
+            }
+            const patternKey = JSON.stringify([result.prefix, result.suffix]);
+            if (!patternKeys.has(patternKey)) {
+                patternKeys.add(patternKey);
+                used.dynamicPatterns.push({ prefix: result.prefix, suffix: result.suffix });
+            }
+        }
+    }
+    return used;
 };
 exports.getUsedTranslationStrings = getUsedTranslationStrings;
 /** Whether the key appears in the source as a quoted string, in any of the three quote styles. */
 const isQuotedInSource = (sourceText, key) => sourceText.includes(`"${key}"`) || sourceText.includes(`'${key}'`) || sourceText.includes(`\`${key}\``);
 /**
  * Whether a translation key is referenced by the scanned source — quoted verbatim, through a dynamic
- * template's static bookends, or as the plural form of a referenced base key.
+ * template's static bookends, as one of the exact keys a type-aware dynamic template can produce, or
+ * as the plural form of a referenced base key.
  */
 const isTranslationKeyUsed = (used, key) => {
     const isReferenced = (candidate) => isQuotedInSource(used.sourceText, candidate) ||
+        used.concreteDynamicKeys.has(candidate) ||
         used.dynamicPatterns.some(({ prefix, suffix }) => candidate.startsWith(prefix) && candidate.endsWith(suffix));
     return isReferenced(key) || (PLURAL_SUFFIX_REGEX.test(key) && isReferenced(key.replace(PLURAL_SUFFIX_REGEX, "")));
 };

package/src/lib/utils/program-utils.d.ts

@@ -0,0 +1,28 @@
+import * as ts from "typescript";
+/**
+ * Utility functions for building a type-checking TypeScript `Program` scoped to a library.
+ *
+ * ## Main Functions
+ * - `getLibraryProgram()` - Build (and cache) a `ts.Program`/`ts.TypeChecker` pair for a library
+ * - `clearProgramCache()` - Clear the cache. Useful for testing.
+ */
+export type LibraryProgram = {
+    program: ts.Program;
+    checker: ts.TypeChecker;
+};
+/**
+ * Build (and cache) a `ts.Program` scoped to the nearest `tsconfig.json` found by walking up from
+ * `projectDir`. Falls back to sibling leaf tsconfigs (`tsconfig.lib.json`, etc.) when the discovered
+ * config is solution-style and covers no real source files.
+ *
+ * @param projectDir - Absolute path to a library's directory (or a directory inside it)
+ * @returns The `Program`/`TypeChecker` pair, or `null` if no usable tsconfig was found
+ * @example
+ * const result = getLibraryProgram("/workspace/libs/my-lib");
+ * // Returns: { program, checker }
+ */
+export declare const getLibraryProgram: (projectDir: string) => LibraryProgram | null;
+/**
+ * Clear the Program cache. Useful for testing.
+ */
+export declare const clearProgramCache: () => void;

package/src/lib/utils/program-utils.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearProgramCache = exports.getLibraryProgram = void 0;
+const tslib_1 = require("tslib");
+const path = tslib_1.__importStar(require("path"));
+const ts = tslib_1.__importStar(require("typescript"));
+const file_utils_1 = require("./file-utils");
+/**
+ * Cache for library Programs to avoid re-parsing tsconfig and rebuilding the (expensive) `ts.Program`
+ * on every call. Key is the resolved `projectDir` passed in, value is the built program/checker pair.
+ */
+const programCache = new Map();
+/**
+ * Nx-convention leaf tsconfigs to fall back to, in priority order, when the discovered `tsconfig.json`
+ * turns out to be "solution style" (no real source files of its own — just `references` to these).
+ */
+const LEAF_TSCONFIG_CANDIDATES = ["tsconfig.lib.json", "tsconfig.app.json", "tsconfig.spec.json"];
+/** Parse a tsconfig file at `tsconfigPath`, resolving relative paths against its own directory. */
+const parseTsconfigAt = (tsconfigPath) => {
+    const configFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+    if (configFile.error) {
+        return null;
+    }
+    return ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(tsconfigPath));
+};
+/**
+ * Resolve a tsconfig that actually covers real source files, starting from `tsconfigPath`.
+ *
+ * Many Nx libraries use a "solution style" root `tsconfig.json` (`files: []` plus `references` to
+ * `tsconfig.lib.json`/`tsconfig.spec.json`/etc.) that parses to an empty `fileNames` on its own. When
+ * that happens, fall back to the sibling leaf configs that actually resolve source files.
+ *
+ * Every usable leaf config's `fileNames` are unioned (not just the first match): `tsconfig.lib.json`
+ * conventionally excludes spec/test/story/demo files, which live only in `tsconfig.spec.json`.
+ * Building the Program from a single leaf would silently drop those files from type-aware scanning —
+ * while the regex-based fallback elsewhere still sees them via a plain filesystem walk — leaving any
+ * dynamic key referenced only from such a file neither wildcarded nor concretely expanded (i.e.
+ * incorrectly reported as unused). Compiler `options` are taken from the first usable config; the
+ * leaf configs share the same `extends` chain so this only affects unrelated settings like `types`.
+ */
+const resolveUsableTsconfig = (tsconfigPath) => {
+    const parsed = parseTsconfigAt(tsconfigPath);
+    if (parsed && parsed.fileNames.some(fileName => !fileName.endsWith(".d.ts"))) {
+        return parsed;
+    }
+    const configDir = path.dirname(tsconfigPath);
+    const usableConfigs = [];
+    for (const candidate of LEAF_TSCONFIG_CANDIDATES) {
+        const candidatePath = path.join(configDir, candidate);
+        if (!ts.sys.fileExists(candidatePath)) {
+            continue;
+        }
+        const candidateParsed = parseTsconfigAt(candidatePath);
+        if (candidateParsed && candidateParsed.fileNames.some(fileName => !fileName.endsWith(".d.ts"))) {
+            usableConfigs.push(candidateParsed);
+        }
+    }
+    const [primaryConfig, ...restConfigs] = usableConfigs;
+    if (!primaryConfig) {
+        return null;
+    }
+    const fileNames = new Set(primaryConfig.fileNames);
+    for (const config of restConfigs) {
+        for (const fileName of config.fileNames) {
+            fileNames.add(fileName);
+        }
+    }
+    return { ...primaryConfig, fileNames: [...fileNames] };
+};
+/**
+ * Build (and cache) a `ts.Program` scoped to the nearest `tsconfig.json` found by walking up from
+ * `projectDir`. Falls back to sibling leaf tsconfigs (`tsconfig.lib.json`, etc.) when the discovered
+ * config is solution-style and covers no real source files.
+ *
+ * @param projectDir - Absolute path to a library's directory (or a directory inside it)
+ * @returns The `Program`/`TypeChecker` pair, or `null` if no usable tsconfig was found
+ * @example
+ * const result = getLibraryProgram("/workspace/libs/my-lib");
+ * // Returns: { program, checker }
+ */
+const getLibraryProgram = (projectDir) => {
+    const resolvedProjectDir = path.resolve(projectDir);
+    const cached = programCache.get(resolvedProjectDir);
+    if (cached) {
+        return cached;
+    }
+    // `findNearestFile` starts looking in the *parent* of the file path it's given, so probing with a
+    // synthetic file inside `resolvedProjectDir` makes it look in `resolvedProjectDir` itself first.
+    const tsconfigPath = (0, file_utils_1.findNearestFile)(path.join(resolvedProjectDir, "__probe__.ts"), "tsconfig.json");
+    if (!tsconfigPath) {
+        return null;
+    }
+    const parsedConfig = resolveUsableTsconfig(tsconfigPath);
+    if (!parsedConfig) {
+        return null;
+    }
+    const program = ts.createProgram({
+        rootNames: parsedConfig.fileNames,
+        options: parsedConfig.options,
+    });
+    const result = { program, checker: program.getTypeChecker() };
+    programCache.set(resolvedProjectDir, result);
+    return result;
+};
+exports.getLibraryProgram = getLibraryProgram;
+/**
+ * Clear the Program cache. Useful for testing.
+ */
+const clearProgramCache = () => {
+    programCache.clear();
+};
+exports.clearProgramCache = clearProgramCache;
+//# sourceMappingURL=program-utils.js.map

package/src/lib/utils/translation-key-types.d.ts

@@ -0,0 +1,8 @@
+import * as ts from "typescript";
+/**
+ * Classifies a template-literal interpolation's TypeScript type as either a finite
+ * string-literal union (every possible value is statically known, e.g. `"a" | "b"`) or a
+ * widened type (plain `string`, `any`, `unknown`, or any enum) whose exact set of values
+ * cannot be enumerated at compile time.
+ */
+export declare function classifyInterpolationType(type: ts.Type): "literalUnion" | "widened";

package/src/lib/utils/translation-key-types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyInterpolationType = classifyInterpolationType;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+function isFiniteStringLiteralType(type) {
+    const flags = type.getFlags();
+    return (flags & ts.TypeFlags.StringLiteral) !== 0 && (flags & ts.TypeFlags.EnumLiteral) === 0;
+}
+/**
+ * Classifies a template-literal interpolation's TypeScript type as either a finite
+ * string-literal union (every possible value is statically known, e.g. `"a" | "b"`) or a
+ * widened type (plain `string`, `any`, `unknown`, or any enum) whose exact set of values
+ * cannot be enumerated at compile time.
+ */
+function classifyInterpolationType(type) {
+    if (type.isUnion()) {
+        const nonUndefinedMembers = type.types.filter(member => (member.getFlags() & ts.TypeFlags.Undefined) === 0);
+        // `.some(isFiniteStringLiteralType)` was previously ANDed in here too, but it's implied by
+        // `length > 0 && every(...)`: if every member of a non-empty array passes, at least one does.
+        const isFiniteUnion = nonUndefinedMembers.length > 0 && nonUndefinedMembers.every(isFiniteStringLiteralType);
+        return isFiniteUnion ? "literalUnion" : "widened";
+    }
+    return isFiniteStringLiteralType(type) ? "literalUnion" : "widened";
+}
+//# sourceMappingURL=translation-key-types.js.map