@digitalby/zh-lint 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 digitalby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# zh-lint
+
+> Compiler-error-grade lint for Chinese localizations. Catches Simplified characters that leaked into a Traditional locale (and vice versa) before they ship.
+
+[![CI](https://github.com/digitalby/zh-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/digitalby/zh-lint/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@digitalby/zh-lint.svg)](https://www.npmjs.com/package/@digitalby/zh-lint)
+
+## The problem
+
+Chinese localizations get this wrong all the time:
+
+- A translator copy-pastes from a mainland source into `zh-Hant.lproj`.
+- The wrong IME is active when a single character is patched.
+- A 简 sneaks into 繁 (or the reverse) and the compiler is silent. It looks like Chinese, so it ships.
+
+`zh-lint` catches it. One CJK character at a time, with file/line/column, so you can fail the Xcode build or the GitHub Actions run.
+
+## What it does
+
+For every `.strings` file under a `zh-Hans*.lproj`, `zh-Hant*.lproj`, `zh-HK.lproj`, `zh-TW.lproj`, `zh-MO.lproj`, `zh-SG.lproj` or `zh-CN.lproj` directory:
+
+1. Detect the expected script (Simplified for `zh-Hans*`/`zh-CN`/`zh-SG`, Traditional for the rest). Override per-glob in `.zh-lint.yml`.
+2. For every value, run [OpenCC](https://github.com/BYVoid/OpenCC) (via `opencc-js`) to convert the string to the *expected* script.
+3. Any CJK character that *changed* during conversion was script-exclusive in the wrong direction. Flag it as an error at its exact line and column.
+
+Shared characters (most of the CJK Unified Ideographs block) don't change during OpenCC conversion and produce zero noise.
+
+## Install / run
+
+```sh
+# One-off, no install:
+npx --yes @digitalby/zh-lint /path/to/repo
+
+# As a dev dependency:
+npm install --save-dev @digitalby/zh-lint
+```
+
+> The package ships as `@digitalby/zh-lint` on npm but the CLI binary is `zh-lint`. After install/`npx`, run it as `zh-lint <root>`.
+
+## Usage
+
+```
+zh-lint <root>                              Scan <root> for Hans/Hant contamination.
+zh-lint --init                              Write a default .zh-lint.yml.
+zh-lint --config=<path>                     Use a specific config file.
+zh-lint --no-config                         Ignore .zh-lint.yml entirely.
+zh-lint --format=xcode|github|plain|json    Output format.
+zh-lint --help
+zh-lint --version
+```
+
+Exit codes:
+
+| code | meaning |
+|---|---|
+| `0` | No violations. |
+| `1` | One or more violations. |
+| `2` | Configuration or I/O error. |
+
+### Output formats
+
+- **`xcode`** — `file:line:col: error: zh-lint: ...`, written to stderr. Xcode picks these up automatically when emitted from a Run Script build phase.
+- **`github`** — `::error file=...,line=...,col=...::...` workflow commands for GitHub Actions annotations.
+- **`plain`** — `file:line:col: error: ...` for any CI. The default.
+- **`json`** — A JSON array of `{file, line, col, severity, key, char, expectedScript, actualScriptHint, message}` for programmatic consumers.
+
+## Configuration: `.zh-lint.yml`
+
+All keys are optional. The defaults handle standard Apple/Android layouts.
+
+```yaml
+# Override or extend the default directory→script mapping.
+locales:
+  "**/zh-HK.lproj": traditional
+  "**/zh-SG.lproj": simplified
+
+# Globs to skip during the walk.
+ignore:
+  - "**/*.generated.strings"
+
+# Exact whole-string values to permit (proper nouns, brand names).
+allow_strings:
+  - "App Store"
+
+# Individual characters to permit in any locale.
+# Useful for brand names where Traditional 髮 is used even in Simplified copy.
+allow_chars:
+  - "髮"
+  - "體"
+```
+
+Run `zh-lint --init` to drop a starter file in the current directory.
+
+## Integrations
+
+- [Xcode (Run Script build phase)](docs/integration-xcode.md)
+- [GitHub Actions](docs/integration-github-actions.md)
+- [Fastlane](docs/integration-fastlane.md)
+
+### One-liner: GitHub Actions
+
+```yaml
+- uses: digitalby/zh-lint@v0.1.1
+  with:
+    root: '.'
+    format: 'github'
+```
+
+### One-liner: Xcode build phase
+
+Add a new "Run Script" build phase before "Compile Sources":
+
+```sh
+if ! command -v npx >/dev/null 2>&1; then
+  echo "warning: zh-lint skipped — install Node (brew install node)"
+  exit 0
+fi
+npx --yes @digitalby/zh-lint@latest "$SRCROOT" --format=xcode
+```
+
+The `xcode` format writes errors to stderr in the form Xcode parses, so violations appear directly in the Issue Navigator.
+
+## Scope (v0.1)
+
+- Apple legacy `.strings` files (UTF-8, UTF-8-with-BOM, UTF-16 LE/BE — all handled).
+- Hans-vs-Hant character-script detection only. CN-vs-HK-vs-TW vocabulary mismatches are tracked for v0.2.
+- `.stringsdict`, `.xcstrings` (String Catalogs), and Android `strings.xml` are also v0.2 — file an issue if you need them sooner.
+- No inline-comment overrides; everything goes through `.zh-lint.yml`.
+
+## How it works (one paragraph)
+
+For a Hans file, `zh-lint` converts every character with OpenCC's TW→CN mapping. If the conversion changed a character, the original was Traditional-exclusive — that's the violation. For Hant files, the reverse: CN→TW. Shared characters pass through unchanged in both directions, so they're never flagged.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,639 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import * as fs4 from "fs";
+import * as path3 from "path";
+
+// src/config.ts
+import * as fs from "fs";
+import * as path from "path";
+import { parse as parseYaml } from "yaml";
+var DEFAULT_CONFIG_NAMES = [".zh-lint.yml", ".zh-lint.yaml"];
+var DEFAULT_LOCALES = {
+  "**/zh-Hans*.lproj": "simplified",
+  "**/zh-Hant*.lproj": "traditional",
+  "**/zh-HK.lproj": "traditional",
+  "**/zh-MO.lproj": "traditional",
+  "**/zh-TW.lproj": "traditional",
+  "**/zh-SG.lproj": "simplified",
+  "**/zh-CN.lproj": "simplified"
+};
+var DEFAULT_IGNORE = ["**/node_modules/**", "**/Pods/**", "**/.git/**"];
+var ConfigError = class extends Error {
+};
+function findConfig(startDir) {
+  let dir = path.resolve(startDir);
+  const root = path.parse(dir).root;
+  while (true) {
+    for (const name of DEFAULT_CONFIG_NAMES) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    }
+    if (dir === root) return null;
+    dir = path.dirname(dir);
+  }
+}
+function loadConfig(configPath) {
+  if (configPath === null) {
+    return {
+      locales: { ...DEFAULT_LOCALES },
+      ignore: [...DEFAULT_IGNORE],
+      allowStrings: /* @__PURE__ */ new Set(),
+      allowChars: /* @__PURE__ */ new Set()
+    };
+  }
+  const raw = fs.readFileSync(configPath, "utf8");
+  let parsed;
+  try {
+    parsed = parseYaml(raw);
+  } catch (e) {
+    throw new ConfigError(`Failed to parse ${configPath}: ${e.message}`);
+  }
+  if (parsed === null || parsed === void 0) {
+    return {
+      locales: { ...DEFAULT_LOCALES },
+      ignore: [...DEFAULT_IGNORE],
+      allowStrings: /* @__PURE__ */ new Set(),
+      allowChars: /* @__PURE__ */ new Set()
+    };
+  }
+  if (typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new ConfigError(`${configPath}: top-level must be a mapping`);
+  }
+  const obj = parsed;
+  const locales = { ...DEFAULT_LOCALES };
+  if (obj.locales !== void 0) {
+    if (typeof obj.locales !== "object" || obj.locales === null || Array.isArray(obj.locales)) {
+      throw new ConfigError(`${configPath}: 'locales' must be a mapping of glob \u2192 script`);
+    }
+    for (const [glob, script] of Object.entries(obj.locales)) {
+      if (script !== "simplified" && script !== "traditional") {
+        throw new ConfigError(
+          `${configPath}: locale '${glob}' must map to 'simplified' or 'traditional', got '${String(script)}'`
+        );
+      }
+      locales[glob] = script;
+    }
+  }
+  const ignore = [...DEFAULT_IGNORE];
+  if (obj.ignore !== void 0) {
+    if (!Array.isArray(obj.ignore)) {
+      throw new ConfigError(`${configPath}: 'ignore' must be an array of globs`);
+    }
+    for (const g of obj.ignore) {
+      if (typeof g !== "string") {
+        throw new ConfigError(`${configPath}: 'ignore' entries must be strings`);
+      }
+      ignore.push(g);
+    }
+  }
+  const allowStrings = /* @__PURE__ */ new Set();
+  if (obj.allow_strings !== void 0) {
+    if (!Array.isArray(obj.allow_strings)) {
+      throw new ConfigError(`${configPath}: 'allow_strings' must be an array`);
+    }
+    for (const s of obj.allow_strings) {
+      if (typeof s !== "string") {
+        throw new ConfigError(`${configPath}: 'allow_strings' entries must be strings`);
+      }
+      allowStrings.add(s);
+    }
+  }
+  const allowChars = /* @__PURE__ */ new Set();
+  if (obj.allow_chars !== void 0) {
+    if (!Array.isArray(obj.allow_chars)) {
+      throw new ConfigError(`${configPath}: 'allow_chars' must be an array`);
+    }
+    for (const ch of obj.allow_chars) {
+      if (typeof ch !== "string") {
+        throw new ConfigError(`${configPath}: 'allow_chars' entries must be strings`);
+      }
+      for (const cp of ch) allowChars.add(cp);
+    }
+  }
+  return { locales, ignore, allowStrings, allowChars };
+}
+var DEFAULT_INIT_CONFIG = `# zh-lint configuration.
+# All keys are optional; defaults already cover standard iOS/Android layouts.
+
+# locales:
+#   "**/zh-HK.lproj": traditional
+#   "**/zh-SG.lproj": simplified
+
+# ignore:
+#   - "**/*.generated.strings"
+
+# allow_strings:
+#   - "App Store"
+
+# allow_chars:
+#   - "\u9AEE"
+`;
+
+// src/core.ts
+import * as fs3 from "fs";
+
+// src/detect.ts
+import { Converter } from "opencc-js";
+var t2s = Converter({ from: "tw", to: "cn" });
+var s2t = Converter({ from: "cn", to: "tw" });
+function isCJK(cp) {
+  const code = cp.codePointAt(0);
+  if (code === void 0) return false;
+  return code >= 13312 && code <= 19903 || code >= 19968 && code <= 40959 || code >= 131072 && code <= 173791 || code >= 173824 && code <= 191471 || code >= 196608 && code <= 201551 || code >= 63744 && code <= 64255;
+}
+function detectInEntry(filePath, entry, expectedScript, config) {
+  if (config.allowStrings.has(entry.value)) return [];
+  const violations = [];
+  const convert = expectedScript === "simplified" ? t2s : s2t;
+  const oppositeScript = expectedScript === "simplified" ? "traditional" : "simplified";
+  for (let i = 0; i < entry.valueChars.length; i++) {
+    const ch = entry.valueChars[i];
+    if (!isCJK(ch)) continue;
+    if (config.allowChars.has(ch)) continue;
+    const converted = convert(ch);
+    if (converted === ch) continue;
+    violations.push({
+      file: filePath,
+      line: entry.charLines[i] ?? entry.valueLine,
+      col: entry.charCols[i] ?? entry.valueCol,
+      key: entry.key,
+      char: ch,
+      expectedScript,
+      actualScriptHint: oppositeScript,
+      message: `${oppositeScript} character "${ch}" in ${scriptLabel(expectedScript)} file (key="${entry.key}")`
+    });
+  }
+  return violations;
+}
+function scriptLabel(s) {
+  return s === "simplified" ? "zh-Hans" : "zh-Hant";
+}
+
+// src/parsers/strings.ts
+var ParseError = class extends Error {
+  constructor(message, line, col) {
+    super(`${message} at line ${line}, col ${col}`);
+    this.line = line;
+    this.col = col;
+  }
+  line;
+  col;
+};
+function advance(c, n = 1) {
+  for (let i = 0; i < n; i++) {
+    if (c.pos >= c.source.length) return;
+    if (c.source[c.pos] === "\n") {
+      c.line++;
+      c.col = 1;
+    } else {
+      c.col++;
+    }
+    c.pos++;
+  }
+}
+function peek(c, offset = 0) {
+  return c.source[c.pos + offset] ?? "";
+}
+function skipTrivia(c) {
+  while (c.pos < c.source.length) {
+    const ch = peek(c);
+    if (ch === " " || ch === "	" || ch === "\n" || ch === "\r") {
+      advance(c);
+      continue;
+    }
+    if (ch === "/" && peek(c, 1) === "/") {
+      while (c.pos < c.source.length && peek(c) !== "\n") advance(c);
+      continue;
+    }
+    if (ch === "/" && peek(c, 1) === "*") {
+      advance(c, 2);
+      while (c.pos < c.source.length && !(peek(c) === "*" && peek(c, 1) === "/")) {
+        advance(c);
+      }
+      if (c.pos < c.source.length) advance(c, 2);
+      continue;
+    }
+    return;
+  }
+}
+function expect(c, ch) {
+  if (peek(c) !== ch) {
+    throw new ParseError(`Expected '${ch}', got '${peek(c) || "<eof>"}'`, c.line, c.col);
+  }
+  advance(c);
+}
+function readStringLiteral(c) {
+  expect(c, '"');
+  const chars = [];
+  const charLines = [];
+  const charCols = [];
+  const startLine = c.line;
+  const startCol = c.col;
+  while (c.pos < c.source.length) {
+    const ch = peek(c);
+    if (ch === '"') {
+      advance(c);
+      return { value: chars.join(""), startLine, startCol, charLines, charCols };
+    }
+    if (ch === "\\") {
+      const escLine = c.line;
+      const escCol = c.col;
+      advance(c);
+      const esc = peek(c);
+      let decoded;
+      switch (esc) {
+        case "n":
+          decoded = "\n";
+          advance(c);
+          break;
+        case "t":
+          decoded = "	";
+          advance(c);
+          break;
+        case "r":
+          decoded = "\r";
+          advance(c);
+          break;
+        case '"':
+          decoded = '"';
+          advance(c);
+          break;
+        case "\\":
+          decoded = "\\";
+          advance(c);
+          break;
+        case "'":
+          decoded = "'";
+          advance(c);
+          break;
+        case "0":
+          decoded = "\0";
+          advance(c);
+          break;
+        case "U":
+        case "u": {
+          advance(c);
+          let hex = "";
+          while (hex.length < 4 && /[0-9a-fA-F]/.test(peek(c))) {
+            hex += peek(c);
+            advance(c);
+          }
+          if (hex.length === 0) {
+            throw new ParseError("Invalid \\u escape", escLine, escCol);
+          }
+          decoded = String.fromCodePoint(parseInt(hex, 16));
+          break;
+        }
+        default:
+          decoded = esc;
+          advance(c);
+      }
+      for (const codePoint of decoded) {
+        chars.push(codePoint);
+        charLines.push(escLine);
+        charCols.push(escCol);
+      }
+      continue;
+    }
+    const charLine = c.line;
+    const charCol = c.col;
+    if (ch >= "\uD800" && ch <= "\uDBFF" && c.pos + 1 < c.source.length) {
+      const next = peek(c, 1);
+      if (next >= "\uDC00" && next <= "\uDFFF") {
+        chars.push(ch + next);
+        charLines.push(charLine);
+        charCols.push(charCol);
+        advance(c, 2);
+        continue;
+      }
+    }
+    chars.push(ch);
+    charLines.push(charLine);
+    charCols.push(charCol);
+    advance(c);
+  }
+  throw new ParseError("Unterminated string literal", startLine, startCol);
+}
+function parseStrings(source) {
+  const c = { source, pos: 0, line: 1, col: 1 };
+  if (source.charCodeAt(0) === 65279) {
+    advance(c);
+  }
+  const entries = [];
+  while (true) {
+    skipTrivia(c);
+    if (c.pos >= c.source.length) break;
+    const key = readStringLiteral(c);
+    skipTrivia(c);
+    expect(c, "=");
+    skipTrivia(c);
+    const valueResult = readStringLiteral(c);
+    skipTrivia(c);
+    expect(c, ";");
+    const valueChars = [];
+    for (const cp of valueResult.value) valueChars.push(cp);
+    entries.push({
+      key: key.value,
+      value: valueResult.value,
+      valueLine: valueResult.startLine,
+      valueCol: valueResult.startCol,
+      valueChars,
+      charLines: valueResult.charLines,
+      charCols: valueResult.charCols
+    });
+  }
+  return entries;
+}
+function decodeStringsBuffer(buf) {
+  if (buf.length >= 2 && buf[0] === 255 && buf[1] === 254) {
+    return buf.toString("utf16le", 2);
+  }
+  if (buf.length >= 2 && buf[0] === 254 && buf[1] === 255) {
+    const swapped = Buffer.alloc(buf.length - 2);
+    for (let i = 2; i + 1 < buf.length; i += 2) {
+      swapped[i - 2] = buf[i + 1];
+      swapped[i - 1] = buf[i];
+    }
+    return swapped.toString("utf16le");
+  }
+  if (buf.length >= 3 && buf[0] === 239 && buf[1] === 187 && buf[2] === 191) {
+    return buf.toString("utf8", 3);
+  }
+  return buf.toString("utf8");
+}
+
+// src/walker.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+import picomatch from "picomatch";
+var STRINGS_EXTENSIONS = /* @__PURE__ */ new Set([".strings"]);
+function walk(root, config) {
+  const absRoot = path2.resolve(root);
+  const ignoreMatchers = config.ignore.map((g) => picomatch(g, { dot: true }));
+  const localeMatchers = Object.entries(
+    config.locales
+  ).map(([glob, script]) => ({ match: picomatch(glob, { dot: true }), script }));
+  const out = [];
+  function visit(dir) {
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path2.join(dir, e.name);
+      const rel = path2.relative(absRoot, full) || e.name;
+      if (ignoreMatchers.some((m) => m(rel) || m(full))) continue;
+      if (e.isDirectory()) {
+        visit(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      const ext = path2.extname(full);
+      if (!STRINGS_EXTENSIONS.has(ext)) continue;
+      const parentDir = path2.basename(path2.dirname(full));
+      if (!parentDir.endsWith(".lproj")) continue;
+      const dirRel = path2.relative(absRoot, path2.dirname(full));
+      const dirFull = path2.dirname(full);
+      const script = inferScript(localeMatchers, dirRel, dirFull);
+      if (script === null) continue;
+      out.push({ path: full, expectedScript: script });
+    }
+  }
+  visit(absRoot);
+  return out;
+}
+function inferScript(matchers, dirRel, dirFull) {
+  for (const m of matchers) {
+    if (m.match(dirRel) || m.match(dirFull)) return m.script;
+  }
+  return null;
+}
+
+// src/core.ts
+function scan(root, config) {
+  const files = walk(root, config);
+  const violations = [];
+  const parseErrors = [];
+  for (const file of files) {
+    let source;
+    try {
+      const buf = fs3.readFileSync(file.path);
+      source = decodeStringsBuffer(buf);
+    } catch (e) {
+      parseErrors.push({ file: file.path, message: e.message });
+      continue;
+    }
+    try {
+      const entries = parseStrings(source);
+      for (const entry of entries) {
+        violations.push(...detectInEntry(file.path, entry, file.expectedScript, config));
+      }
+    } catch (e) {
+      parseErrors.push({ file: file.path, message: e.message });
+    }
+  }
+  return { files: files.length, violations, parseErrors };
+}
+
+// src/report/github.ts
+function escape(s) {
+  return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+}
+function formatGithub(violations) {
+  return violations.map(
+    (v) => `::error file=${escape(v.file)},line=${v.line},col=${v.col}::${escape(`zh-lint: ${v.message}`)}`
+  ).join("\n");
+}
+
+// src/report/json.ts
+function formatJson(violations) {
+  return JSON.stringify(
+    violations.map((v) => ({
+      file: v.file,
+      line: v.line,
+      col: v.col,
+      severity: "error",
+      key: v.key,
+      char: v.char,
+      expectedScript: v.expectedScript,
+      actualScriptHint: v.actualScriptHint,
+      message: v.message
+    })),
+    null,
+    2
+  );
+}
+
+// src/report/plain.ts
+function formatPlain(violations) {
+  return violations.map((v) => `${v.file}:${v.line}:${v.col}: error: ${v.message}`).join("\n");
+}
+
+// src/report/xcode.ts
+function formatXcode(violations) {
+  return violations.map((v) => `${v.file}:${v.line}:${v.col}: error: zh-lint: ${v.message}`).join("\n");
+}
+
+// src/report/index.ts
+function format(violations, outputFormat) {
+  switch (outputFormat) {
+    case "xcode":
+      return formatXcode(violations);
+    case "github":
+      return formatGithub(violations);
+    case "plain":
+      return formatPlain(violations);
+    case "json":
+      return formatJson(violations);
+  }
+}
+
+// src/cli.ts
+var USAGE = `zh-lint \u2014 Chinese script-contamination linter
+
+Usage:
+  zh-lint <root>                     Scan <root> for Hans/Hant contamination.
+  zh-lint --init                     Write a default .zh-lint.yml in the current directory.
+
+Options:
+  --config=<path>                    Use a specific config file (default: .zh-lint.yml searched upward).
+  --no-config                        Ignore any .zh-lint.yml and use built-in defaults.
+  --format=<xcode|github|plain|json> Output format (default: plain).
+  --help, -h                         Show this message.
+  --version, -V                      Print version and exit.
+
+Exit codes:
+  0  Clean.
+  1  One or more violations found.
+  2  Configuration or IO error.
+`;
+function parseArgs(argv) {
+  const result = {
+    root: ".",
+    configPath: void 0,
+    format: "plain",
+    init: false,
+    help: false,
+    version: false
+  };
+  let positional = null;
+  for (const arg of argv) {
+    if (arg === "--help" || arg === "-h") result.help = true;
+    else if (arg === "--version" || arg === "-V") result.version = true;
+    else if (arg === "--init") result.init = true;
+    else if (arg === "--no-config") result.configPath = null;
+    else if (arg.startsWith("--config=")) result.configPath = arg.slice("--config=".length);
+    else if (arg.startsWith("--format=")) {
+      const v = arg.slice("--format=".length);
+      if (v !== "xcode" && v !== "github" && v !== "plain" && v !== "json") {
+        throw new Error(`Unknown --format value: ${v}`);
+      }
+      result.format = v;
+    } else if (arg.startsWith("--")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (positional === null) {
+      positional = arg;
+    } else {
+      throw new Error(`Unexpected extra argument: ${arg}`);
+    }
+  }
+  if (positional !== null) result.root = positional;
+  return result;
+}
+function readVersion() {
+  try {
+    const here = path3.dirname(new URL(import.meta.url).pathname);
+    const candidates = [path3.join(here, "..", "package.json"), path3.join(here, "package.json")];
+    for (const c of candidates) {
+      if (fs4.existsSync(c)) {
+        const pkg = JSON.parse(fs4.readFileSync(c, "utf8"));
+        if (pkg.version) return pkg.version;
+      }
+    }
+  } catch {
+  }
+  return "unknown";
+}
+function main(argv) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (e) {
+    process.stderr.write(`zh-lint: ${e.message}
+
+${USAGE}`);
+    return 2;
+  }
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.version) {
+    process.stdout.write(`${readVersion()}
+`);
+    return 0;
+  }
+  if (args.init) {
+    const target = path3.resolve(".zh-lint.yml");
+    if (fs4.existsSync(target)) {
+      process.stderr.write(`zh-lint: ${target} already exists; refusing to overwrite
+`);
+      return 2;
+    }
+    fs4.writeFileSync(target, DEFAULT_INIT_CONFIG, "utf8");
+    process.stdout.write(`Wrote ${target}
+`);
+    return 0;
+  }
+  let configPath;
+  if (args.configPath === void 0) {
+    configPath = findConfig(args.root);
+  } else if (args.configPath === null) {
+    configPath = null;
+  } else {
+    configPath = path3.resolve(args.configPath);
+    if (!fs4.existsSync(configPath)) {
+      process.stderr.write(`zh-lint: config file not found: ${configPath}
+`);
+      return 2;
+    }
+  }
+  let config;
+  try {
+    config = loadConfig(configPath);
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      process.stderr.write(`zh-lint: ${e.message}
+`);
+      return 2;
+    }
+    throw e;
+  }
+  const result = scan(args.root, config);
+  if (result.parseErrors.length > 0) {
+    for (const pe of result.parseErrors) {
+      process.stderr.write(`zh-lint: parse error in ${pe.file}: ${pe.message}
+`);
+    }
+  }
+  if (result.violations.length === 0) {
+    if (args.format === "json") process.stdout.write("[]\n");
+    return result.parseErrors.length > 0 ? 2 : 0;
+  }
+  const out = format(result.violations, args.format);
+  const stream = args.format === "xcode" ? process.stderr : process.stdout;
+  stream.write(out + "\n");
+  return 1;
+}
+var isDirectInvocation = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("cli.js") === true || process.argv[1]?.endsWith("zh-lint") === true;
+if (isDirectInvocation) {
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@digitalby/zh-lint",
+  "version": "0.1.1",
+  "description": "Lint Chinese localization files for Simplified/Traditional script contamination",
+  "type": "module",
+  "bin": {
+    "zh-lint": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run lint && npm run test && npm run build"
+  },
+  "keywords": [
+    "chinese",
+    "localization",
+    "l10n",
+    "i18n",
+    "lint",
+    "simplified",
+    "traditional",
+    "opencc",
+    "ios",
+    "xcode"
+  ],
+  "author": "digitalby <yury@digitalby.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/digitalby/zh-lint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/digitalby/zh-lint/issues"
+  },
+  "homepage": "https://github.com/digitalby/zh-lint#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "opencc-js": "^1.0.5",
+    "picomatch": "^4.0.2",
+    "yaml": "^2.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/picomatch": "^3.0.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.6"
+  }
+}