@katerynakhar/i18n-keeper 0.16.0

package/src/mcp.ts

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { check } from './check.js';
+import { FormatError, describeFormatError } from './formats/error.js';
+import {
+  GlossaryError,
+  glossaryPath,
+  loadGlossary,
+  type Glossary,
+} from './glossary.js';
+import { LimitsError, limitsPath, loadLimits, type Limits } from './lengths.js';
+import {
+  MemoryError,
+  emptyMemory,
+  loadMemory,
+  memoryPath,
+  saveMemory,
+  syncMemory,
+  type Memory,
+} from './memory.js';
+import { ALL_SYNTAXES } from './placeholders.js';
+import { ScanError, detectProject, listLocales } from './scan.js';
+import { RULE_IDS, type Config, type Finding, type Report, type RuleId } from './types.js';
+import { VERSION } from './version.js';
+
+/**
+ * Everything a tool returns lands in the agent's context, so the text stays
+ * compact and findings are paged rather than dumped.
+ */
+const DEFAULT_LIMIT = 25;
+
+const commonInput = {
+  path: z.string().optional().describe('Project root. Defaults to the working directory.'),
+  localesDir: z.string().optional().describe('Locales directory. Auto-detected when omitted.'),
+  source: z.string().optional().describe('Source locale. Defaults to en, else the first found.'),
+  memory: z.string().optional().describe('Translation memory file. Defaults to .i18n/memory.json.'),
+  glossary: z.string().optional().describe('Glossary file. Defaults to .i18n/glossary.json.'),
+  limits: z.string().optional().describe('Width limits file. Defaults to .i18n/limits.json.'),
+};
+
+const statShape = {
+  locale: z.string(),
+  coverage: z.number(),
+  missing: z.number(),
+  orphan: z.number(),
+  stale: z.number(),
+  errors: z.number(),
+  warnings: z.number(),
+};
+
+interface CommonArgs {
+  path?: string;
+  localesDir?: string;
+  source?: string;
+  memory?: string;
+  glossary?: string;
+  limits?: string;
+  ignoreIdentical?: string[];
+  syntax?: string[];
+}
+
+function buildConfig(args: CommonArgs): Config {
+  const config = detectProject(args.path ?? process.cwd(), {
+    localesDir: args.localesDir,
+    sourceLocale: args.source,
+  });
+  if (args.syntax && args.syntax.length > 0) config.placeholderSyntaxes = args.syntax;
+  if (args.ignoreIdentical) config.ignoreIdentical = args.ignoreIdentical;
+  return config;
+}
+
+/** An explicitly named memory must exist; the default path is optional. */
+function openMemory(config: Config, explicit?: string): { memory: Memory | null; file: string } {
+  const file = memoryPath(config.root, explicit);
+  if (explicit && !existsSync(file)) throw new MemoryError(`Memory file not found: ${file}`);
+  return { memory: loadMemory(file), file };
+}
+
+/** An explicitly named limits file must exist; the default path is optional. */
+function openLimits(config: Config, explicit?: string): { limits: Limits | null; file: string } {
+  const file = limitsPath(config.root, explicit);
+  if (explicit && !existsSync(file)) throw new LimitsError(`Limits file not found: ${file}`);
+  return { limits: loadLimits(file), file };
+}
+
+/** An explicitly named glossary must exist; the default path is optional. */
+function openGlossary(config: Config, explicit?: string): { glossary: Glossary | null; file: string } {
+  const file = glossaryPath(config.root, explicit);
+  if (explicit && !existsSync(file)) throw new GlossaryError(`Glossary file not found: ${file}`);
+  return { glossary: loadGlossary(file), file };
+}
+
+function pad(s: string, width: number, right = false): string {
+  const gap = ' '.repeat(Math.max(0, width - s.length));
+  return right ? gap + s : s + gap;
+}
+
+function renderTable(report: Report): string {
+  const head = ['locale', 'cov', 'miss', 'orph'];
+  if (report.memoryLoaded) head.push('stale');
+  head.push('err', 'warn');
+
+  const rows = report.stats.map((s) => {
+    const row = [
+      s.locale,
+      `${(s.coverage * 100).toFixed(1)}%`,
+      String(s.missing),
+      String(s.orphan),
+    ];
+    if (report.memoryLoaded) row.push(String(s.stale));
+    row.push(String(s.errors), String(s.warnings));
+    return row;
+  });
+
+  const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+  const line = (cells: string[]) =>
+    cells.map((c, i) => pad(c, widths[i]!, i > 0)).join('  ').trimEnd();
+  return [line(head), ...rows.map(line)].join('\n');
+}
+
+function renderFindings(findings: Finding[], offset: number, total: number): string {
+  if (total === 0) return 'no findings';
+  if (findings.length === 0) return `no findings at offset ${offset} (${total} total)`;
+
+  const localeWidth = Math.max(...findings.map((f) => f.locale.length));
+  const keyWidth = Math.max(...findings.map((f) => f.key.length));
+  const ruleWidth = Math.max(...findings.map((f) => f.rule.length));
+
+  const lines = findings.map(
+    (f) =>
+      `${f.severity === 'error' ? 'E' : 'W'} ${pad(f.locale, localeWidth)}  ` +
+      `${pad(f.key, keyWidth)}  ${pad(f.rule, ruleWidth)}  ${f.detail}`,
+  );
+
+  const end = offset + findings.length;
+  const header =
+    end < total || offset > 0
+      ? `findings ${offset + 1}-${end} of ${total} (raise offset for more)`
+      : `findings (${total})`;
+
+  return [header, ...lines].join('\n');
+}
+
+function describeError(err: unknown): string {
+  if (
+    err instanceof ScanError ||
+    err instanceof MemoryError ||
+    err instanceof GlossaryError ||
+    err instanceof LimitsError
+  ) {
+    return err.message;
+  }
+  if (err instanceof FormatError) return describeFormatError(err);
+  return err instanceof Error ? err.message : String(err);
+}
+
+function toolError(err: unknown) {
+  return { isError: true, content: [{ type: 'text' as const, text: describeError(err) }] };
+}
+
+const server = new McpServer(
+  { name: 'i18n-keeper', version: VERSION },
+  { capabilities: { tools: {} } },
+);
+
+server.registerTool(
+  'i18n_scan',
+  {
+    title: 'Scan i18n project',
+    description:
+      'Report which locale directory, layout, locales and translation memory would be used. Run this first when the project layout is unknown.',
+    inputSchema: commonInput,
+    annotations: { readOnlyHint: true },
+  },
+  async (args) => {
+    try {
+      const config = buildConfig(args);
+      const { layout, locales } = listLocales(config.localesDir);
+      const { memory, file } = openMemory(config, args.memory);
+      const glossaryInfo = openGlossary(config, args.glossary);
+      const limitsInfo = openLimits(config, args.limits);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: [
+              `localesDir: ${config.localesDir}`,
+              `layout: ${layout}`,
+              `source: ${config.sourceLocale}`,
+              `locales: ${locales.join(', ')}`,
+              `placeholders: ${config.placeholderSyntaxes.join(', ')}`,
+              `memory: ${memory ? file : 'none (run i18n_sync to start tracking)'}`,
+              `glossary: ${
+                glossaryInfo.glossary
+                  ? `${glossaryInfo.file} (${glossaryInfo.glossary.terms.length} terms, ${glossaryInfo.glossary.doNotTranslate.length} verbatim)`
+                  : 'none'
+              }`,
+              `limits: ${
+                limitsInfo.limits
+                  ? `${limitsInfo.file} (${Object.keys(limitsInfo.limits.keys).length} keys, ${limitsInfo.limits.patterns.length} patterns)`
+                  : 'none'
+              }`,
+            ].join('\n'),
+          },
+        ],
+      };
+    } catch (err) {
+      return toolError(err);
+    }
+  },
+);
+
+server.registerTool(
+  'i18n_status',
+  {
+    title: 'i18n coverage summary',
+    description:
+      'Per-locale coverage and issue counts, without listing individual findings. Cheap overview; use i18n_check for detail.',
+    inputSchema: commonInput,
+    outputSchema: {
+      sourceLocale: z.string(),
+      sourceKeys: z.number(),
+      memoryLoaded: z.boolean(),
+      locales: z.array(z.object(statShape)),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async (args) => {
+    try {
+      const config = buildConfig(args);
+      const { memory } = openMemory(config, args.memory);
+      const { glossary } = openGlossary(config, args.glossary);
+      const { limits } = openLimits(config, args.limits);
+      const report = check(config, memory, glossary, limits);
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              `${report.sourceLocale} · ${report.sourceKeys} keys` +
+              `${report.memoryLoaded ? '' : ' · no memory'}\n\n${renderTable(report)}`,
+          },
+        ],
+        structuredContent: {
+          sourceLocale: report.sourceLocale,
+          sourceKeys: report.sourceKeys,
+          memoryLoaded: report.memoryLoaded,
+          locales: report.stats.map((s) => ({
+            locale: s.locale,
+            coverage: Number(s.coverage.toFixed(4)),
+            missing: s.missing,
+            orphan: s.orphan,
+            stale: s.stale,
+            errors: s.errors,
+            warnings: s.warnings,
+          })),
+        },
+      };
+    } catch (err) {
+      return toolError(err);
+    }
+  },
+);
+
+server.registerTool(
+  'i18n_check',
+  {
+    title: 'Lint locale files',
+    description:
+      'Find missing keys, orphans, empty values, structure mismatches, broken placeholders and — when a translation memory exists — translations whose source has changed since (stale). Deterministic: nothing is translated and no network is used. Filter by locale, rule or severity, and page with offset.',
+    inputSchema: {
+      ...commonInput,
+      locale: z.array(z.string()).optional().describe('Only these target locales.'),
+      rule: z
+        .array(z.enum(RULE_IDS))
+        .optional()
+        .describe('Only these rules. Naming a rule also enables it if it is off by default.'),
+      severity: z.enum(['error', 'warning']).optional().describe('Only this severity.'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe(`Findings per call (default ${DEFAULT_LIMIT}).`),
+      offset: z.number().int().min(0).optional().describe('Skip this many findings.'),
+      ignoreIdentical: z
+        .array(z.string())
+        .optional()
+        .describe('Values allowed to equal the source, e.g. ["OK", "Email"].'),
+      syntax: z
+        .array(z.enum(ALL_SYNTAXES as [string, ...string[]]))
+        .optional()
+        .describe('Override placeholder syntaxes. Add "laravel" for :name projects.'),
+      noMemory: z.boolean().optional().describe('Ignore the memory; disables stale detection.'),
+      noGlossary: z.boolean().optional().describe('Ignore the glossary.'),
+      noLimits: z.boolean().optional().describe('Ignore the width limits.'),
+    },
+    outputSchema: {
+      sourceLocale: z.string(),
+      sourceKeys: z.number(),
+      memoryLoaded: z.boolean(),
+      errors: z.number(),
+      warnings: z.number(),
+      total: z.number(),
+      offset: z.number(),
+      findings: z.array(
+        z.object({
+          rule: z.string(),
+          severity: z.string(),
+          locale: z.string(),
+          key: z.string(),
+          detail: z.string(),
+        }),
+      ),
+    },
+    annotations: { readOnlyHint: true },
+  },
+  async (args) => {
+    try {
+      const config = buildConfig(args);
+      const rules = new Set((args.rule ?? []) as RuleId[]);
+      // Naming a rule turns it on, so asking for an off-by-default rule works.
+      for (const rule of rules) {
+        if (config.rules[rule] === 'off') config.rules[rule] = 'warning';
+      }
+
+      const memory = args.noMemory ? null : openMemory(config, args.memory).memory;
+      const glossary = args.noGlossary ? null : openGlossary(config, args.glossary).glossary;
+      const limits = args.noLimits ? null : openLimits(config, args.limits).limits;
+      const report = check(config, memory, glossary, limits);
+
+      const locales = new Set(args.locale ?? []);
+      let findings = report.findings;
+      if (locales.size > 0) findings = findings.filter((f) => locales.has(f.locale));
+      if (rules.size > 0) findings = findings.filter((f) => rules.has(f.rule));
+      if (args.severity) findings = findings.filter((f) => f.severity === args.severity);
+
+      const total = findings.length;
+      const offset = args.offset ?? 0;
+      const limit = args.limit ?? DEFAULT_LIMIT;
+      const page = findings.slice(offset, offset + limit);
+
+      const errors = findings.filter((f) => f.severity === 'error').length;
+      const stats =
+        locales.size > 0 ? report.stats.filter((s) => locales.has(s.locale)) : report.stats;
+
+      const text = [
+        `${report.sourceLocale} · ${report.sourceKeys} keys · ${errors} errors · ${total - errors} warnings` +
+          `${report.memoryLoaded ? '' : ' · no memory'}`,
+        '',
+        renderTable({ ...report, stats }),
+        '',
+        renderFindings(page, offset, total),
+      ].join('\n');
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        structuredContent: {
+          sourceLocale: report.sourceLocale,
+          sourceKeys: report.sourceKeys,
+          memoryLoaded: report.memoryLoaded,
+          errors,
+          warnings: total - errors,
+          total,
+          offset,
+          findings: page.map((f) => ({
+            rule: f.rule,
+            severity: f.severity,
+            locale: f.locale,
+            key: f.key,
+            detail: f.detail,
+          })),
+        },
+      };
+    } catch (err) {
+      return toolError(err);
+    }
+  },
+);
+
+server.registerTool(
+  'i18n_sync',
+  {
+    title: 'Record translations in the memory',
+    description:
+      'Write the current translations into .i18n/memory.json so later source edits can be detected as stale. Without force this never clears a stale flag: entries whose translation is unchanged keep their old source hash. Run it after translations are updated, and once when adopting the tool.',
+    inputSchema: {
+      ...commonInput,
+      locale: z.array(z.string()).optional().describe('Only record these locales.'),
+      origin: z
+        .enum(['human', 'machine'])
+        .optional()
+        .describe('Who produced these translations. Default human, which also marks them reviewed.'),
+      force: z
+        .boolean()
+        .optional()
+        .describe('Re-record unchanged translations too, accepting them as current and clearing stale.'),
+    },
+    outputSchema: {
+      memory: z.string(),
+      created: z.number(),
+      updated: z.number(),
+      keptStale: z.number(),
+      unchanged: z.number(),
+      removed: z.number(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+  },
+  async (args) => {
+    try {
+      const config = buildConfig(args);
+      const file = memoryPath(config.root, args.memory);
+      const memory = loadMemory(file) ?? emptyMemory(config.sourceLocale);
+      const origin = args.origin ?? 'human';
+      const result = syncMemory(config, memory, {
+        origin,
+        reviewed: origin === 'human',
+        locales: args.locale,
+        force: args.force === true,
+      });
+      saveMemory(file, memory);
+
+      const note =
+        result.keptStale > 0 && !args.force
+          ? `\n${result.keptStale} translation(s) left stale on purpose — retranslate them, or sync with force to accept as-is.`
+          : '';
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              `memory ${file}\n` +
+              `created ${result.created}  updated ${result.updated}  ` +
+              `kept-stale ${result.keptStale}  unchanged ${result.unchanged}  removed ${result.removed}` +
+              note,
+          },
+        ],
+        structuredContent: { memory: file, ...result },
+      };
+    } catch (err) {
+      return toolError(err);
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/src/memory.ts

@@ -0,0 +1,227 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { loadBundle } from './scan.js';
+import type { Config } from './types.js';
+
+export const MEMORY_FILE = '.i18n/memory.json';
+
+export interface MemoryEntry {
+  /** Hash of the source string at the moment this translation was recorded. */
+  sourceHash: string;
+  value: string;
+  origin: 'human' | 'machine';
+  reviewed: boolean;
+  updatedAt: string;
+  /** When a person signed off on it, for entries that have been reviewed. */
+  reviewedAt?: string;
+}
+
+export interface Unreviewed {
+  locale: string;
+  key: string;
+  entry: MemoryEntry;
+}
+
+/** Everything still waiting for a person to look at it, in a stable order. */
+export function unreviewed(memory: Memory, locales?: string[], keys?: string[]): Unreviewed[] {
+  const wantedLocale = locales && locales.length > 0 ? new Set(locales) : null;
+  const wantedKey = keys && keys.length > 0 ? new Set(keys) : null;
+  const out: Unreviewed[] = [];
+
+  for (const locale of Object.keys(memory.entries).sort()) {
+    if (wantedLocale && !wantedLocale.has(locale)) continue;
+    const byKey = memory.entries[locale] ?? {};
+    for (const key of Object.keys(byKey).sort()) {
+      if (wantedKey && !wantedKey.has(key)) continue;
+      const entry = byKey[key]!;
+      if (!entry.reviewed) out.push({ locale, key, entry });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Signs off on translations a person has actually looked at.
+ *
+ * Nothing else in the tool can set this: a machine translation is recorded
+ * unreviewed and stays that way until someone says otherwise, which is the
+ * whole point of recording it.
+ */
+export function markReviewed(entries: Unreviewed[], now: string): number {
+  for (const { entry } of entries) {
+    entry.reviewed = true;
+    entry.reviewedAt = now;
+  }
+  return entries.length;
+}
+
+export interface Memory {
+  version: 1;
+  sourceLocale: string;
+  /** locale -> key -> entry. Nested rather than a flat list, for readable diffs. */
+  entries: Record<string, Record<string, MemoryEntry>>;
+}
+
+export class MemoryError extends Error {}
+
+/** 48 bits is plenty to notice an edited string, and keeps the file readable. */
+export function hashValue(value: string): string {
+  return createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 12);
+}
+
+export function memoryPath(root: string, explicit?: string): string {
+  return resolve(root, explicit ?? MEMORY_FILE);
+}
+
+export function emptyMemory(sourceLocale: string): Memory {
+  return { version: 1, sourceLocale, entries: {} };
+}
+
+export function loadMemory(file: string): Memory | null {
+  if (!existsSync(file)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new MemoryError(
+      `Invalid memory file ${file}\n  ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  const memory = parsed as Partial<Memory>;
+  if (memory?.version !== 1 || typeof memory.entries !== 'object' || memory.entries === null) {
+    throw new MemoryError(`Unrecognised memory file format in ${file} (expected version 1)`);
+  }
+  return { version: 1, sourceLocale: memory.sourceLocale ?? '', entries: memory.entries };
+}
+
+/** Writes with sorted keys so the file diffs cleanly in review. */
+export function saveMemory(file: string, memory: Memory): void {
+  const entries: Record<string, Record<string, MemoryEntry>> = {};
+  for (const locale of Object.keys(memory.entries).sort()) {
+    const byKey = memory.entries[locale] ?? {};
+    const sorted: Record<string, MemoryEntry> = {};
+    for (const key of Object.keys(byKey).sort()) sorted[key] = byKey[key]!;
+    entries[locale] = sorted;
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(
+    file,
+    `${JSON.stringify({ version: 1, sourceLocale: memory.sourceLocale, entries }, null, 2)}\n`,
+  );
+}
+
+export interface StaleVerdict {
+  stale: boolean;
+  tracked: boolean;
+}
+
+/**
+ * A translation is stale when the source moved and the translation demonstrably
+ * did not. If the target no longer matches what was recorded, someone edited it
+ * by hand — we cannot claim it is outdated, so we stay quiet.
+ */
+export function judge(
+  entry: MemoryEntry | undefined,
+  sourceValue: string,
+  targetValue: string,
+): StaleVerdict {
+  if (!entry) return { stale: false, tracked: false };
+  const moved = entry.sourceHash !== hashValue(sourceValue);
+  return { stale: moved && entry.value === targetValue, tracked: true };
+}
+
+export interface SyncOptions {
+  origin: 'human' | 'machine';
+  reviewed: boolean;
+  locales?: string[];
+  /** Accept the current state wholesale, clearing stale flags. */
+  force: boolean;
+}
+
+export interface SyncResult {
+  created: number;
+  updated: number;
+  keptStale: number;
+  unchanged: number;
+  removed: number;
+}
+
+/**
+ * Records the current translations. Without --force this never clears a stale
+ * flag: an entry whose target is unchanged keeps its old source hash, because
+ * nothing about the translation has actually been redone.
+ */
+export function syncMemory(config: Config, memory: Memory, opts: SyncOptions): SyncResult {
+  const source = loadBundle(config, config.sourceLocale);
+  const result: SyncResult = { created: 0, updated: 0, keptStale: 0, unchanged: 0, removed: 0 };
+  const now = new Date().toISOString();
+  const wanted = opts.locales && opts.locales.length > 0 ? new Set(opts.locales) : null;
+
+  memory.sourceLocale = config.sourceLocale;
+
+  for (const locale of config.locales) {
+    if (locale === config.sourceLocale) continue;
+    if (wanted && !wanted.has(locale)) continue;
+
+    const target = loadBundle(config, locale);
+    const byKey = (memory.entries[locale] ??= {});
+
+    for (const [key, sourceLeaf] of source.leaves) {
+      const targetLeaf = target.leaves.get(key);
+      if (!targetLeaf || targetLeaf.value.trim() === '') continue;
+
+      const entry = byKey[key];
+      const sourceHash = hashValue(sourceLeaf.value);
+
+      if (!entry) {
+        byKey[key] = {
+          sourceHash,
+          value: targetLeaf.value,
+          origin: opts.origin,
+          reviewed: opts.reviewed,
+          updatedAt: now,
+        };
+        result.created++;
+        continue;
+      }
+
+      const translationChanged = entry.value !== targetLeaf.value;
+
+      if (translationChanged || opts.force) {
+        if (entry.sourceHash === sourceHash && !translationChanged) {
+          result.unchanged++;
+          continue;
+        }
+        byKey[key] = {
+          sourceHash,
+          value: targetLeaf.value,
+          origin: translationChanged ? opts.origin : entry.origin,
+          reviewed: translationChanged ? opts.reviewed : entry.reviewed,
+          updatedAt: now,
+          // A sign-off survives a source edit; only a rewritten translation
+          // invalidates it.
+          ...(translationChanged || entry.reviewedAt === undefined
+            ? {}
+            : { reviewedAt: entry.reviewedAt }),
+        };
+        result.updated++;
+        continue;
+      }
+
+      if (entry.sourceHash !== sourceHash) result.keptStale++;
+      else result.unchanged++;
+    }
+
+    // Drop bookkeeping for keys that no longer exist in the source.
+    for (const key of Object.keys(byKey)) {
+      if (!source.leaves.has(key)) {
+        delete byKey[key];
+        result.removed++;
+      }
+    }
+  }
+
+  return result;
+}