i18n-lens-language-server 0.9.0 → 0.11.0

package/README.md

@@ -7,10 +7,11 @@ Zed extension plus Language Server for Vue, TypeScript, TSX, JavaScript and JSX.
 - Inline translation display via LSP inlay hints
 - Detect `$t`/`t`/`tc`/`$tc`/`i18n.t` calls, `v-t="'key'"`, `v-t="{ path: 'key' }"`, `<i18n-t keypath="key">` (Vue I18n), `<Trans i18nKey="key">` (react-i18next), and `formatMessage({ id: "key" })` (react-intl)
 - Hover: show all locale values for a key
-- Diagnostics: report missing keys, missing locale entries, and mismatched interpolation params
-- Quick fixes: add missing interpolation params to supported i18n calls
+- Diagnostics: report missing keys, missing locale entries, mismatched interpolation params, and (on locale files) keys whose params differ across languages
+- Quick fixes: add missing / remove unused interpolation params on supported i18n calls, and create a missing key in every locale file that lacks it
 - Completion: suggest existing i18n keys with default locale text
 - Definition: jump from a source key to its locale definition; when several locales define the key, pick which language file to open
+- References: from a key in a locale file (or a source usage), find every place the key is used across the project's source code
 
 ## Installation
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "i18n-lens-language-server",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
-  "description": "Language server for configurable i18n inlay hints, hover, completion, diagnostics, and definition in Vue/TS/TSX/JS.",
+  "description": "Language server for configurable i18n inlay hints, hover, completion, diagnostics, definition, and references in Vue/TS/TSX/JS.",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/core.js

@@ -171,7 +171,8 @@ function collectFunctionCallKeys(text, found) {
     const end = start + key.length;
     const args = splitArgsWithOffsets(callText.slice(1, -1));
     const paramsEdit = getParamsEdit(args.slice(1), parenOffset + 1, parenOffset + callText.length - 1);
-    found.push({ key, range: makeRange(text, start, end), startOffset: start, endOffset: end, providedParams: collectParamNames(args.slice(1)), paramsEdit });
+    const paramsObject = extractParamsObject(args.slice(1), parenOffset + 1);
+    found.push({ key, range: makeRange(text, start, end), startOffset: start, endOffset: end, providedParams: collectParamNames(args.slice(1)), paramsEdit, paramsObject });
   }
 }
 
@@ -190,7 +191,8 @@ function collectFormatMessageKeys(text, found) {
     const start = parenOffset + 1 + idArg.indexOf(key);
     const end = start + key.length;
     const paramsEdit = getParamsEdit(args.slice(1), parenOffset + 1, parenOffset + callText.length - 1);
-    found.push({ key, range: makeRange(text, start, end), startOffset: start, endOffset: end, providedParams: collectParamNames(args.slice(1)), paramsEdit });
+    const paramsObject = extractParamsObject(args.slice(1), parenOffset + 1);
+    found.push({ key, range: makeRange(text, start, end), startOffset: start, endOffset: end, providedParams: collectParamNames(args.slice(1)), paramsEdit, paramsObject });
   }
 }
 
@@ -285,19 +287,41 @@ function collectParamNames(args) {
     if (!trimmed.startsWith('{')) continue;
     const body = trimmed.slice(1, trimmed.lastIndexOf('}'));
     for (const part of splitArgs(body)) {
-      const m = part.trim().match(/^(?:['"]([^'"]+)['"]|([A-Za-z_$][\w$]*))\s*(?::|$)/);
-      const name = m && (m[1] || m[2]);
-      if (name && !part.trim().startsWith('...')) params.add(name);
+      const name = paramNameOf(part);
+      if (name) params.add(name);
     }
   }
   return [...params].sort();
 }
 
+function paramNameOf(part) {
+  const trimmed = String(part).trim();
+  if (trimmed.startsWith('...')) return undefined;
+  const m = trimmed.match(/^(?:['"]([^'"]+)['"]|([A-Za-z_$][\w$]*))\s*(?::|$)/);
+  return (m && (m[1] || m[2])) || undefined;
+}
+
+// Absolute span of the params object literal plus each top-level property's raw
+// text, so a code action can rebuild the object with unused params removed.
+function extractParamsObject(args, argsStartOffset) {
+  const objectArg = args.find((arg) => arg.text.startsWith('{') && arg.text.lastIndexOf('}') > 0);
+  if (!objectArg) return undefined;
+  const start = argsStartOffset + objectArg.start;
+  const body = objectArg.text.slice(1, objectArg.text.lastIndexOf('}'));
+  const props = splitArgsWithOffsets(body).map((part) => ({ name: paramNameOf(part.text), text: part.text }));
+  return { start, end: start + objectArg.text.length, props };
+}
+
 export function keyAtPosition(text, position) {
   const offset = positionToOffset(text, position);
   return extractI18nKeys(text).find((item) => item.startOffset <= offset && offset <= item.endOffset);
 }
 
+// Reverse of Go to Definition: every range in `text` (source code) that uses `key`.
+export function findCodeKeyRanges(text, key) {
+  return extractI18nKeys(text).filter((item) => item.key === key).map((item) => item.range);
+}
+
 export function positionToOffset(text, position) {
   const lines = text.split('\n');
   let offset = 0;
@@ -387,7 +411,11 @@ export function getDiagnostics(text, locales) {
         data: { key: item.key, missingLocales, missingInAllLocales },
       });
     }
-    if (missingLocales.length !== localeEntries.length) diagnostics.push(...getParamDiagnostics(item, localeEntries));
+    if (missingLocales.length !== localeEntries.length) {
+      diagnostics.push(...getParamDiagnostics(item, localeEntries));
+      const consistency = getLocaleParamConsistency(item.key, locales);
+      if (!consistency.consistent) diagnostics.push(paramInconsistencyDiagnostic(item.key, item.range, consistency.perLocale));
+    }
     return diagnostics;
   });
 }
@@ -416,19 +444,87 @@ function collectRequiredParams(key, localeEntries) {
   return [...params].sort();
 }
 
+// Compare the interpolation placeholders a key uses across every locale that
+// defines it. `consistent` is false when two locales that both define the key
+// carry different param sets (a translation forgot or renamed a placeholder).
+// Locales that do not define the key are ignored — that is a missing-key concern.
+export function getLocaleParamConsistency(key, locales) {
+  const perLocale = [];
+  for (const [name, locale] of Object.entries(locales || {})) {
+    const value = locale.flat?.[key];
+    if (value === undefined) continue;
+    perLocale.push({ name, params: extractPlaceholders(value) });
+  }
+  const union = [...new Set(perLocale.flatMap((entry) => entry.params))].sort();
+  const consistent = perLocale.length < 2
+    || perLocale.every((entry) => entry.params.length === union.length && union.every((param) => entry.params.includes(param)));
+  return { consistent, perLocale, union };
+}
+
+// Warnings for keys defined in `locale`'s file whose params disagree with the
+// same key in other locales, anchored at each key's position in the file text.
+export function getLocaleParamDiagnostics(locale, filePath, text, locales) {
+  if (!locale?.flat) return [];
+  const isJson = /\.json$/i.test(filePath);
+  const diagnostics = [];
+  for (const key of Object.keys(locale.flat)) {
+    const consistency = getLocaleParamConsistency(key, locales);
+    if (consistency.consistent) continue;
+    const lookupKey = lookupKeyForLocaleFile(locale, filePath, key);
+    const position = isJson ? findJsonKeyLocation(text, lookupKey) : findLocaleKeyLocation(text, lookupKey);
+    if (!position) continue;
+    const leaf = lookupKey.split('.').at(-1);
+    const end = { line: position.line, character: position.character + leaf.length + (isJson ? 2 : 0) };
+    diagnostics.push(paramInconsistencyDiagnostic(key, { start: position, end }, consistency.perLocale));
+  }
+  return diagnostics;
+}
+
+function paramInconsistencyDiagnostic(key, range, perLocale) {
+  return {
+    severity: 2,
+    range,
+    message: 'i18n params for "' + key + '" differ across locales — ' + formatPerLocaleParams(perLocale),
+    source: 'i18n-lens',
+    data: { key, paramInconsistency: perLocale },
+  };
+}
+
+function formatPerLocaleParams(perLocale) {
+  return perLocale
+    .map((entry) => entry.name + ': ' + (entry.params.length ? entry.params.map((p) => '{' + p + '}').join(', ') : '(none)'))
+    .join('; ');
+}
+
 export function getParamCodeActions(text, diagnostics = []) {
   const items = extractI18nKeys(text);
   return diagnostics.flatMap((diagnostic) => {
-    const missingParams = diagnostic.data?.missingParams;
-    if (!Array.isArray(missingParams) || missingParams.length === 0) return [];
     const item = items.find((candidate) => candidate.key === diagnostic.data?.key && sameRange(candidate.range, diagnostic.range));
-    if (!item?.paramsEdit) return [];
-    const newText = item.paramsEdit.prefix + missingParams.join(', ') + (item.paramsEdit.suffix || '');
-    return [{
-      title: 'Add missing i18n params: ' + missingParams.join(', '),
-      diagnostic,
-      edit: { range: makeRange(text, item.paramsEdit.insertOffset, item.paramsEdit.insertOffset), newText },
-    }];
+
+    const missingParams = diagnostic.data?.missingParams;
+    if (Array.isArray(missingParams) && missingParams.length > 0) {
+      if (!item?.paramsEdit) return [];
+      const newText = item.paramsEdit.prefix + missingParams.join(', ') + (item.paramsEdit.suffix || '');
+      return [{
+        title: 'Add missing i18n params: ' + missingParams.join(', '),
+        diagnostic,
+        edit: { range: makeRange(text, item.paramsEdit.insertOffset, item.paramsEdit.insertOffset), newText },
+      }];
+    }
+
+    const unusedParams = diagnostic.data?.unusedParams;
+    if (Array.isArray(unusedParams) && unusedParams.length > 0) {
+      if (!item?.paramsObject) return [];
+      const kept = item.paramsObject.props.filter((prop) => !unusedParams.includes(prop.name));
+      const rebuilt = kept.length ? '{ ' + kept.map((prop) => prop.text).join(', ') + ' }' : '{}';
+      return [{
+        title: 'Remove unused i18n params: ' + unusedParams.join(', '),
+        diagnostic,
+        edit: { range: makeRange(text, item.paramsObject.start, item.paramsObject.end), newText: rebuilt },
+      }];
+    }
+
+    return [];
   });
 }
 
@@ -516,6 +612,29 @@ export function collectLocaleKeyTargets(locales, key, localeTexts = {}, defaultL
     .filter((target) => target?.position);
 }
 
+// Inverse of findLocaleKeyTarget: given a caret position inside a locale file,
+// return the full flattened key it points at (so Find References can jump back
+// to the code). Reuses the same key->location logic as Go to Definition to stay
+// consistent; precise for JSON, best-effort (line-based) for TS/JS locale modules.
+export function localeKeyAtPosition(locale, filePath, text, position) {
+  if (!locale || !locale.flat || !text || !position) return undefined;
+  const isJson = /\.json$/i.test(filePath);
+  let lineFallback;
+  let lineFallbackCount = 0;
+  for (const fullKey of Object.keys(locale.flat)) {
+    const lookupKey = lookupKeyForLocaleFile(locale, filePath, fullKey);
+    const loc = isJson ? findJsonKeyLocation(text, lookupKey) : findLocaleKeyLocation(text, lookupKey);
+    if (!loc || loc.line !== position.line) continue;
+    const leaf = lookupKey.split('.').at(-1);
+    const tokenStart = loc.character;
+    const tokenEnd = tokenStart + leaf.length + (isJson ? 2 : 0);
+    if (position.character >= tokenStart && position.character <= tokenEnd) return fullKey;
+    lineFallback = fullKey;
+    lineFallbackCount++;
+  }
+  return lineFallbackCount === 1 ? lineFallback : undefined;
+}
+
 export function getCompletionPrefix(text, position) {
   const offset = positionToOffset(text, position);
   const before = text.slice(0, offset);
@@ -546,6 +665,85 @@ export function findJsonKeyLocation(jsonText, key) {
   return undefined;
 }
 
+// Surgically insert a dotted `key` into a JSON document, creating intermediate
+// objects as needed and preserving the rest of the file's formatting. Returns
+// the new text, or undefined if the JSON is unparseable or the key already exists.
+export function insertNestedJsonKey(jsonText, key, value = '') {
+  let root;
+  try { root = JSON.parse(jsonText); } catch { return undefined; }
+  if (!root || typeof root !== 'object' || Array.isArray(root)) return undefined;
+  if (getValueByKey(root, key) !== undefined) return undefined;
+
+  const parts = key.split('.');
+  let node = root;
+  let existingDepth = 0;
+  for (; existingDepth < parts.length - 1; existingDepth++) {
+    const next = node[parts[existingDepth]];
+    if (next && typeof next === 'object' && !Array.isArray(next)) node = next;
+    else break;
+  }
+
+  const span = findJsonObjectSpan(jsonText, parts.slice(0, existingDepth));
+  if (!span) return undefined;
+
+  const unit = detectIndentUnit(jsonText);
+  const snippet = buildNestedProperty(parts.slice(existingDepth), value, unit.repeat(existingDepth + 1), unit);
+  const inner = jsonText.slice(span.openBrace + 1, span.contentEnd).trim();
+  if (inner.length === 0) {
+    return jsonText.slice(0, span.openBrace + 1) + '\n' + snippet + '\n' + unit.repeat(existingDepth) + jsonText.slice(span.closeBrace);
+  }
+  const needsComma = jsonText[span.contentEnd - 1] !== ',';
+  return jsonText.slice(0, span.contentEnd) + (needsComma ? ',' : '') + '\n' + snippet + jsonText.slice(span.contentEnd);
+}
+
+function findJsonObjectSpan(jsonText, pathParts) {
+  let searchFrom = 0;
+  if (pathParts.length) {
+    const pos = findJsonKeyLocation(jsonText, pathParts.join('.'));
+    if (!pos) return undefined;
+    const colon = jsonText.indexOf(':', positionToOffset(jsonText, pos));
+    if (colon === -1) return undefined;
+    searchFrom = colon + 1;
+  }
+  const openBrace = jsonText.indexOf('{', searchFrom);
+  if (openBrace === -1) return undefined;
+  const closeBrace = matchBrace(jsonText, openBrace);
+  if (closeBrace === -1) return undefined;
+  let contentEnd = closeBrace;
+  while (contentEnd > openBrace + 1 && /\s/.test(jsonText[contentEnd - 1])) contentEnd--;
+  return { openBrace, closeBrace, contentEnd };
+}
+
+function matchBrace(text, open) {
+  let depth = 0;
+  let quote = false;
+  let escaped = false;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') quote = false;
+      continue;
+    }
+    if (ch === '"') quote = true;
+    else if (ch === '{') depth++;
+    else if (ch === '}' && --depth === 0) return i;
+  }
+  return -1;
+}
+
+function detectIndentUnit(jsonText) {
+  const match = jsonText.match(/\n([ \t]+)\S/);
+  return match ? match[1] : '  ';
+}
+
+function buildNestedProperty(parts, value, indent, unit) {
+  const keyStr = JSON.stringify(parts[0]);
+  if (parts.length === 1) return indent + keyStr + ': ' + JSON.stringify(value);
+  return indent + keyStr + ': {\n' + buildNestedProperty(parts.slice(1), value, indent + unit, unit) + '\n' + indent + '}';
+}
+
 
 export function parseTsLocaleModule(text, fileName = 'index.ts') {
   const result = {};

package/server/index.js

@@ -8,12 +8,16 @@ import {
   flattenLocale,
   buildHoverMarkdown,
   getDiagnostics,
+  getLocaleParamDiagnostics,
   getParamCodeActions,
+  insertNestedJsonKey,
   getCompletions,
   getCompletionPrefix,
   keyAtPosition,
   parseTsLocaleModule,
   collectLocaleKeyTargets,
+  localeKeyAtPosition,
+  findCodeKeyRanges,
   getInlayHints,
   normalizeI18nLensConfig,
   mergeI18nLensConfig,
@@ -43,7 +47,7 @@ connection.onInitialize((params) => {
   zedSettingsConfig = normalizeIncomingSettings(params.initializationOptions);
   loadConfig();
   watchConfigFile();
-  return { capabilities: { textDocumentSync: TextDocumentSyncKind.Incremental, hoverProvider: true, completionProvider: { triggerCharacters: ['.', '"', "'"] }, definitionProvider: true, inlayHintProvider: true, codeActionProvider: true } };
+  return { capabilities: { textDocumentSync: TextDocumentSyncKind.Incremental, hoverProvider: true, completionProvider: { triggerCharacters: ['.', '"', "'"] }, definitionProvider: true, referencesProvider: true, inlayHintProvider: true, codeActionProvider: true } };
 });
 
 connection.onInitialized(() => {
@@ -81,6 +85,7 @@ connection.onHover((params) => {
 });
 
 connection.onCompletion((params) => {
+  if (!isSourceFile(params.textDocument.uri)) return [];
   const doc = documents.get(params.textDocument.uri);
   const context = getProjectContext(params.textDocument.uri);
   const { locales } = loadLocalesForContext(context);
@@ -89,6 +94,7 @@ connection.onCompletion((params) => {
 });
 
 connection.languages.inlayHint.on((params) => {
+  if (!isSourceFile(params.textDocument.uri)) return [];
   const doc = documents.get(params.textDocument.uri);
   if (!doc) return [];
   const context = getProjectContext(params.textDocument.uri);
@@ -112,18 +118,91 @@ connection.onDefinition((params) => {
   return locations.length ? locations : null;
 });
 
+connection.onReferences((params) => {
+  const uri = params.textDocument.uri;
+  const context = getProjectContext(uri);
+  const key = resolveKeyAtPosition(uri, params.position, context);
+  if (!key) return null;
+
+  const locations = collectCodeReferences(context, key);
+  if (params.context?.includeDeclaration) {
+    const { locales, localeTexts } = loadLocalesForContext(context);
+    const keyTokenLength = key.split('.').at(-1).length + 2;
+    for (const { filePath, position } of collectLocaleKeyTargets(locales, key, localeTexts, context.config.defaultLocale)) {
+      locations.push({
+        uri: pathToFileURL(filePath).toString(),
+        range: { start: position, end: { line: position.line, character: position.character + keyTokenLength } },
+      });
+    }
+  }
+  return locations.length ? locations : null;
+});
+
 connection.onCodeAction((params) => {
   const doc = documents.get(params.textDocument.uri);
-  if (!doc) return [];
-  return getParamCodeActions(doc.getText(), params.context.diagnostics)
-    .map((action) => ({
-      title: action.title,
-      kind: CodeActionKind.QuickFix,
-      diagnostics: [action.diagnostic],
-      edit: { changes: { [params.textDocument.uri]: [action.edit] } },
-    }));
+  const diagnostics = params.context.diagnostics || [];
+  const actions = [];
+  if (doc) {
+    for (const action of getParamCodeActions(doc.getText(), diagnostics)) {
+      actions.push({
+        title: action.title,
+        kind: CodeActionKind.QuickFix,
+        diagnostics: [action.diagnostic],
+        edit: { changes: { [params.textDocument.uri]: [action.edit] } },
+      });
+    }
+  }
+  actions.push(...getCreateKeyActions(diagnostics, getProjectContext(params.textDocument.uri)));
+  return actions;
 });
 
+// Quick fix for a "missing i18n key" diagnostic: create the key (empty value) in
+// every locale file that lacks it, as a cross-file workspace edit. Only single
+// flat JSON locale files are supported; nested/TS locales are skipped.
+function getCreateKeyActions(diagnostics, context) {
+  const { locales, localeTexts } = loadLocalesForContext(context);
+  const actions = [];
+  for (const diagnostic of diagnostics) {
+    const key = diagnostic.data?.key;
+    const missingLocales = diagnostic.data?.missingLocales;
+    if (!key || !Array.isArray(missingLocales) || missingLocales.length === 0) continue;
+
+    const changes = {};
+    for (const name of missingLocales) {
+      const filePath = flatLocaleFile(locales[name]);
+      if (!filePath) continue;
+      const text = localeTexts[filePath] ?? readFileSafe(filePath);
+      if (text === undefined) continue;
+      const newText = insertNestedJsonKey(text, key, '');
+      if (newText === undefined) continue;
+      changes[pathToFileURL(filePath).toString()] = [fullDocumentEdit(text, newText)];
+    }
+
+    const fileCount = Object.keys(changes).length;
+    if (fileCount === 0) continue;
+    actions.push({
+      title: `Create i18n key "${key}" in ${fileCount} locale file(s)`,
+      kind: CodeActionKind.QuickFix,
+      diagnostics: [diagnostic],
+      edit: { changes },
+    });
+  }
+  return actions;
+}
+
+// A locale backed by a single flat .json file (not a nested directory locale).
+function flatLocaleFile(locale) {
+  if (!locale || !/\.json$/i.test(locale.path || '')) return undefined;
+  const files = locale.files?.length ? locale.files : [locale.path];
+  return files.length === 1 && files[0] === locale.path ? locale.path : undefined;
+}
+
+function fullDocumentEdit(oldText, newText) {
+  const lines = oldText.split('\n');
+  const endLine = lines.length - 1;
+  return { range: { start: { line: 0, character: 0 }, end: { line: endLine, character: lines[endLine].length } }, newText };
+}
+
 function getProjectContext(uri) {
   loadConfigIfChanged();
   const filePath = uri ? fileURLToPath(uri) : workspaceRoot;
@@ -220,13 +299,84 @@ function normalizeIncomingSettings(value) {
 }
 
 function validate(document) {
-  if (!isSourceFile(document.uri)) return;
   const context = getProjectContext(document.uri);
   const { locales } = loadLocalesForContext(context);
-  connection.sendDiagnostics({ uri: document.uri, diagnostics: getDiagnostics(document.getText(), locales) });
+  if (isSourceFile(document.uri)) {
+    connection.sendDiagnostics({ uri: document.uri, diagnostics: getDiagnostics(document.getText(), locales) });
+    return;
+  }
+  const locale = findLocaleForFile(locales, fileURLToPath(document.uri));
+  if (!locale) return;
+  connection.sendDiagnostics({ uri: document.uri, diagnostics: getLocaleParamDiagnostics(locale, fileURLToPath(document.uri), document.getText(), locales) });
 }
 function isSourceFile(uri) { return /\.(vue|tsx?|jsx?)$/i.test(uri); }
 
+const IGNORED_SCAN_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'vendor', '.output', '.next', '.nuxt', '.cache']);
+const MAX_SCAN_FILES = 5000;
+
+// Resolve the i18n key under `position`, whether the caret sits on a t()/keypath
+// usage in source code or on a key inside a locale JSON/TS file.
+function resolveKeyAtPosition(uri, position, context) {
+  const filePath = fileURLToPath(uri);
+  const text = documents.get(uri)?.getText() ?? readFileSafe(filePath);
+  if (!text) return undefined;
+  if (isSourceFile(uri)) return keyAtPosition(text, position)?.key;
+  const { locales } = loadLocalesForContext(context);
+  const locale = findLocaleForFile(locales, filePath);
+  return locale ? localeKeyAtPosition(locale, filePath, text, position) : undefined;
+}
+
+function findLocaleForFile(locales, filePath) {
+  const target = path.resolve(filePath);
+  for (const locale of Object.values(locales)) {
+    const files = locale.files?.length ? locale.files : (locale.path ? [locale.path] : []);
+    if (files.some((file) => path.resolve(file) === target)) return locale;
+  }
+  return undefined;
+}
+
+// Every source-code usage of `key` within the project/package root. Prefers the
+// in-memory text of open (possibly unsaved) documents over the on-disk copy.
+function collectCodeReferences(context, key) {
+  const openTextByPath = new Map();
+  for (const doc of documents.all()) {
+    try { openTextByPath.set(path.resolve(fileURLToPath(doc.uri)), doc.getText()); } catch { /* non-file uri */ }
+  }
+  const locations = [];
+  for (const filePath of collectSourceFiles(context.root)) {
+    const text = openTextByPath.get(path.resolve(filePath)) ?? readFileSafe(filePath);
+    if (!text) continue;
+    for (const range of findCodeKeyRanges(text, key)) {
+      locations.push({ uri: pathToFileURL(filePath).toString(), range });
+    }
+  }
+  return locations;
+}
+
+function collectSourceFiles(root) {
+  const files = [];
+  const stack = [root];
+  while (stack.length && files.length < MAX_SCAN_FILES) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.startsWith('.') || IGNORED_SCAN_DIRS.has(entry.name)) continue;
+        stack.push(full);
+      } else if (isSourceFile(entry.name)) {
+        files.push(full);
+      }
+    }
+  }
+  return files;
+}
+
+function readFileSafe(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return undefined; }
+}
+
 function getAllConfiguredContexts() {
   loadConfigIfChanged();
   return [resolveProjectContext(workspaceRoot, workspaceRoot, config), ...config.packages.map((pkg) => ({