@noctcore/lint-meta-rules 0.1.0 → 0.3.0

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
+};