@noctcore/lint-meta-rules 0.2.0 → 0.3.0

package/README.md

@@ -69,3 +69,15 @@ over the whole catalog.
 
 Every factory is callable with no arguments (all options default), so `createAllRules()` and
 per-factory defaults work out of the box; supply options to retarget a rule at your own repo.
+
+### `@noctcore/lint-meta-rules/i18n`
+
+Whole-program translation checks live on a separate entry point, because they run ESLint's parser
+and scope analysis (reusing the i18n visitor behind `noctcore-contracts/translation-key-exists`).
+The main entry never loads ESLint; this one needs the optional peers `eslint` and
+`@typescript-eslint/parser`. Its factories are not part of `RULE_FACTORIES` / `createAllRules()`:
+they are inert until you point them at your catalogs.
+
+| Factory | Category | What it enforces |
+| --- | --- | --- |
+| [`createTranslationDeadKeysRule`](./docs/rules/translation-dead-keys.md) | source-text | Every catalog key is reachable: named by a translation call, or spelled by some string in the source. |

package/dist/chunk-Z7TXSZR4.js

@@ -0,0 +1,63 @@
+// src/rules/shared.ts
+function dirOf(rel, basename = "package.json") {
+  return rel.replace(new RegExp(`/${escapeRegExp(basename)}$`), "");
+}
+function baseName(pathLike) {
+  const parts = pathLike.split("/").filter(Boolean);
+  return parts[parts.length - 1] ?? pathLike;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function countLines(text) {
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.length;
+}
+function recursiveGlobs(roots, extensions) {
+  return roots.flatMap((root) => extensions.map((ext) => `${root}/**/*${ext}`));
+}
+var DEFAULT_WORKFLOW_GLOBS = [
+  ".github/workflows/*.yml",
+  ".github/workflows/*.yaml"
+];
+var DEFAULT_SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".turbo",
+  "coverage"
+];
+function globFiles(glob, globs, skipDirs = []) {
+  const skip = new Set(skipDirs);
+  const found = /* @__PURE__ */ new Set();
+  for (const pattern of globs) {
+    for (const rel of glob(pattern)) {
+      if (!rel.split("/").some((segment) => skip.has(segment))) found.add(rel);
+    }
+  }
+  return [...found].sort();
+}
+function stripYamlComment(line) {
+  return line.replace(/(^|\s)#.*$/u, "");
+}
+function unquote(value) {
+  return value.trim().replace(/^(['"])(.*)\1$/u, "$2");
+}
+function anywhereGlobs(baseNames) {
+  return baseNames.flatMap((name) => [`**/${name}`, `**/.*/**/${name}`]);
+}
+
+export {
+  dirOf,
+  baseName,
+  escapeRegExp,
+  countLines,
+  recursiveGlobs,
+  DEFAULT_WORKFLOW_GLOBS,
+  DEFAULT_SKIP_DIRS,
+  globFiles,
+  stripYamlComment,
+  unquote,
+  anywhereGlobs
+};

package/dist/i18n.cjs

@@ -0,0 +1,317 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/i18n.ts
+var i18n_exports = {};
+__export(i18n_exports, {
+  createTranslationDeadKeysRule: () => createTranslationDeadKeysRule,
+  deriveNamespaces: () => deriveNamespaces
+});
+module.exports = __toCommonJS(i18n_exports);
+
+// src/i18n/translation-dead-keys.ts
+var import_node_path = __toESM(require("path"), 1);
+var import_eslint_plugin_contracts = require("@noctcore/eslint-plugin-contracts");
+var tsParser = __toESM(require("@typescript-eslint/parser"), 1);
+var import_utils = require("@typescript-eslint/utils");
+var import_eslint = require("eslint");
+
+// src/rules/shared.ts
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var DEFAULT_SKIP_DIRS = [
+  "node_modules",
+  ".git",
+  "dist",
+  ".turbo",
+  "coverage"
+];
+function globFiles(glob, globs, skipDirs = []) {
+  const skip = new Set(skipDirs);
+  const found = /* @__PURE__ */ new Set();
+  for (const pattern of globs) {
+    for (const rel of glob(pattern)) {
+      if (!rel.split("/").some((segment) => skip.has(segment))) found.add(rel);
+    }
+  }
+  return [...found].sort();
+}
+
+// src/i18n/translation-dead-keys.ts
+var DEFAULT_ID = "translation-dead-keys";
+var NS_PLACEHOLDER = "{ns}";
+var SOURCE_FILES = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
+function namespacesFromFileTemplate(ctx, file) {
+  const segments = file.split("/");
+  if (segments.filter((segment) => segment.includes(NS_PLACEHOLDER)).length !== 1) return [];
+  const pattern = file.replaceAll(NS_PLACEHOLDER, "*");
+  const capture = new RegExp(
+    `^${file.split(NS_PLACEHOLDER).map((part) => escapeRegExp(part).replaceAll("\\*", "[^/]*")).join("([^/]+)")}$`,
+    "u"
+  );
+  const found = [];
+  for (const rel of ctx.glob(pattern)) {
+    const namespace = capture.exec(rel)?.[1];
+    if (namespace !== void 0) found.push(namespace);
+  }
+  return found;
+}
+function namespacesFromKeyPath(ctx, file, keyPath) {
+  const segments = keyPath.split(".");
+  if (segments.indexOf(NS_PLACEHOLDER) !== segments.length - 1) return null;
+  const text = ctx.read(file);
+  if (text === null) return [];
+  let node = JSON.parse(text);
+  for (const segment of segments.slice(0, -1)) {
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, segment)) return [];
+    node = node[segment];
+  }
+  return node !== null && typeof node === "object" ? Object.keys(node) : [];
+}
+function deriveNamespaces(ctx, catalogs, defaultNamespace) {
+  const found = /* @__PURE__ */ new Set();
+  for (const source of catalogs) {
+    const fileTemplated = source.file.includes(NS_PLACEHOLDER);
+    const keyPathTemplated = source.keyPath?.includes(NS_PLACEHOLDER) ?? false;
+    if (!fileTemplated && !keyPathTemplated) {
+      found.add(source.namespace ?? defaultNamespace);
+      continue;
+    }
+    const derived = fileTemplated ? namespacesFromFileTemplate(ctx, source.file) : namespacesFromKeyPath(ctx, source.file, source.keyPath ?? "");
+    if (derived === null || fileTemplated && keyPathTemplated) {
+      throw new Error(
+        `cannot enumerate the namespaces of catalog ${JSON.stringify(source)}: list them in \`namespaces\``
+      );
+    }
+    for (const namespace of derived) found.add(namespace);
+  }
+  return [...found].sort();
+}
+function holePattern(fragments) {
+  if (fragments.join("").replace(/[.:_\-/\s]/gu, "").length < 2) return null;
+  return new RegExp(`^${fragments.map(escapeRegExp).join(".*")}$`, "u");
+}
+function textFragments(root) {
+  const fragments = [""];
+  let sawText = false;
+  const hole = () => {
+    if (fragments.length === 1 || fragments[fragments.length - 1] !== "") fragments.push("");
+  };
+  const text = (value) => {
+    sawText = true;
+    fragments[fragments.length - 1] += value;
+  };
+  const visit = (node) => {
+    if (node.type === import_utils.AST_NODE_TYPES.BinaryExpression && node.operator === "+") {
+      visit(node.left);
+      visit(node.right);
+    } else if (node.type === import_utils.AST_NODE_TYPES.Literal && typeof node.value === "string") {
+      text(node.value);
+    } else if (node.type === import_utils.AST_NODE_TYPES.TemplateLiteral) {
+      node.quasis.forEach((quasi, index) => {
+        if (index > 0) hole();
+        text(quasi.value.cooked ?? "");
+      });
+    } else {
+      hole();
+    }
+  };
+  visit(root);
+  return sawText ? fragments : null;
+}
+function collectReach(ctx, files, options, reach) {
+  const settings = (0, import_eslint_plugin_contracts.translationSettingsOf)(options);
+  const fallbackNamespaces = options.fallbackNamespaces ?? [];
+  const keySeparator = settings.keySeparator;
+  const addPrefix = (namespace, prefix) => {
+    reach.prefixes.set(namespace, [...reach.prefixes.get(namespace) ?? [], prefix]);
+  };
+  const onUsage = (usage) => {
+    if (usage.kind === "key") {
+      for (const namespace of [...usage.namespaces, ...fallbackNamespaces]) {
+        for (const key of usage.keys) {
+          reach.exact.add(`${namespace}\0${key}`);
+          if (usage.returnObjects && keySeparator !== false) addPrefix(namespace, `${key}${keySeparator}`);
+        }
+      }
+    } else if (usage.kind === "prefix") {
+      for (const namespace of [...usage.namespaces, ...fallbackNamespaces]) addPrefix(namespace, usage.prefix);
+    }
+  };
+  const addText = (node) => {
+    const fragments = textFragments(node);
+    if (fragments === null) return;
+    if (fragments.length === 1) {
+      if (fragments[0] !== "") reach.literals.add(fragments[0] ?? "");
+      return;
+    }
+    const pattern = holePattern(fragments);
+    if (pattern !== null) reach.patterns.push(pattern);
+  };
+  const collector = {
+    defaultOptions: [],
+    meta: { type: "problem", schema: [], messages: { never: "never reported" } },
+    create(context) {
+      return {
+        ...(0, import_eslint_plugin_contracts.createTranslationVisitor)(context, settings, onUsage),
+        Literal(node) {
+          if (typeof node.value === "string" && node.value !== "") reach.literals.add(node.value);
+        },
+        TemplateLiteral(node) {
+          if (!isConcatOperand(node)) addText(node);
+        },
+        BinaryExpression(node) {
+          if (node.operator === "+" && !isConcatOperand(node)) addText(node);
+        }
+      };
+    }
+  };
+  const linter = new import_eslint.Linter({ cwd: ctx.root });
+  const config = [
+    {
+      // Not `**/*`: flat config treats a match-everything pattern as universal
+      // and applies it to no file on its own.
+      files: SOURCE_FILES,
+      languageOptions: {
+        parser: tsParser,
+        parserOptions: { ecmaFeatures: { jsx: true } }
+      },
+      linterOptions: { reportUnusedDisableDirectives: "off" },
+      plugins: { deadKeys: { rules: { collect: collector } } },
+      rules: { "deadKeys/collect": "error" }
+    }
+  ];
+  const unparsed = [];
+  for (const file of files) {
+    const text = ctx.read(file);
+    if (text === null) continue;
+    const messages = linter.verify(text, config, { filename: import_node_path.default.join(ctx.root, file) });
+    if (messages.some((message) => message.ruleId === null)) unparsed.push(file);
+  }
+  return unparsed;
+}
+function isConcatOperand(node) {
+  const parent = node.parent;
+  return parent?.type === import_utils.AST_NODE_TYPES.BinaryExpression && parent.operator === "+";
+}
+function allowPatterns(allow) {
+  return allow.map((pattern) => new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`, "u"));
+}
+function lookupForms(key, keySeparator) {
+  const forms = [key];
+  const lastSegmentStart = keySeparator === false ? 0 : key.lastIndexOf(keySeparator) + 1;
+  let base = key;
+  while (base.lastIndexOf("_") > lastSegmentStart) {
+    base = base.slice(0, base.lastIndexOf("_"));
+    forms.push(base);
+  }
+  return forms;
+}
+function isReached(namespace, key, reach, nsSeparator, keySeparator) {
+  for (const prefix of reach.prefixes.get(namespace) ?? []) {
+    if (key.startsWith(prefix)) return true;
+  }
+  const texts = [];
+  for (const form of lookupForms(key, keySeparator)) {
+    if (reach.exact.has(`${namespace}\0${form}`)) return true;
+    texts.push(form);
+    if (nsSeparator !== false) texts.push(`${namespace}${nsSeparator}${form}`);
+  }
+  if (texts.some((text) => reach.literals.has(text))) return true;
+  return reach.patterns.some((pattern) => texts.some((text) => pattern.test(text)));
+}
+function createTranslationDeadKeysRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const catalogs = options.catalogs ?? [];
+  const sourceGlobs = options.sourceGlobs ?? [];
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const allow = allowPatterns(options.allow ?? []);
+  const ciCritical = options.ciCritical ?? true;
+  const defaultNamespace = options.defaultNamespace ?? import_eslint_plugin_contracts.TRANSLATION_DEFAULTS.defaultNamespace;
+  const nsSeparator = options.nsSeparator ?? import_eslint_plugin_contracts.TRANSLATION_DEFAULTS.nsSeparator;
+  const keySeparator = options.keySeparator ?? import_eslint_plugin_contracts.TRANSLATION_DEFAULTS.keySeparator;
+  return {
+    id,
+    category: "source-text",
+    ciCritical,
+    description: "Every translation catalog key must be reachable from the source: named by a translation call, or spelled by some string in the code.",
+    run(ctx) {
+      if (catalogs.length === 0 || sourceGlobs.length === 0) return [];
+      const violations = [];
+      const report = (file, message) => {
+        violations.push({ file, rule: id, message });
+      };
+      const namespaces = options.namespaces ?? deriveNamespaces(ctx, catalogs, defaultNamespace);
+      const keyed = [];
+      for (const namespace of namespaces) {
+        const loaded = (0, import_eslint_plugin_contracts.catalogsForNamespace)(namespace, catalogs, {
+          cwd: ctx.root,
+          defaultNamespace,
+          keySeparator
+        });
+        for (const reason of loaded.errors) report(reason.split(":")[0] ?? reason, `Catalog could not be loaded: ${reason}.`);
+        keyed.push({ namespace, catalogs: loaded.catalogs });
+      }
+      if (violations.length > 0) return violations;
+      const reach = { exact: /* @__PURE__ */ new Set(), prefixes: /* @__PURE__ */ new Map(), literals: /* @__PURE__ */ new Set(), patterns: [] };
+      const files = globFiles((pattern) => ctx.glob(pattern), sourceGlobs, skipDirs);
+      if (files.length === 0) {
+        report(sourceGlobs.join(", "), "No source file matches `sourceGlobs`, so every key would look dead. Fix the globs.");
+        return violations;
+      }
+      const unparsed = collectReach(ctx, files, options, reach);
+      if (unparsed.length > 0) {
+        for (const file of unparsed) {
+          report(file, "Could not analyse this file (a parse error, or not a JS/TS file), so the keys it reaches are unknown. Dead-key analysis is skipped until every source file is analysable.");
+        }
+        return violations;
+      }
+      for (const { namespace, catalogs: sources } of keyed) {
+        for (const catalog of sources) {
+          for (const key of [...catalog.leaves].sort()) {
+            if (isReached(namespace, key, reach, nsSeparator, keySeparator)) continue;
+            const qualified = `${namespace}:${key}`;
+            if (allow.some((pattern) => pattern.test(qualified))) continue;
+            report(
+              catalog.label.split("#")[0] ?? catalog.label,
+              `Translation key \`${qualified}\` (${catalog.label}) is named by no translation call and spelled by no string in the source. Delete it, or add it to \`allow\` if it is reached from outside the scanned files.`
+            );
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createTranslationDeadKeysRule,
+  deriveNamespaces
+});

package/dist/i18n.d.cts

@@ -0,0 +1,60 @@
+import { IMetaRule, IMetaCtx } from '@noctcore/harness';
+import { TranslationKeyExistsOptions, CatalogSource } from '@noctcore/eslint-plugin-contracts';
+
+/**
+ * Options for {@link createTranslationDeadKeysRule}.
+ *
+ * Every resolution option (`defaultNamespace`, `hooks`, `namespaceIdentifiers`,
+ * separators, ...) is the SAME option `noctcore-contracts/translation-key-exists`
+ * takes, and is resolved by the same code, so the two checks cannot disagree on
+ * which key a call site means. Pass them the same values.
+ */
+interface TranslationDeadKeysOptions extends Omit<TranslationKeyExistsOptions, 'catalogs' | 'dynamicKeys'> {
+    /** Rule id, for running more than one instance. Default `translation-dead-keys`. */
+    readonly id?: string;
+    /**
+     * The catalogs whose keys must be reachable, in `translation-key-exists`'
+     * `CatalogSource` shape. List ONE language (the reference one): a key is dead
+     * or alive regardless of how many languages translate it. Empty = inert.
+     */
+    readonly catalogs?: readonly CatalogSource[];
+    /**
+     * The namespaces to check. Default: derived from `catalogs`, where a `{ns}`
+     * file segment is globbed and a trailing `{ns}` keyPath segment lists the
+     * object's keys. Required when a `{ns}` placeholder sits anywhere else.
+     */
+    readonly namespaces?: readonly string[];
+    /** Globs of every file that can reach a key (call sites AND key tables). Empty = inert. */
+    readonly sourceGlobs?: readonly string[];
+    /** Source paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /**
+     * `ns:key` patterns known to be reached from outside the scanned source
+     * (server-sent codes, a CMS, another app). `*` matches any run of characters.
+     */
+    readonly allow?: readonly string[];
+    /** Whether a dead key fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** The namespaces `catalogs` supply, or throws when a placeholder cannot be enumerated. */
+declare function deriveNamespaces(ctx: IMetaCtx, catalogs: readonly CatalogSource[], defaultNamespace: string): string[];
+/**
+ * Catalog keys nothing in the source can reach. A whole-program check, so it
+ * lives here and not in ESLint: a per-file rule never sees every call site, and
+ * keys flow as data (key tables, helper functions, server codes), which a
+ * call-site-only analysis cannot follow.
+ *
+ * CONSERVATIVE BY DESIGN. A key counts as reached when ANY of these holds:
+ *   - a translation call resolves to it (same visitor as `translation-key-exists`),
+ *   - a template key's static head is a prefix of it (`` t(`status.${s}`) ``),
+ *   - any string literal in the source equals it, `ns:key`, an ancestor of it,
+ *     or its plural/context base (`key` for `key_one`),
+ *   - any template literal or `+` chain in the source can produce it,
+ *   - it matches an `allow` pattern.
+ * And it reports NOTHING when a source file cannot be parsed. What is left was
+ * named by no call and spelled by no string: dead, or reached from outside the
+ * scanned source (see the rule doc's blind spots).
+ */
+declare function createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule;
+
+export { type TranslationDeadKeysOptions, createTranslationDeadKeysRule, deriveNamespaces };

package/dist/i18n.d.ts

@@ -0,0 +1,60 @@
+import { IMetaRule, IMetaCtx } from '@noctcore/harness';
+import { TranslationKeyExistsOptions, CatalogSource } from '@noctcore/eslint-plugin-contracts';
+
+/**
+ * Options for {@link createTranslationDeadKeysRule}.
+ *
+ * Every resolution option (`defaultNamespace`, `hooks`, `namespaceIdentifiers`,
+ * separators, ...) is the SAME option `noctcore-contracts/translation-key-exists`
+ * takes, and is resolved by the same code, so the two checks cannot disagree on
+ * which key a call site means. Pass them the same values.
+ */
+interface TranslationDeadKeysOptions extends Omit<TranslationKeyExistsOptions, 'catalogs' | 'dynamicKeys'> {
+    /** Rule id, for running more than one instance. Default `translation-dead-keys`. */
+    readonly id?: string;
+    /**
+     * The catalogs whose keys must be reachable, in `translation-key-exists`'
+     * `CatalogSource` shape. List ONE language (the reference one): a key is dead
+     * or alive regardless of how many languages translate it. Empty = inert.
+     */
+    readonly catalogs?: readonly CatalogSource[];
+    /**
+     * The namespaces to check. Default: derived from `catalogs`, where a `{ns}`
+     * file segment is globbed and a trailing `{ns}` keyPath segment lists the
+     * object's keys. Required when a `{ns}` placeholder sits anywhere else.
+     */
+    readonly namespaces?: readonly string[];
+    /** Globs of every file that can reach a key (call sites AND key tables). Empty = inert. */
+    readonly sourceGlobs?: readonly string[];
+    /** Source paths with any of these segments are skipped. Default `node_modules`, `.git`, `dist`, `.turbo`, `coverage`. */
+    readonly skipDirs?: readonly string[];
+    /**
+     * `ns:key` patterns known to be reached from outside the scanned source
+     * (server-sent codes, a CMS, another app). `*` matches any run of characters.
+     */
+    readonly allow?: readonly string[];
+    /** Whether a dead key fails CI. Default `true`. */
+    readonly ciCritical?: boolean;
+}
+/** The namespaces `catalogs` supply, or throws when a placeholder cannot be enumerated. */
+declare function deriveNamespaces(ctx: IMetaCtx, catalogs: readonly CatalogSource[], defaultNamespace: string): string[];
+/**
+ * Catalog keys nothing in the source can reach. A whole-program check, so it
+ * lives here and not in ESLint: a per-file rule never sees every call site, and
+ * keys flow as data (key tables, helper functions, server codes), which a
+ * call-site-only analysis cannot follow.
+ *
+ * CONSERVATIVE BY DESIGN. A key counts as reached when ANY of these holds:
+ *   - a translation call resolves to it (same visitor as `translation-key-exists`),
+ *   - a template key's static head is a prefix of it (`` t(`status.${s}`) ``),
+ *   - any string literal in the source equals it, `ns:key`, an ancestor of it,
+ *     or its plural/context base (`key` for `key_one`),
+ *   - any template literal or `+` chain in the source can produce it,
+ *   - it matches an `allow` pattern.
+ * And it reports NOTHING when a source file cannot be parsed. What is left was
+ * named by no call and spelled by no string: dead, or reached from outside the
+ * scanned source (see the rule doc's blind spots).
+ */
+declare function createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule;
+
+export { type TranslationDeadKeysOptions, createTranslationDeadKeysRule, deriveNamespaces };

package/dist/i18n.js

@@ -0,0 +1,266 @@
+import {
+  DEFAULT_SKIP_DIRS,
+  escapeRegExp,
+  globFiles
+} from "./chunk-Z7TXSZR4.js";
+
+// src/i18n/translation-dead-keys.ts
+import path from "path";
+import {
+  catalogsForNamespace,
+  createTranslationVisitor,
+  TRANSLATION_DEFAULTS,
+  translationSettingsOf
+} from "@noctcore/eslint-plugin-contracts";
+import * as tsParser from "@typescript-eslint/parser";
+import { AST_NODE_TYPES } from "@typescript-eslint/utils";
+import { Linter } from "eslint";
+var DEFAULT_ID = "translation-dead-keys";
+var NS_PLACEHOLDER = "{ns}";
+var SOURCE_FILES = ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts", "**/*.js", "**/*.jsx", "**/*.mjs", "**/*.cjs"];
+function namespacesFromFileTemplate(ctx, file) {
+  const segments = file.split("/");
+  if (segments.filter((segment) => segment.includes(NS_PLACEHOLDER)).length !== 1) return [];
+  const pattern = file.replaceAll(NS_PLACEHOLDER, "*");
+  const capture = new RegExp(
+    `^${file.split(NS_PLACEHOLDER).map((part) => escapeRegExp(part).replaceAll("\\*", "[^/]*")).join("([^/]+)")}$`,
+    "u"
+  );
+  const found = [];
+  for (const rel of ctx.glob(pattern)) {
+    const namespace = capture.exec(rel)?.[1];
+    if (namespace !== void 0) found.push(namespace);
+  }
+  return found;
+}
+function namespacesFromKeyPath(ctx, file, keyPath) {
+  const segments = keyPath.split(".");
+  if (segments.indexOf(NS_PLACEHOLDER) !== segments.length - 1) return null;
+  const text = ctx.read(file);
+  if (text === null) return [];
+  let node = JSON.parse(text);
+  for (const segment of segments.slice(0, -1)) {
+    if (node === null || typeof node !== "object" || !Object.hasOwn(node, segment)) return [];
+    node = node[segment];
+  }
+  return node !== null && typeof node === "object" ? Object.keys(node) : [];
+}
+function deriveNamespaces(ctx, catalogs, defaultNamespace) {
+  const found = /* @__PURE__ */ new Set();
+  for (const source of catalogs) {
+    const fileTemplated = source.file.includes(NS_PLACEHOLDER);
+    const keyPathTemplated = source.keyPath?.includes(NS_PLACEHOLDER) ?? false;
+    if (!fileTemplated && !keyPathTemplated) {
+      found.add(source.namespace ?? defaultNamespace);
+      continue;
+    }
+    const derived = fileTemplated ? namespacesFromFileTemplate(ctx, source.file) : namespacesFromKeyPath(ctx, source.file, source.keyPath ?? "");
+    if (derived === null || fileTemplated && keyPathTemplated) {
+      throw new Error(
+        `cannot enumerate the namespaces of catalog ${JSON.stringify(source)}: list them in \`namespaces\``
+      );
+    }
+    for (const namespace of derived) found.add(namespace);
+  }
+  return [...found].sort();
+}
+function holePattern(fragments) {
+  if (fragments.join("").replace(/[.:_\-/\s]/gu, "").length < 2) return null;
+  return new RegExp(`^${fragments.map(escapeRegExp).join(".*")}$`, "u");
+}
+function textFragments(root) {
+  const fragments = [""];
+  let sawText = false;
+  const hole = () => {
+    if (fragments.length === 1 || fragments[fragments.length - 1] !== "") fragments.push("");
+  };
+  const text = (value) => {
+    sawText = true;
+    fragments[fragments.length - 1] += value;
+  };
+  const visit = (node) => {
+    if (node.type === AST_NODE_TYPES.BinaryExpression && node.operator === "+") {
+      visit(node.left);
+      visit(node.right);
+    } else if (node.type === AST_NODE_TYPES.Literal && typeof node.value === "string") {
+      text(node.value);
+    } else if (node.type === AST_NODE_TYPES.TemplateLiteral) {
+      node.quasis.forEach((quasi, index) => {
+        if (index > 0) hole();
+        text(quasi.value.cooked ?? "");
+      });
+    } else {
+      hole();
+    }
+  };
+  visit(root);
+  return sawText ? fragments : null;
+}
+function collectReach(ctx, files, options, reach) {
+  const settings = translationSettingsOf(options);
+  const fallbackNamespaces = options.fallbackNamespaces ?? [];
+  const keySeparator = settings.keySeparator;
+  const addPrefix = (namespace, prefix) => {
+    reach.prefixes.set(namespace, [...reach.prefixes.get(namespace) ?? [], prefix]);
+  };
+  const onUsage = (usage) => {
+    if (usage.kind === "key") {
+      for (const namespace of [...usage.namespaces, ...fallbackNamespaces]) {
+        for (const key of usage.keys) {
+          reach.exact.add(`${namespace}\0${key}`);
+          if (usage.returnObjects && keySeparator !== false) addPrefix(namespace, `${key}${keySeparator}`);
+        }
+      }
+    } else if (usage.kind === "prefix") {
+      for (const namespace of [...usage.namespaces, ...fallbackNamespaces]) addPrefix(namespace, usage.prefix);
+    }
+  };
+  const addText = (node) => {
+    const fragments = textFragments(node);
+    if (fragments === null) return;
+    if (fragments.length === 1) {
+      if (fragments[0] !== "") reach.literals.add(fragments[0] ?? "");
+      return;
+    }
+    const pattern = holePattern(fragments);
+    if (pattern !== null) reach.patterns.push(pattern);
+  };
+  const collector = {
+    defaultOptions: [],
+    meta: { type: "problem", schema: [], messages: { never: "never reported" } },
+    create(context) {
+      return {
+        ...createTranslationVisitor(context, settings, onUsage),
+        Literal(node) {
+          if (typeof node.value === "string" && node.value !== "") reach.literals.add(node.value);
+        },
+        TemplateLiteral(node) {
+          if (!isConcatOperand(node)) addText(node);
+        },
+        BinaryExpression(node) {
+          if (node.operator === "+" && !isConcatOperand(node)) addText(node);
+        }
+      };
+    }
+  };
+  const linter = new Linter({ cwd: ctx.root });
+  const config = [
+    {
+      // Not `**/*`: flat config treats a match-everything pattern as universal
+      // and applies it to no file on its own.
+      files: SOURCE_FILES,
+      languageOptions: {
+        parser: tsParser,
+        parserOptions: { ecmaFeatures: { jsx: true } }
+      },
+      linterOptions: { reportUnusedDisableDirectives: "off" },
+      plugins: { deadKeys: { rules: { collect: collector } } },
+      rules: { "deadKeys/collect": "error" }
+    }
+  ];
+  const unparsed = [];
+  for (const file of files) {
+    const text = ctx.read(file);
+    if (text === null) continue;
+    const messages = linter.verify(text, config, { filename: path.join(ctx.root, file) });
+    if (messages.some((message) => message.ruleId === null)) unparsed.push(file);
+  }
+  return unparsed;
+}
+function isConcatOperand(node) {
+  const parent = node.parent;
+  return parent?.type === AST_NODE_TYPES.BinaryExpression && parent.operator === "+";
+}
+function allowPatterns(allow) {
+  return allow.map((pattern) => new RegExp(`^${pattern.split("*").map(escapeRegExp).join(".*")}$`, "u"));
+}
+function lookupForms(key, keySeparator) {
+  const forms = [key];
+  const lastSegmentStart = keySeparator === false ? 0 : key.lastIndexOf(keySeparator) + 1;
+  let base = key;
+  while (base.lastIndexOf("_") > lastSegmentStart) {
+    base = base.slice(0, base.lastIndexOf("_"));
+    forms.push(base);
+  }
+  return forms;
+}
+function isReached(namespace, key, reach, nsSeparator, keySeparator) {
+  for (const prefix of reach.prefixes.get(namespace) ?? []) {
+    if (key.startsWith(prefix)) return true;
+  }
+  const texts = [];
+  for (const form of lookupForms(key, keySeparator)) {
+    if (reach.exact.has(`${namespace}\0${form}`)) return true;
+    texts.push(form);
+    if (nsSeparator !== false) texts.push(`${namespace}${nsSeparator}${form}`);
+  }
+  if (texts.some((text) => reach.literals.has(text))) return true;
+  return reach.patterns.some((pattern) => texts.some((text) => pattern.test(text)));
+}
+function createTranslationDeadKeysRule(options = {}) {
+  const id = options.id ?? DEFAULT_ID;
+  const catalogs = options.catalogs ?? [];
+  const sourceGlobs = options.sourceGlobs ?? [];
+  const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
+  const allow = allowPatterns(options.allow ?? []);
+  const ciCritical = options.ciCritical ?? true;
+  const defaultNamespace = options.defaultNamespace ?? TRANSLATION_DEFAULTS.defaultNamespace;
+  const nsSeparator = options.nsSeparator ?? TRANSLATION_DEFAULTS.nsSeparator;
+  const keySeparator = options.keySeparator ?? TRANSLATION_DEFAULTS.keySeparator;
+  return {
+    id,
+    category: "source-text",
+    ciCritical,
+    description: "Every translation catalog key must be reachable from the source: named by a translation call, or spelled by some string in the code.",
+    run(ctx) {
+      if (catalogs.length === 0 || sourceGlobs.length === 0) return [];
+      const violations = [];
+      const report = (file, message) => {
+        violations.push({ file, rule: id, message });
+      };
+      const namespaces = options.namespaces ?? deriveNamespaces(ctx, catalogs, defaultNamespace);
+      const keyed = [];
+      for (const namespace of namespaces) {
+        const loaded = catalogsForNamespace(namespace, catalogs, {
+          cwd: ctx.root,
+          defaultNamespace,
+          keySeparator
+        });
+        for (const reason of loaded.errors) report(reason.split(":")[0] ?? reason, `Catalog could not be loaded: ${reason}.`);
+        keyed.push({ namespace, catalogs: loaded.catalogs });
+      }
+      if (violations.length > 0) return violations;
+      const reach = { exact: /* @__PURE__ */ new Set(), prefixes: /* @__PURE__ */ new Map(), literals: /* @__PURE__ */ new Set(), patterns: [] };
+      const files = globFiles((pattern) => ctx.glob(pattern), sourceGlobs, skipDirs);
+      if (files.length === 0) {
+        report(sourceGlobs.join(", "), "No source file matches `sourceGlobs`, so every key would look dead. Fix the globs.");
+        return violations;
+      }
+      const unparsed = collectReach(ctx, files, options, reach);
+      if (unparsed.length > 0) {
+        for (const file of unparsed) {
+          report(file, "Could not analyse this file (a parse error, or not a JS/TS file), so the keys it reaches are unknown. Dead-key analysis is skipped until every source file is analysable.");
+        }
+        return violations;
+      }
+      for (const { namespace, catalogs: sources } of keyed) {
+        for (const catalog of sources) {
+          for (const key of [...catalog.leaves].sort()) {
+            if (isReached(namespace, key, reach, nsSeparator, keySeparator)) continue;
+            const qualified = `${namespace}:${key}`;
+            if (allow.some((pattern) => pattern.test(qualified))) continue;
+            report(
+              catalog.label.split("#")[0] ?? catalog.label,
+              `Translation key \`${qualified}\` (${catalog.label}) is named by no translation call and spelled by no string in the source. Delete it, or add it to \`allow\` if it is reached from outside the scanned files.`
+            );
+          }
+        }
+      }
+      return violations;
+    }
+  };
+}
+export {
+  createTranslationDeadKeysRule,
+  deriveNamespaces
+};

package/dist/index.js

@@ -1,52 +1,16 @@
-// src/rules/shared.ts
-function dirOf(rel, basename = "package.json") {
-  return rel.replace(new RegExp(`/${escapeRegExp(basename)}$`), "");
-}
-function baseName(pathLike) {
-  const parts = pathLike.split("/").filter(Boolean);
-  return parts[parts.length - 1] ?? pathLike;
-}
-function escapeRegExp(value) {
-  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function countLines(text) {
-  const lines = text.split("\n");
-  if (lines[lines.length - 1] === "") lines.pop();
-  return lines.length;
-}
-function recursiveGlobs(roots, extensions) {
-  return roots.flatMap((root) => extensions.map((ext) => `${root}/**/*${ext}`));
-}
-var DEFAULT_WORKFLOW_GLOBS = [
-  ".github/workflows/*.yml",
-  ".github/workflows/*.yaml"
-];
-var DEFAULT_SKIP_DIRS = [
-  "node_modules",
-  ".git",
-  "dist",
-  ".turbo",
-  "coverage"
-];
-function globFiles(glob, globs, skipDirs = []) {
-  const skip = new Set(skipDirs);
-  const found = /* @__PURE__ */ new Set();
-  for (const pattern of globs) {
-    for (const rel of glob(pattern)) {
-      if (!rel.split("/").some((segment) => skip.has(segment))) found.add(rel);
-    }
-  }
-  return [...found].sort();
-}
-function stripYamlComment(line) {
-  return line.replace(/(^|\s)#.*$/u, "");
-}
-function unquote(value) {
-  return value.trim().replace(/^(['"])(.*)\1$/u, "$2");
-}
-function anywhereGlobs(baseNames) {
-  return baseNames.flatMap((name) => [`**/${name}`, `**/.*/**/${name}`]);
-}
+import {
+  DEFAULT_SKIP_DIRS,
+  DEFAULT_WORKFLOW_GLOBS,
+  anywhereGlobs,
+  baseName,
+  countLines,
+  dirOf,
+  escapeRegExp,
+  globFiles,
+  recursiveGlobs,
+  stripYamlComment,
+  unquote
+} from "./chunk-Z7TXSZR4.js";
 
 // src/rules/agents-doc-presence.ts
 function createAgentsDocPresenceRule(options = {}) {

package/docs/rules/translation-dead-keys.md

@@ -0,0 +1,98 @@
+# `translation-dead-keys`
+
+> Every translation catalog key is reachable from the source: named by a translation call, or spelled
+> by some string in the code.
+
+Import it from the `i18n` entry point, which (unlike the main one) loads ESLint:
+
+```ts
+import { createTranslationDeadKeysRule } from '@noctcore/lint-meta-rules/i18n';
+```
+
+## Why
+
+A catalog key nothing uses is still translated, reviewed and shipped in every language. Finding them is
+a whole-program question, so it is not an ESLint rule: a per-file rule never sees every call site
+(editor runs, `--cache`, lint-staged, sharded workers), and keys flow as data (key tables, key-building
+helpers, server-sent codes) that no call-site analysis follows.
+
+This rule resolves call sites with the same visitor and catalog loader as
+`noctcore-contracts/translation-key-exists` (exported by `@noctcore/eslint-plugin-contracts`), so the
+two checks never disagree on which key a call means. It then adds the data routes a per-file rule
+cannot see.
+
+## What counts as reached
+
+A key is reached, and never reported, when ANY of these holds:
+
+- a translation call resolves to it: `t('key')`, `t('ns:key')`, `t('key', { ns })`,
+  `useTranslation('ns', { keyPrefix })`, `<Trans i18nKey>`, a `TFunction<'ns'>` parameter, the
+  `fallbackNamespaces`;
+- a template key's static head is a prefix of it: `` t(`status.${s}`) `` reaches every `status.*`;
+- a `returnObjects` call names one of its ancestors;
+- ANY string literal in the scanned source equals the key, `ns:key`, or its plural/context base
+  (`key` reaches `key_one`, `key_ordinal_few`, `key_male`), in any namespace;
+- ANY template literal or `+` chain in the scanned source can produce it:
+  `` `nav.${id}.label` `` and `'errors.' + code` are patterns, not just call arguments;
+- it matches an `allow` pattern.
+
+And it reports **no dead key at all** when a scanned file cannot be analysed (a parse error), or when
+`sourceGlobs` match nothing: in both cases the rule would otherwise call reached keys dead.
+
+What is left was named by no call and spelled by no string. On a production app with 1,824 keys this
+reported 55, and every one of them had zero references outside the catalogs.
+
+## Blind spots
+
+It is conservative, not complete. It reports a reached key as dead when the key arrives by a route it
+cannot see:
+
+- **Keys that never appear in the scanned source**: server-sent codes, a CMS, another app, JSON
+  config. List them in `allow`, or add the files that spell them to `sourceGlobs`.
+- **A variable key under a `keyPrefix` binding**: `useTranslation('ns', { keyPrefix: 'form' })` then
+  `t(field)` with `field = 'name'` reaches `form.name`, but no string spells `form.name`. (A static key
+  under a `keyPrefix` is resolved correctly.)
+- **Keys built by anything other than `+` or a template literal**: `[a, b].join('.')`,
+  `` `${a}` `` split across variables, `String.prototype.concat`.
+
+It also misses some dead keys, by design: any string that happens to equal a key (in any namespace)
+keeps it alive, and a broad pattern such as `` `${x}.title` `` keeps every `*.title` alive.
+
+## Factory
+
+```ts
+createTranslationDeadKeysRule(options?: TranslationDeadKeysOptions): IMetaRule
+```
+
+Inert until both `catalogs` and `sourceGlobs` are set; there are no built-in paths.
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `catalogs` | `CatalogSource[]` | `[]` | The catalogs to check, in `translation-key-exists`' shape (`{ file, namespace?, keyPath? }`, `{ns}` placeholders allowed). List ONE language: a key is dead or alive regardless of how many languages translate it. |
+| `sourceGlobs` | `string[]` | `[]` | Every file that can reach a key: call sites AND key tables. Include tests if a key used only by a test should count as alive. |
+| `namespaces` | `string[]` | derived | The namespaces to check. Derived from `catalogs`: a `{ns}` file segment is globbed, a trailing `{ns}` keyPath segment lists the object's keys. Required when a `{ns}` sits anywhere else. |
+| `allow` | `string[]` | `[]` | `ns:key` patterns reached from outside the scanned source; `*` matches any run of characters. |
+| `skipDirs` | `string[]` | `['node_modules', '.git', 'dist', '.turbo', 'coverage']` | Source paths with any of these segments are skipped. |
+| `id` | `string` | `'translation-dead-keys'` | Rule id, for running more than one instance. |
+| `ciCritical` | `boolean` | `true` | Whether a dead key fails CI. |
+
+Every resolution option of `translation-key-exists` is accepted and means the same thing:
+`defaultNamespace`, `fallbackNamespaces`, `hooks`, `instances`, `functions`, `typeNames`,
+`transComponents`, `namespaceIdentifiers`, `nsSeparator`, `keySeparator`. Pass them the same values.
+
+```ts
+createTranslationDeadKeysRule({
+  catalogs: [
+    { file: 'apps/web/src/lib/i18n/locales/pl.json', keyPath: '{ns}' },
+    { file: 'apps/web/src/features/{ns}/locales/pl.json' },
+  ],
+  defaultNamespace: 'common',
+  namespaceIdentifiers: { HELP_NS: 'help' },
+  sourceGlobs: ['apps/web/src/**/*.ts', 'apps/web/src/**/*.tsx'],
+});
+```
+
+## Requirements
+
+The `i18n` entry needs the optional peers `eslint` (>= 9) and `@typescript-eslint/parser`. Scanned
+files are parsed as TypeScript with JSX enabled, without type information.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noctcore/lint-meta-rules",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Portable, parameterized lint-meta rules — whole-repo / cross-file invariants ESLint cannot reach — for the @noctcore/harness lint-meta runner.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,11 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./i18n": {
+      "types": "./dist/i18n.d.ts",
+      "import": "./dist/i18n.js",
+      "require": "./dist/i18n.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -41,15 +46,31 @@
   "homepage": "https://github.com/noctcore/eslint-plugins/tree/main/packages/lint-meta-rules",
   "bugs": "https://github.com/noctcore/eslint-plugins/issues",
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "build": "tsup src/index.ts src/i18n.ts --format esm,cjs --dts --clean",
     "typecheck": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
-    "@noctcore/harness": "^0.3.0"
+    "@noctcore/eslint-plugin-contracts": "^0.5.0",
+    "@noctcore/harness": "^0.3.0",
+    "@typescript-eslint/utils": "^8.61.1"
+  },
+  "peerDependencies": {
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": ">=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@typescript-eslint/parser": {
+      "optional": true
+    },
+    "eslint": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "eslint": "^10.7.0",
     "tsup": "^8.5.1",
     "typescript": "^5.6.0"
   }