@noctcore/lint-meta-rules 0.1.0 → 0.3.0

package/README.md

@@ -44,7 +44,8 @@ over the whole catalog.
 
 13 nightcore lint-meta rules are ported as 12 factories — nightcore's `web-file-size-ratchet` and
 `engine-file-size-ratchet` were byte-identical logic and collapse into a single
-`createFileSizeRatchetRule` (instantiated once per capped area).
+`createFileSizeRatchetRule` (instantiated once per capped area). Five CI-hygiene rules (category
+`ci`) are ported from a production NestJS + Vite monorepo, one factory each, for 17 factories in all.
 
 | Factory | Source rule(s) | Category | What it enforces |
 | --- | --- | --- | --- |
@@ -60,6 +61,23 @@ over the whole catalog.
 | [`createUiPrimitiveShapeRule`](./docs/rules/ui-primitive-shape.md) | `ui-primitive-shape` | source-text | A folder primitive ships its proof siblings; a flat primitive carries none at the ui root. |
 | [`createTestWorkspaceEnrollmentRule`](./docs/rules/test-workspace-enrollment.md) | `test-workspace-enrollment` | testing | Every tested package is enumerated in the aggregate test script. |
 | [`createTestRunnerSegregationRule`](./docs/rules/test-runner-segregation.md) | `test-runner-segregation` | testing | Bun-side and foreign-side test runners are never mixed within a package. |
+| [`createGithubActionsShaPinnedRule`](./docs/rules/github-actions-sha-pinned.md) | `github-actions-sha-pinned` | ci | Workflow `uses:` refs are pinned to a full commit SHA with a `# vN` comment. |
+| [`createGithubActionsRunnerPinnedRule`](./docs/rules/github-actions-runner-pinned.md) | `github-actions-runner-pinned` | ci | Workflow jobs run on a named runner image, never a `*-latest` label. |
+| [`createServiceImageDigestPinRule`](./docs/rules/service-image-digest-pin.md) | `service-image-digest-pin` | ci | Workflow service/container images and compose images are pinned by `@sha256:` digest. |
+| [`createDockerfileBaseImageDigestPinRule`](./docs/rules/dockerfile-base-image-digest-pin.md) | `dockerfile-base-image-digest-pin` | ci | Dockerfile `FROM` base images are pinned by `@sha256:` digest. |
+| [`createSecurityScannerVersionParityRule`](./docs/rules/security-scanner-version-parity.md) | `security-scanner-version-parity` | ci | CI and the local pre-push hook pin the same secret-scanner version, and the hook checks it at run time. |
 
 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 };