@polang233/kiro-language-pack 0.0.0-stage → 1.2.0

package/scripts/lib/upgrade-diff.mjs

@@ -0,0 +1,244 @@
+/** Pure snapshot comparison and translation review. No filesystem or app access. */
+const IGNORED_MODULE = /(^|\/)tests?\//;
+const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+const coreOrder = (a, b) => compare(a.moduleId, b.moduleId) || compare(a.key, b.key);
+const sourceText = (value) => typeof value === 'string' ? value : value?.message ?? '';
+const recorded = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+export function flattenCore(core = {}) {
+  const rows = [];
+  for (const [moduleId, keys] of Object.entries(core)) {
+    if (IGNORED_MODULE.test(moduleId)) continue;
+    for (const [key, english] of Object.entries(keys ?? {})) {
+      rows.push({ moduleId, key, english: sourceText(english) });
+    }
+  }
+  return new Map(rows.sort(coreOrder).map((row) => [`${row.moduleId}\0${row.key}`, row]));
+}
+
+function diffRows(before, after) {
+  const addedKeys = [], removedKeys = [], changedKeys = [];
+  for (const [id, row] of after) {
+    if (!before.has(id)) addedKeys.push({ ...row });
+    else if (before.get(id).english !== row.english) {
+      changedKeys.push({ ...row, previousEnglish: before.get(id).english });
+    }
+  }
+  for (const [id, row] of before) {
+    if (!after.has(id)) removedKeys.push({ ...row });
+  }
+  return { addedKeys, removedKeys, changedKeys };
+}
+
+function extensionRows(extensionId, entries = {}) {
+  return new Map(Object.entries(entries ?? {}).sort(([a], [b]) => compare(a, b))
+    .map(([key, value]) => [key, { extensionId, key, english: sourceText(value) }]));
+}
+
+const counts = (diff) => ({
+  added: diff.addedKeys.length, removed: diff.removedKeys.length, changed: diff.changedKeys.length
+});
+const emptyDiff = () => ({ addedKeys: [], removedKeys: [], changedKeys: [] });
+
+/** A move requires the same key and English unique in BOTH complete snapshots. */
+function findMoves(before, after, added, removed) {
+  const identity = (row) => row.english;
+  const index = (rows) => {
+    const map = new Map();
+    for (const row of rows) {
+      const id = identity(row);
+      if (!map.has(id)) map.set(id, []);
+      map.get(id).push(row);
+    }
+    return map;
+  };
+  const beforeIndex = index(before.values()), afterIndex = index(after.values());
+  const removedIndex = index(removed);
+  return added.flatMap((row) => {
+    const id = identity(row), candidates = removedIndex.get(id) ?? [];
+    if (!row.english || candidates.length !== 1 ||
+        beforeIndex.get(id)?.length !== 1 || afterIndex.get(id)?.length !== 1) return [];
+    const old = candidates[0];
+    if (old.moduleId === row.moduleId || old.key !== row.key) return [];
+    return [{ fromModuleId: old.moduleId, toModuleId: row.moduleId, key: row.key, english: row.english }];
+  });
+}
+
+export function diffUpgrade(before, after) {
+  const beforeCore = flattenCore(before?.core), afterCore = flattenCore(after.core);
+  const core = diffRows(beforeCore, afterCore);
+  const movedKeys = findMoves(beforeCore, afterCore, core.addedKeys, core.removedKeys);
+  const previous = before?.extensions ?? {}, current = after.extensions ?? {};
+  const addedExtensions = [], removedExtensions = [];
+  const packageNls = emptyDiff(), l10nBundle = emptyDiff();
+  const comparedExtensions = [], uncomparedExtensions = [];
+  const ids = [...new Set([...Object.keys(previous), ...Object.keys(current)])].sort(compare);
+  for (const extensionId of ids) {
+    const old = previous[extensionId], next = current[extensionId];
+    if (!old) addedExtensions.push(extensionId);
+    if (!next) removedExtensions.push(extensionId);
+    const packageDiff = diffRows(
+      extensionRows(extensionId, old?.packageNls), extensionRows(extensionId, next?.packageNls)
+    );
+    for (const key of Object.keys(packageNls)) packageNls[key].push(...packageDiff[key]);
+
+    // An absent extension is known empty; an omitted bundle field is NOT a baseline.
+    const beforeKnown = !old || recorded(old.l10nBundle);
+    const afterKnown = !next || recorded(next.l10nBundle);
+    if (!beforeKnown || !afterKnown) {
+      uncomparedExtensions.push({
+        extensionId,
+        reason: !beforeKnown && !afterKnown ? 'baseline-and-current-not-recorded'
+          : !beforeKnown ? 'baseline-not-recorded' : 'current-not-recorded'
+      });
+      continue;
+    }
+    comparedExtensions.push(extensionId);
+    const bundleDiff = diffRows(
+      extensionRows(extensionId, old?.l10nBundle), extensionRows(extensionId, next?.l10nBundle)
+    );
+    for (const key of Object.keys(l10nBundle)) l10nBundle[key].push(...bundleDiff[key]);
+  }
+  return {
+    baselineAvailable: before != null,
+    ...core,
+    movedKeys,
+    counts: { ...counts(core), moved: movedKeys.length },
+    extensionDrift: {
+      addedExtensions, removedExtensions,
+      counts: { addedExtensions: addedExtensions.length, removedExtensions: removedExtensions.length },
+      packageNls: { ...packageNls, counts: counts(packageNls) },
+      l10nBundle: {
+        ...l10nBundle, counts: counts(l10nBundle), comparedExtensions, uncomparedExtensions,
+        coverage: { comparedExtensions: comparedExtensions.length, uncomparedExtensions: uncomparedExtensions.length }
+      }
+    }
+  };
+}
+
+function translationState(english, own, upstream) {
+  const candidate = (value) => typeof value === 'string' && value !== '' ? value : null;
+  const ownTranslation = candidate(own), upstreamTranslation = candidate(upstream);
+  const effectiveSource = ownTranslation !== null ? 'own' : upstreamTranslation !== null ? 'upstream' : null;
+  const effective = effectiveSource === 'own' ? ownTranslation : upstreamTranslation;
+  return {
+    own: ownTranslation, upstream: upstreamTranslation, effectiveSource,
+    translated: effective !== null,
+    identicalToEnglish: effective !== null && effective === english
+  };
+}
+
+function review(english, own, upstream) {
+  const { translated, ...state } = translationState(english, own, upstream);
+  return {
+    ...state, hasCandidateTranslation: translated, required: true,
+    sourcesToReview: ['own', 'upstream'].filter((source) => state[source] !== null)
+  };
+}
+
+/** Candidate translations for changed English always require review, even if present. */
+export function auditUpgrade(metadata, drift, {
+  ownCore = {}, authoredCore = ownCore, upstreamCore = {}, ownExtensions = {}, upstreamExtensions = {}
+} = {}) {
+  const live = flattenCore(metadata.core);
+  const missingTranslations = [], identicalToEnglish = [];
+  for (const row of live.values()) {
+    const state = translationState(row.english, ownCore[row.moduleId]?.[row.key], upstreamCore[row.moduleId]?.[row.key]);
+    if (row.english !== '' && !state.translated) missingTranslations.push(row);
+    if (state.identicalToEnglish) identicalToEnglish.push({ ...row, translationSource: state.effectiveSource });
+  }
+  const missingIds = new Set(missingTranslations.map((row) => `${row.moduleId}\0${row.key}`));
+  const addedUntranslated = drift.addedKeys.filter((row) => missingIds.has(`${row.moduleId}\0${row.key}`));
+  const changedKeys = drift.changedKeys.map((row) => ({
+    ...row, translationReview: review(row.english, ownCore[row.moduleId]?.[row.key], upstreamCore[row.moduleId]?.[row.key])
+  }));
+  const movedKeys = drift.movedKeys.map((row) => ({
+    ...row,
+    translationReview: review(row.english, ownCore[row.toModuleId]?.[row.key], upstreamCore[row.toModuleId]?.[row.key]),
+    previousTranslations: translationState(row.english, ownCore[row.fromModuleId]?.[row.key], upstreamCore[row.fromModuleId]?.[row.key])
+  }));
+  const orphanedAuthored = [...flattenCore(authoredCore).entries()]
+    .filter(([id]) => !live.has(id)).map(([, { moduleId, key }]) => ({ moduleId, key }));
+  const removedIds = new Set(drift.removedKeys.map((row) => `${row.moduleId}\0${row.key}`));
+  const newlyOrphanedAuthored = orphanedAuthored.filter((row) => removedIds.has(`${row.moduleId}\0${row.key}`));
+  const preExistingOrphanedAuthored = drift.baselineAvailable
+    ? orphanedAuthored.filter((row) => !removedIds.has(`${row.moduleId}\0${row.key}`)) : null;
+  const missingModules = new Map();
+  for (const { moduleId, key, english } of missingTranslations) {
+    if (!missingModules.has(moduleId)) missingModules.set(moduleId, []);
+    missingModules.get(moduleId).push({ key, english });
+  }
+  const missingByModule = Object.fromEntries([...missingModules]
+    .sort((a, b) => b[1].length - a[1].length || compare(a[0], b[0])));
+
+  const extensionMissingTranslations = [], extensionIdenticalToEnglish = [];
+  for (const [extensionId, ext] of Object.entries(metadata.extensions ?? {}).sort(([a], [b]) => compare(a, b))) {
+    for (const [section, translationSection] of [['packageNls', 'package'], ['l10nBundle', 'bundle']]) {
+      for (const row of extensionRows(extensionId, ext[section]).values()) {
+        const state = translationState(row.english,
+          ownExtensions[extensionId]?.[translationSection]?.[row.key],
+          upstreamExtensions[extensionId]?.[translationSection]?.[row.key]);
+        if (row.english !== '' && !state.translated) {
+          extensionMissingTranslations.push({ ...row, section });
+        }
+        if (state.identicalToEnglish) {
+          extensionIdenticalToEnglish.push({ ...row, section, translationSource: state.effectiveSource });
+        }
+      }
+    }
+  }
+  const extensionDrift = { ...drift.extensionDrift };
+  for (const [section, translationSection] of [['packageNls', 'package'], ['l10nBundle', 'bundle']]) {
+    const diff = drift.extensionDrift[section];
+    extensionDrift[section] = { ...diff, changedKeys: diff.changedKeys.map((row) => ({
+      ...row, translationReview: review(row.english,
+        ownExtensions[row.extensionId]?.[translationSection]?.[row.key],
+        upstreamExtensions[row.extensionId]?.[translationSection]?.[row.key])
+    })) };
+  }
+  return {
+    changedKeys, movedKeys, extensionDrift,
+    missingTranslations, addedUntranslated, missingByModule, identicalToEnglish,
+    orphanedAuthored, newlyOrphanedAuthored, preExistingOrphanedAuthored,
+    extensionMissingTranslations, extensionIdenticalToEnglish
+  };
+}
+
+/** English work list. Existing candidate translations never suppress changed sources. */
+export function buildUpgradeSkeleton(audits) {
+  const core = new Map(), extensions = new Map();
+  const coreWork = new Map(), extensionWork = new Map();
+  for (const audit of audits) {
+    for (const row of [...audit.missingTranslations, ...audit.changedKeys]) {
+      if (!core.has(row.moduleId)) core.set(row.moduleId, new Map());
+      core.get(row.moduleId).set(row.key, row.english);
+      const id = `${row.moduleId}\0${row.key}`;
+      if (!coreWork.has(id) || row.translationReview?.required) {
+        coreWork.set(id, { moduleId: row.moduleId, key: row.key,
+          reason: row.translationReview?.required ? 'source-changed' : 'missing-translation' });
+      }
+    }
+    const changed = ['packageNls', 'l10nBundle'].flatMap((section) =>
+      audit.extensionDrift[section].changedKeys.map((row) => ({ ...row, section })));
+    for (const row of [...audit.extensionMissingTranslations, ...changed]) {
+      if (!extensions.has(row.extensionId)) extensions.set(row.extensionId, { package: new Map(), bundle: new Map() });
+      const section = row.section === 'packageNls' ? 'package' : 'bundle';
+      extensions.get(row.extensionId)[section].set(row.key, row.english);
+      const id = `${row.extensionId}\0${row.section}\0${row.key}`;
+      if (!extensionWork.has(id) || row.translationReview?.required) {
+        extensionWork.set(id, { extensionId: row.extensionId, section: row.section, key: row.key,
+          reason: row.translationReview?.required ? 'source-changed' : 'missing-translation' });
+      }
+    }
+  }
+  return {
+    version: '1.0.0',
+    $comment: 'English source work list. Entries in $reviewRequired need translation or source review before use in src/i18n/.',
+    contents: Object.fromEntries([...core].map(([id, keys]) => [id, Object.fromEntries(keys)])),
+    extensions: Object.fromEntries([...extensions].map(([id, sections]) => [id, {
+      version: '1.0.0', contents: Object.fromEntries(Object.entries(sections)
+        .filter(([, keys]) => keys.size).map(([section, keys]) => [section, Object.fromEntries(keys)]))
+    }])),
+    $reviewRequired: { core: [...coreWork.values()], extensions: [...extensionWork.values()] }
+  };
+}

package/scripts/lib/util.mjs

@@ -0,0 +1,146 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/** Resolve a path relative to the repository root. */
+export const p = (...segments) => path.join(ROOT, ...segments);
+
+export function readJson(file, fallback = undefined) {
+  try {
+    return JSON.parse(stripJsonComments(fs.readFileSync(file, 'utf8')));
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      if (fallback !== undefined) return fallback;
+      throw new Error(`File not found: ${file}`);
+    }
+    throw new Error(`Failed to parse JSON: ${file}\n${err.message}`);
+  }
+}
+
+export function writeJson(file, data, { pretty = true } = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(data, null, pretty ? 2 : 0) + '\n', 'utf8');
+}
+
+/**
+ * VS Code allows comments in product.json and argv.json, and this project allows
+ * them in config.json and in translation sources. Only comments outside string
+ * literals are removed.
+ */
+export function stripJsonComments(text) {
+  let out = '';
+  let inString = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    if (inLineComment) {
+      if (c === '\n') { inLineComment = false; out += c; }
+      continue;
+    }
+    if (inBlockComment) {
+      if (c === '*' && next === '/') { inBlockComment = false; i++; }
+      continue;
+    }
+    if (inString) {
+      out += c;
+      if (c === '\\') { out += text[++i] ?? ''; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === '/' && next === '/') { inLineComment = true; i++; continue; }
+    if (c === '/' && next === '*') { inBlockComment = true; i++; continue; }
+    out += c;
+  }
+  return out;
+}
+
+/** Deep merge where `override` wins. Arrays are replaced, not concatenated. */
+export function deepMerge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return structuredClone(override ?? base);
+  }
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    out[key] = isPlainObject(value) && isPlainObject(base[key])
+      ? deepMerge(base[key], value)
+      : structuredClone(value);
+  }
+  return out;
+}
+
+export const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+/** Files directly inside `dir` with the given extension, sorted by name. */
+export function listFiles(dir, ext) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith(ext))
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+export function rmrf(target) {
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code, s) => (USE_COLOR ? `\u001b[${code}m${s}\u001b[0m` : s);
+
+export const log = {
+  info: (...a) => console.log(paint(36, '·'), ...a),
+  ok: (...a) => console.log(paint(32, '+'), ...a),
+  warn: (...a) => console.warn(paint(33, '!'), ...a),
+  err: (...a) => console.error(paint(31, 'x'), ...a),
+  step: (title) => console.log('\n' + paint(1, title)),
+  plain: (...a) => console.log(...a)
+};
+
+export function fail(message) {
+  log.err(message);
+  process.exit(1);
+}
+
+export function loadConfig() {
+  const config = readJson(p('config.json'));
+
+  const required = ['publisher', 'namePrefix', 'version', 'engines', 'locales', 'modes', 'upstream', 'build', 'target'];
+  for (const key of required) {
+    if (config[key] === undefined) fail(`config.json is missing the required "${key}" field.`);
+  }
+  if (!Array.isArray(config.locales) || config.locales.length === 0) {
+    fail('config.json: "locales" must be a non-empty array.');
+  }
+  for (const locale of config.locales) {
+    for (const key of ['id', 'languageName', 'localizedLanguageName']) {
+      if (!locale[key]) fail(`config.json: locale entry ${JSON.stringify(locale.id ?? locale)} is missing "${key}".`);
+    }
+  }
+  if (String(config.publisher).startsWith('CHANGE-ME')) {
+    log.warn('config.json still has the placeholder "publisher". Packaging works, but set a real publisher id before publishing.');
+  }
+  return config;
+}
+
+/** Minimal `--flag`, `--key=value` and positional argument parser. */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const flags = {};
+  const positional = [];
+  for (const arg of argv) {
+    if (arg.startsWith('--')) {
+      const equal = arg.indexOf('=');
+      const key = arg.slice(2, equal < 0 ? undefined : equal);
+      const value = equal < 0 ? undefined : arg.slice(equal + 1);
+      flags[key] = value === undefined ? true : value === 'false' ? false : value;
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { flags, positional };
+}