champollion 0.3.3 → 0.4.0

package/lib/lint.js

@@ -6,8 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveConfig } from './config.js';
-import { flattenKeys } from './flatten.js';
-import { readLocaleFile, detectFormatFromDir, getExtension } from './format.js';
+import { discoverLocaleLayout, readLocaleFlat } from './locale-layout.js';
 import { isNonTranslatableString, isNonTranslatableLintExtended } from './string-classify.js';
 import { output } from './output.js';
 
@@ -50,6 +49,25 @@ const FRAMEWORKS = {
     frameworkImport: /from\s+['"]vue-i18n['"]/,
     translatableAttrs: ['placeholder', 'aria-label', 'alt', 'title', 'content', 'label'],
   },
+  // Docusaurus: copy is translated by <Translate> / translate({ id, message }).
+  // Dogfood 2026-08-28 (finding 8): ten pages of champollion.dev were
+  // written with raw JSX prose next to an i18n setup that was never used —
+  // and the lint called the site "generic", looked only for t('key'), and
+  // could not see it.
+  docusaurus: {
+    name: 'Docusaurus',
+    srcDirs: ['src'],
+    extensions: ['.tsx', '.jsx', '.ts', '.js'],
+    i18nCallPatterns: [
+      /<Translate\b[^>]*\bid\s*=\s*['"]([^'"]+)['"]/g,
+      /<Translate\b(?![^>]*\bid\s*=)[^>]*>([^<{]+)<\/Translate>/g,
+      /\btranslate\(\s*\{[^}]*?\bid\s*:\s*['"`]([^'"`]+)['"`]/g,
+    ],
+    frameworkImport: /from\s+['"]@docusaurus\/Translate['"]/,
+    translatableAttrs: ['placeholder', 'aria-label', 'alt', 'title', 'label'],
+    // Text inside these tags IS translated — never flag it.
+    wrapperTags: ['Translate'],
+  },
   hugo: {
     name: 'Hugo',
     srcDirs: ['layouts', 'themes'],
@@ -62,6 +80,9 @@ const FRAMEWORKS = {
   },
 };
 
+// Tags whose text content is code, never translatable copy.
+const CODE_TAGS = new Set(['code', 'pre', 'kbd', 'samp', 'var']);
+
 // Default generic framework for unknown projects
 const GENERIC_FRAMEWORK = {
   name: 'generic',
@@ -85,6 +106,11 @@ const GENERIC_FRAMEWORK = {
  * @returns {{ name: string, extensions: string[], srcDirs: string[], i18nCallPatterns: RegExp[], frameworkImport: RegExp|null }} Framework detection result
  */
 function detectFramework(cwd) {
+  // Docusaurus before Hugo: its own config file is unambiguous, while a
+  // Docusaurus repo can carry a stray config.yaml.
+  const docusaurusConfigs = ['docusaurus.config.js', 'docusaurus.config.ts', 'docusaurus.config.mjs', 'docusaurus.config.cjs'];
+  if (docusaurusConfigs.some(cfg => fs.existsSync(path.join(cwd, cfg)))) return FRAMEWORKS.docusaurus;
+
   // Check for Hugo config files first
   const hugoConfigs = ['hugo.toml', 'hugo.yaml', 'hugo.yml', 'config.toml', 'config.yaml'];
   for (const cfg of hugoConfigs) {
@@ -97,6 +123,7 @@ function detectFramework(cwd) {
     try {
       const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
       const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+      if (allDeps['@docusaurus/core']) return FRAMEWORKS.docusaurus;
       if (allDeps['next-intl']) return FRAMEWORKS['next-intl'];
       if (allDeps['react-i18next'] || allDeps['i18next']) return FRAMEWORKS['react-i18next'];
       if (allDeps['vue-i18n']) return FRAMEWORKS['vue-i18n'];
@@ -236,6 +263,16 @@ function extractHardcodedStrings(content, filePath, framework, minLength) {
     let match;
     while ((match = textPattern.exec(line)) !== null) {
       const text = match[1].trim();
+      // Text whose enclosing tag is a translation wrapper (<Translate>) is
+      // already translated.
+      const open = line.lastIndexOf('<', match.index);
+      const tag = open >= 0 ? (line.slice(open).match(/^<\/?([A-Za-z][\w.]*)/) || [])[1] : null;
+      if (tag && framework.wrapperTags && framework.wrapperTags.includes(tag)) continue;
+      // Code is not copy: <code>cli/shared/x.json</code>, <kbd>Ctrl</kbd>.
+      if (tag && CODE_TAGS.has(tag)) continue;
+      // No letters at all is not text — usually JS caught between a `>`
+      // comparison and a JSX tag (`n > 0 && <Badge`).
+      if (!/\p{L}/u.test(text)) continue;
       if (shouldFlagString(text, minLength)) {
         results.push({ line: i + 1, text, context: 'jsx-text' });
       }
@@ -505,6 +542,16 @@ async function runLint(options = {}) {
   }
 
   if (sourceFiles.length === 0) {
+    // A lint that checked nothing is not a pass: it used to exit 0 with "No
+    // source files found to lint." while verify failed on the same project
+    // (Round 4, i18next persona) — a CI gate pointed at the wrong folder
+    // stayed green. Name where it looked and how to point it elsewhere.
+    const rel = (p) => path.relative(cwd, path.resolve(cwd, p)).split(path.sep).join('/') || '.';
+    const lookedIn = srcDir ? [rel(srcDir)] : framework.srcDirs.map(rel);
+    const exts = framework.extensions.join(', ');
+    const reason = `no ${exts} files in ${lookedIn.map(d => `${d}/`).join(', ')}`
+      + `${srcDir ? '' : ` (the ${framework.name} defaults)`}${ignorePatterns.length > 0 ? ', after the ignore list' : ''}`;
+    const hint = 'Point it at your code: `champollion lint --src <dir>`, or "lint": { "srcDir": "<dir>" } in champollion.config.json.';
     if (cliArgs.json) {
       console.log(JSON.stringify({
         command: 'lint',
@@ -512,26 +559,34 @@ async function runLint(options = {}) {
         filesScanned: 0,
         findings: [],
         count: 0,
+        nothingChecked: true,
+        lookedIn,
+        extensions: framework.extensions,
+        error: `Nothing linted: ${reason}. ${hint}`,
       }, null, 2));
-      return 0;
+      return warnOnly ? 0 : 1;
     }
-    output.info('No source files found to lint.');
-    return 0;
+    output.error(`Nothing linted: ${reason}. ${hint}`);
+    return warnOnly ? 0 : 1;
   }
 
   output.info(`Scanning ${sourceFiles.length} file(s)...`);
 
-  // 3. Load locale keys for cross-referencing
-  const format = config.format !== 'auto'
-    ? config.format
-    : detectFormatFromDir(config.localesDir);
-  const ext = getExtension(format);
-  const sourcePath = path.join(config.localesDir, `${config.inputLocale}${ext}`);
-
+  // 3. Load locale keys for cross-referencing — every source file of the
+  //    layout (one for flat projects; every namespace file for i18next's
+  //    folder-per-locale shape). Keys stay bare: code calls t('nav.home')
+  //    with the namespace chosen elsewhere (useTranslation('common')), and
+  //    an explicit t('common:nav.home') is reduced to its key below.
+  //    Docusaurus keeps its historical lookup (no flat source file there).
   let localeKeys = {};
-  if (fs.existsSync(sourcePath)) {
-    const raw = readLocaleFile(sourcePath, format);
-    localeKeys = format === 'json' ? flattenKeys(raw) : raw;
+  let namespaces = new Set();
+  if (config.format !== 'docusaurus') {
+    const layout = discoverLocaleLayout(config, { cwd });
+    namespaces = new Set(layout.sourceFiles.map(f => f.ns).filter(Boolean));
+    for (const file of layout.sourceFiles) {
+      if (!fs.existsSync(file.path)) continue;
+      Object.assign(localeKeys, readLocaleFlat(file));
+    }
   }
   const localeEntries = Object.entries(localeKeys);
 
@@ -560,7 +615,14 @@ async function runLint(options = {}) {
     }
   }
 
-  // 5. Cross-reference
+  // 5. Cross-reference. i18next's "ns:key" form names a key inside one
+  //    namespace file — compare its key part against the merged key set.
+  if (namespaces.size > 0) {
+    for (const ref of [...allI18nKeys]) {
+      const i = ref.indexOf(':');
+      if (i > 0 && namespaces.has(ref.slice(0, i))) allI18nKeys.add(ref.slice(i + 1));
+    }
+  }
   const deadKeys = localeEntries.length > 0
     ? findDeadKeys(allI18nKeys, localeKeys)
     : [];

package/lib/local-only-marks.js

@@ -0,0 +1,106 @@
+/**
+ * local-only-marks.js — the files in a project a data steward has marked
+ * local-only: a `<file>.champollion.json` sidecar saying
+ * `"transmission": "local-only"` (what `champollion network register-corpus
+ * --data … --tier local-only` writes, and what the harness and nmt-forge
+ * honour: only a model on this machine may see that file).
+ *
+ * WHY init reads them: a project holding a local-only test set was set up
+ * with a hosted model by default — `init --yes` wrote OpenRouter beside a
+ * set its steward had said must never leave the machine (synthetic hospital
+ * persona, Rounds 10, 12 and 14). A mark in the project is a statement about
+ * where this project's text may go, so init's DEFAULT follows it: the local
+ * method. An explicit --method still wins; a hosted method is then the
+ * user's own choice, never a default.
+ *
+ * Read only: the walk opens sidecars (small JSON files) and nothing else;
+ * the data files they describe are never read.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The sidecar suffix — mt_eval_harness.corpus_loader.SIDECAR_SUFFIX (keep in step). */
+export const SIDECAR_SUFFIX = '.champollion.json';
+
+/** The one transmission value a sidecar sets (corpus_loader.LOCAL_ONLY). */
+export const LOCAL_ONLY = 'local-only';
+
+/**
+ * Folders never searched: dependency trees, VCS metadata, virtualenvs,
+ * build caches and champollion's own cache. A steward's data sits in the
+ * project's own folders (data/, private/, test-sets/ …), not in these —
+ * and node_modules can be enormous (or, through symlinked packages, cyclic).
+ */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.hg', '.svn', '.champollion', '.venv', 'venv',
+  '__pycache__', '.next', '.nuxt', '.svelte-kit', '.turbo', '.cache',
+  '.pytest_cache', '.mypy_cache', '.tox',
+]);
+
+/** How deep, and how many entries, the walk looks at — bounded, so init stays fast. */
+const MAX_DEPTH = 8;
+const MAX_ENTRIES = 50000;
+
+/**
+ * Every local-only mark under `root`, nearest first (by depth, then path).
+ *
+ * A sidecar that cannot be read is reported as a mark (`unreadable: true`):
+ * the harness refuses to run a corpus whose sidecar it cannot read, and a
+ * steward wrote it to restrict the data — an unreadable restriction is never
+ * read as no restriction.
+ *
+ * @param {string} root - The project folder (init's cwd)
+ * @returns {{ marks: Array<{ sidecar: string, dataFile: string, unreadable: boolean }>, truncated: boolean }}
+ *   absolute paths; `truncated` when the walk hit its bound before finishing
+ */
+export function findLocalOnlyMarks(root) {
+  const marks = [];
+  let seen = 0;
+  let truncated = false;
+  const queue = [{ dir: root, depth: 0 }];
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      if (++seen > MAX_ENTRIES) { truncated = true; break; }
+      const full = path.join(dir, e.name);
+      // Directory symlinks are not followed (no cycles, no leaving the project).
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        if (depth + 1 > MAX_DEPTH) { truncated = true; continue; }
+        queue.push({ dir: full, depth: depth + 1 });
+        continue;
+      }
+      if (!e.name.endsWith(SIDECAR_SUFFIX) || e.name === SIDECAR_SUFFIX) continue;
+      if (!(e.isFile() || e.isSymbolicLink())) continue;
+      const mark = readMark(full);
+      if (mark) marks.push({ ...mark, depth });
+    }
+    if (truncated && seen > MAX_ENTRIES) break;
+  }
+  marks.sort((a, b) => a.depth - b.depth || a.sidecar.localeCompare(b.sidecar));
+  return { marks: marks.map(({ depth, ...m }) => m), truncated };
+}
+
+/**
+ * One sidecar's mark, or null when it marks nothing local-only.
+ *
+ * @param {string} sidecar - Absolute path of a `<file>.champollion.json`
+ * @returns {{ sidecar: string, dataFile: string, unreadable: boolean }|null}
+ */
+export function readMark(sidecar) {
+  const dataFile = sidecar.slice(0, -SIDECAR_SUFFIX.length);
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(sidecar, 'utf-8').replace(/^/, ''));
+  } catch {
+    return { sidecar, dataFile, unreadable: true };
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return { sidecar, dataFile, unreadable: true };
+  return String(data.transmission || '').trim().toLowerCase() === LOCAL_ONLY
+    ? { sidecar, dataFile, unreadable: false }
+    : null;
+}