localization-drift 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-10-13
+
+### Added
+
+- `--fix` annotates every reported finding with the exception marker and a
+  `TODO: localize` reason. All edits are computed before the first write, line
+  endings and indentation are preserved, a second run changes nothing, and the
+  edited files are summarized on stderr. Inside JSX children the marker is
+  written as a JSX comment.
+- Configuration field `allowlist` suppresses findings whose message text
+  matches a `pattern` entry that carries a non-empty `reason`. An invalid
+  regular expression or a missing reason is a configuration error and exits
+  with status 2.
+- `--sarif` prints one SARIF 2.1.0 document instead of text lines.
+- The sibling exception marker
+  `// localization-audit: allow-next-line -- <reason>` is accepted in addition
+  to the configured `localization-drift` marker.
+- The JSX comment marker form (`{/* localization-drift: allow-next-line -- <reason> */}`)
+  is accepted and used by `--fix` inside JSX children.

package/README.md

@@ -7,6 +7,10 @@ Fail a build when customer-visible text bypasses translation keys.
 - Flags hardcoded JSX text and localized attributes in `.tsx` files.
 - Flags configured forbidden patterns in the scanned source files.
 - Honors a reviewed exception comment on the line before a finding.
+- Annotates findings with `--fix` so an adopted codebase can go green and
+  triage the annotated debt.
+- Suppresses reviewed message text through an allowlist.
+- Prints text lines, JSON, or one SARIF 2.1.0 document.
 - Runs as a CLI, an npm package, or a GitHub Action.
 - Pairs with [localize](https://github.com/m1chlcz/localize) for the workbook and ARB side.
 
@@ -23,10 +27,42 @@ Node.js 22 or later is required.
 ```
 npx localization-drift
 npx localization-drift --root app --root components
+npx localization-drift --fix
 npx localization-drift --json
+npx localization-drift --sarif > localization-drift.sarif
 ```
 
-The output is one line per finding: `path:line: kind: message`. The exit code is 1 for findings and 2 for a usage or configuration error.
+The output is one line per finding: `path:line: kind: message`. The exit code
+is 1 for findings and 2 for a usage or configuration error. `--json` and
+`--sarif` are mutually exclusive. Combined with `--fix`, they print the
+findings that remain after the fix.
+
+## Fix
+
+`--fix` adds the exception marker with a `TODO: localize` reason on the line
+before every reported finding. The audit passes at once and the annotated debt
+stays visible for triage.
+
+- Every edit is computed before the first write. A failure leaves the tree
+  untouched.
+- The file line endings and the indentation of the annotated line are
+  preserved.
+- A line that already carries a marker is never touched.
+- A second run changes nothing.
+- Inside JSX children the marker is a JSX comment (`{/* ... */}`) so the file
+  stays valid.
+- The summary goes to stderr, one line per edited file plus a total.
+  `Localization audit passed.` goes to stdout when no finding remains.
+- The exit code is 0 when no finding remains and 1 when a finding cannot be
+  annotated.
+
+## SARIF
+
+`--sarif` prints one SARIF 2.1.0 document to stdout instead of text lines. The
+document has one run, the driver name is `localization-drift`, the version
+comes from `package.json`, and the information URI comes from the `repository`
+field. Every finding becomes one `error` result with a rule id, the message
+text, and the file and line. The exit codes do not change.
 
 ## Configuration
 
@@ -43,6 +79,12 @@ Create `localization-drift.json` in the repository root:
       "pattern": "widget_type\\s*===\\s*[\"'][^\"']+[\"']",
       "message": "use stored capabilities instead of a widget value"
     }
+  ],
+  "allowlist": [
+    {
+      "pattern": "customer-visible title must come from a translation key",
+      "reason": "page titles are rendered from stored content"
+    }
   ]
 }
 ```
@@ -54,7 +96,8 @@ Create `localization-drift.json` in the repository root:
 | `attributes` | `["alt", "aria-label", "placeholder", "title"]` | The JSX attributes that must use a key. |
 | `exclude` | tests, `/generated/`, `node_modules` | Regular expressions for paths to skip. |
 | `forbidden` | `[]` | Regular expression rules with a message. |
-| `allowComment` | the marker below | The exception marker prefix. |
+| `allowlist` | `[]` | Suppresses findings whose message matches `pattern`. Every entry needs a non-empty `reason`. An invalid pattern is a configuration error. |
+| `allowComment` | the marker below | The exception marker prefix. The sibling `localization-audit` marker is always accepted on top. |
 
 ## Exception
 
@@ -65,6 +108,22 @@ Put the marker and a reason on the line before the finding:
 <strong>WhatsApp</strong>
 ```
 
+Inside JSX children use a JSX comment:
+
+```tsx
+{/* localization-drift: allow-next-line -- registered brand name */}
+<strong>WhatsApp</strong>
+```
+
+The audit also accepts the sibling marker
+`// localization-audit: allow-next-line -- <reason>` in both forms, so a shop
+that already carries those comments adopts this tool with a configuration-only
+change.
+
+The inline exception comment wins first. The allowlist suppresses the findings
+that remain: an allowlisted finding is not reported and `--fix` does not
+annotate it.
+
 ## GitHub Action
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "localization-drift",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Fail a build when customer-visible text bypasses translation keys.",
   "type": "module",
   "license": "MIT",
@@ -31,6 +31,7 @@
     "src",
     "action.yml",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {

package/src/cli.mjs

@@ -4,16 +4,20 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 
-import { scanRepository } from "./index.mjs";
+import { fixRepository, scanRepository } from "./index.mjs";
+import { buildSarif } from "./sarif.mjs";
 
-const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+const version = manifest.version;
 
 const usage = `Usage: localization-drift [options]
 
 Options:
   --config FILE    read a JSON configuration file
   --root DIR       scan DIR (repeatable; overrides the configured roots)
+  --fix            annotate findings with a TODO: localize marker
   --json           print the findings as JSON
+  --sarif          print the findings as one SARIF 2.1.0 document
   -h, --help       show this help
   -v, --version    show the version`;
 
@@ -28,13 +32,31 @@ function readConfig(path, required) {
   }
 }
 
+function printFindings(findings) {
+  for (const item of findings) {
+    process.stderr.write(`${item.path}:${item.line}: ${item.kind}: ${item.message}\n`);
+  }
+  process.stderr.write(`${findings.length} localization finding(s).\n`);
+}
+
+function printFixSummary(files) {
+  let markers = 0;
+  for (const file of files) {
+    markers += file.annotated;
+    process.stderr.write(`annotated ${file.path}: ${file.annotated} marker(s)\n`);
+  }
+  process.stderr.write(`${files.length} file(s) annotated, ${markers} marker(s) with TODO: localize.\n`);
+}
+
 async function main() {
   const { values } = parseArgs({
     args: process.argv.slice(2),
     options: {
       config: { type: "string" },
       root: { type: "string", multiple: true },
+      fix: { type: "boolean" },
       json: { type: "boolean" },
+      sarif: { type: "boolean" },
       help: { type: "boolean", short: "h" },
       version: { type: "boolean", short: "v" },
     },
@@ -48,6 +70,9 @@ async function main() {
     process.stdout.write(`${usage}\n`);
     return;
   }
+  if (values.json && values.sarif) {
+    throw new Error("--json and --sarif are mutually exclusive");
+  }
 
   const root = process.cwd();
   const config = values.config
@@ -55,16 +80,21 @@ async function main() {
     : readConfig(resolve(root, "localization-drift.json"), false);
   if (values.root?.length) config.roots = values.root;
 
-  const findings = await scanRepository(root, config);
-  if (values.json) {
+  const result = values.fix
+    ? await fixRepository(root, config)
+    : { files: [], findings: await scanRepository(root, config) };
+  if (result.files.length > 0) printFixSummary(result.files);
+
+  const { findings } = result;
+  if (values.sarif) {
+    const document = buildSarif(findings, { version, repository: manifest.repository });
+    process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
+  } else if (values.json) {
     process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`);
   } else if (findings.length === 0) {
     process.stdout.write("Localization audit passed.\n");
   } else {
-    for (const item of findings) {
-      process.stderr.write(`${item.path}:${item.line}: ${item.kind}: ${item.message}\n`);
-    }
-    process.stderr.write(`${findings.length} localization finding(s).\n`);
+    printFindings(findings);
   }
   if (findings.length > 0) process.exitCode = 1;
 }

package/src/index.mjs

@@ -1,8 +1,10 @@
-import { readFile, readdir } from "node:fs/promises";
+import { readFile, readdir, writeFile } from "node:fs/promises";
 import { extname, join, relative, sep } from "node:path";
 import ts from "typescript";
 
 export const ALLOW_COMMENT = "// localization-drift: allow-next-line -- ";
+export const SIBLING_ALLOW_COMMENT = "// localization-audit: allow-next-line -- ";
+export const FIX_REASON = "TODO: localize";
 
 export const DEFAULT_CONFIG = Object.freeze({
   roots: ["src"],
@@ -10,6 +12,7 @@ export const DEFAULT_CONFIG = Object.freeze({
   attributes: ["alt", "aria-label", "placeholder", "title"],
   exclude: ["\\.test\\.", "/test/", "/generated/", "node_modules", "\\.d\\.ts$"],
   forbidden: [],
+  allowlist: [],
 });
 
 function lineDetails(source, index) {
@@ -23,8 +26,23 @@ function lineDetails(source, index) {
   };
 }
 
-function reviewedException(source, index, allowComment) {
-  return lineDetails(source, index).previous.startsWith(allowComment);
+function commentBody(line) {
+  if (line.startsWith("//")) return line.slice(2).trimStart();
+  if (line.startsWith("{/*") && line.endsWith("*/}")) return line.slice(3, -3).trim();
+  if (line.startsWith("/*") && line.endsWith("*/")) return line.slice(2, -2).trim();
+  return null;
+}
+
+function markerPrefixMatches(line, prefix) {
+  if (line.startsWith(prefix)) return true;
+  if (!prefix.startsWith("// ")) return false;
+  const body = commentBody(line);
+  return body !== null && body.startsWith(prefix.slice(3));
+}
+
+function reviewedException(source, index, allowComments) {
+  const previous = lineDetails(source, index).previous;
+  return allowComments.some((prefix) => markerPrefixMatches(previous, prefix));
 }
 
 function finding(path, source, index, kind, message) {
@@ -43,6 +61,7 @@ export function analyzeSource(path, source, options = {}) {
     forbidden = [],
     allowComment = ALLOW_COMMENT,
   } = options;
+  const allowComments = [allowComment, SIBLING_ALLOW_COMMENT];
   const localizedAttributes = new Set(attributes);
   const indexed = [];
 
@@ -54,7 +73,7 @@ export function analyzeSource(path, source, options = {}) {
           node.initializer && ts.isStringLiteral(node.initializer) &&
           /\p{L}/u.test(node.initializer.text)) {
         const index = node.getStart(sourceFile);
-        if (!reviewedException(source, index, allowComment)) {
+        if (!reviewedException(source, index, allowComments)) {
           indexed.push({
             index,
             finding: finding(
@@ -70,7 +89,7 @@ export function analyzeSource(path, source, options = {}) {
       if (ts.isJsxText(node)) {
         const value = node.getText(sourceFile).replace(/\s+/g, " ").trim();
         const index = node.getStart(sourceFile);
-        if (value && /\p{L}/u.test(value) && !reviewedException(source, index, allowComment)) {
+        if (value && /\p{L}/u.test(value) && !reviewedException(source, index, allowComments)) {
           indexed.push({
             index,
             finding: finding(
@@ -92,7 +111,7 @@ export function analyzeSource(path, source, options = {}) {
     if (!rule || typeof rule.pattern !== "string" || typeof rule.message !== "string") continue;
     const pattern = new RegExp(rule.pattern, "g");
     for (const match of source.matchAll(pattern)) {
-      if (reviewedException(source, match.index, allowComment)) continue;
+      if (reviewedException(source, match.index, allowComments)) continue;
       indexed.push({
         index: match.index,
         finding: finding(path, source, match.index, "forbidden-pattern", rule.message),
@@ -105,6 +124,29 @@ export function analyzeSource(path, source, options = {}) {
     .map(({ finding: result }) => result);
 }
 
+function compileAllowlist(allowlist) {
+  if (!Array.isArray(allowlist)) {
+    throw new Error("allowlist must be an array of { pattern, reason } entries");
+  }
+  return allowlist.map((entry, index) => {
+    if (!entry || typeof entry.pattern !== "string") {
+      throw new Error(`allowlist[${index}].pattern must be a string`);
+    }
+    if (typeof entry.reason !== "string" || entry.reason.trim() === "") {
+      throw new Error(`allowlist[${index}].reason must be a non-empty string`);
+    }
+    try {
+      return { pattern: new RegExp(entry.pattern), reason: entry.reason };
+    } catch {
+      throw new Error(`allowlist[${index}].pattern is not a valid regular expression: ${entry.pattern}`);
+    }
+  });
+}
+
+function allowlisted(item, allowlist) {
+  return allowlist.some((rule) => rule.pattern.test(item.message));
+}
+
 function excludedPath(path, exclude) {
   return exclude.some((pattern) => new RegExp(pattern).test(path));
 }
@@ -128,33 +170,155 @@ async function* walk(directory, config) {
   }
 }
 
-/**
- * scanRepository walks the configured roots and returns every finding, sorted
- * by path and line.
- */
-export async function scanRepository(root, config = {}) {
-  const settings = {
+function compileSettings(config = {}) {
+  return {
     roots: config.roots ?? DEFAULT_CONFIG.roots,
     extensions: config.extensions ?? DEFAULT_CONFIG.extensions,
     attributes: config.attributes ?? DEFAULT_CONFIG.attributes,
     exclude: config.exclude ?? DEFAULT_CONFIG.exclude,
     forbidden: config.forbidden ?? DEFAULT_CONFIG.forbidden,
     allowComment: config.allowComment ?? ALLOW_COMMENT,
+    allowlist: compileAllowlist(config.allowlist ?? DEFAULT_CONFIG.allowlist),
   };
-  const findings = [];
+}
+
+function analysisOptions(settings) {
+  return {
+    attributes: settings.attributes,
+    forbidden: settings.forbidden,
+    allowComment: settings.allowComment,
+  };
+}
+
+async function* repositorySources(root, settings) {
   for (const directory of settings.roots) {
     for await (const absolute of walk(join(root, directory), settings)) {
       const path = relative(root, absolute).split(sep).join("/");
       if (excludedPath(path, settings.exclude)) continue;
-      const source = await readFile(absolute, "utf8");
-      findings.push(...analyzeSource(path, source, {
-        attributes: settings.attributes,
-        forbidden: settings.forbidden,
-        allowComment: settings.allowComment,
-      }));
+      yield { path, absolute, source: await readFile(absolute, "utf8") };
     }
   }
+}
+
+function sortFindings(findings) {
   return findings.sort((left, right) =>
     left.path.localeCompare(right.path) || left.line - right.line
   );
 }
+
+/**
+ * scanRepository walks the configured roots and returns every finding, sorted
+ * by path and line. Allowlisted messages are removed.
+ */
+export async function scanRepository(root, config = {}) {
+  const settings = compileSettings(config);
+  const options = analysisOptions(settings);
+  const findings = [];
+  for await (const file of repositorySources(root, settings)) {
+    findings.push(...analyzeSource(file.path, file.source, options)
+      .filter((item) => !allowlisted(item, settings.allowlist)));
+  }
+  return sortFindings(findings);
+}
+
+function splitLines(source) {
+  const eol = source.includes("\r\n") ? "\r\n" : "\n";
+  const endsWithEol = source.endsWith("\n");
+  const lines = source.split(/\r?\n/);
+  if (endsWithEol) lines.pop();
+  return { eol, endsWithEol, lines };
+}
+
+function isMarkerLine(line, allowComments) {
+  const trimmed = line.trim();
+  return allowComments.some((prefix) => markerPrefixMatches(trimmed, prefix));
+}
+
+function applyMarkers(source, markers) {
+  const { eol, endsWithEol, lines } = splitLines(source);
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const marker = markers.get(index + 1);
+    if (marker !== undefined) result.push(marker);
+    result.push(lines[index]);
+  }
+  return result.join(eol) + (endsWithEol ? eol : "");
+}
+
+function markerForms(allowComment) {
+  const forms = [`${allowComment}${FIX_REASON}`];
+  if (allowComment.startsWith("// ")) {
+    forms.push(`{/* ${allowComment.slice(3)}${FIX_REASON} */}`);
+  }
+  return forms;
+}
+
+function chooseMarker(path, source, options, allowComments, item, total) {
+  const { lines } = splitLines(source);
+  const target = lines[item.line - 1] ?? "";
+  if (isMarkerLine(target, allowComments)) return null;
+  if (isMarkerLine(lines[item.line - 2] ?? "", allowComments)) return null;
+  const indentation = /^[ \t]*/.exec(target)[0];
+  for (const form of markerForms(options.allowComment)) {
+    const marker = `${indentation}${form}`;
+    const candidate = applyMarkers(source, new Map([[item.line, marker]]));
+    const introduced = analyzeSource(path, candidate, options);
+    const markerIsFinding = introduced.some((candidateFinding) => candidateFinding.text === marker.trim());
+    if (!markerIsFinding && introduced.length < total) return marker;
+  }
+  return null;
+}
+
+function fixSource(path, source, options, allowlist) {
+  const allowComments = [options.allowComment, SIBLING_ALLOW_COMMENT];
+  let current = source;
+  let annotated = 0;
+  while (true) {
+    const findings = analyzeSource(path, current, options)
+      .filter((item) => !allowlisted(item, allowlist));
+    if (findings.length === 0) break;
+    const markers = new Map();
+    for (const item of findings) {
+      if (markers.has(item.line)) continue;
+      const marker = chooseMarker(path, current, options, allowComments, item, findings.length);
+      if (marker !== null) markers.set(item.line, marker);
+    }
+    if (markers.size === 0) break;
+    current = applyMarkers(current, markers);
+    annotated += markers.size;
+  }
+  return { source: current, annotated };
+}
+
+/**
+ * fixRepository annotates every reported finding with an exception marker and
+ * writes the edited files. Every edit is computed before the first write.
+ * Returns the edited files and the findings that remain.
+ */
+export async function fixRepository(root, config = {}) {
+  const settings = compileSettings(config);
+  const options = analysisOptions(settings);
+  const edits = [];
+  const remaining = [];
+  for await (const file of repositorySources(root, settings)) {
+    const fixed = fixSource(file.path, file.source, options, settings.allowlist);
+    if (fixed.annotated > 0) {
+      edits.push({
+        path: file.path,
+        absolute: file.absolute,
+        source: fixed.source,
+        annotated: fixed.annotated,
+      });
+    }
+    remaining.push(...analyzeSource(file.path, fixed.source, options)
+      .filter((item) => !allowlisted(item, settings.allowlist)));
+  }
+  edits.sort((left, right) => left.path.localeCompare(right.path));
+  for (const edit of edits) {
+    await writeFile(edit.absolute, edit.source, "utf8");
+  }
+  return {
+    files: edits.map(({ path, annotated }) => ({ path, annotated })),
+    findings: sortFindings(remaining),
+  };
+}

package/src/sarif.mjs

@@ -0,0 +1,52 @@
+const SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json";
+
+const KIND_DESCRIPTIONS = {
+  "localized-jsx-text": "Customer-visible JSX text must come from a translation key.",
+  "localized-attribute": "Customer-visible JSX attributes must come from a translation key.",
+  "forbidden-pattern": "A configured forbidden pattern is present in the source.",
+};
+
+function normalizeRepository(repository) {
+  const url = typeof repository === "string" ? repository : repository?.url;
+  if (typeof url !== "string") return undefined;
+  return url.replace(/^git\+/, "").replace(/\.git$/, "");
+}
+
+/**
+ * buildSarif renders findings as one SARIF 2.1.0 document.
+ */
+export function buildSarif(findings, meta = {}) {
+  const rules = [];
+  const results = [];
+  for (const item of findings) {
+    if (!rules.some((rule) => rule.id === item.kind)) {
+      rules.push({
+        id: item.kind,
+        name: item.kind,
+        shortDescription: { text: KIND_DESCRIPTIONS[item.kind] ?? item.kind },
+      });
+    }
+    results.push({
+      ruleId: item.kind,
+      level: "error",
+      message: { text: item.message },
+      locations: [{
+        physicalLocation: {
+          artifactLocation: { uri: item.path },
+          region: { startLine: item.line },
+        },
+      }],
+    });
+  }
+  const driver = {
+    name: "localization-drift",
+    version: meta.version,
+    informationUri: normalizeRepository(meta.repository),
+    rules,
+  };
+  return {
+    $schema: SCHEMA,
+    version: "2.1.0",
+    runs: [{ tool: { driver }, results }],
+  };
+}