@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/index/queryIndex.js

@@ -23,6 +23,17 @@ function setBoundedCacheEntry(map, key, value, maxEntries = MAX_CACHE_ENTRIES) {
   }
 }
 
+// Returns the artifact's item rows as plain objects, dropping poisoned rows
+// (null, undefined, primitives). Hand-corrupted or truncated `.cache/index/*.json`
+// files can carry `items: [null]` or `items: "corrupted"` — every consumer that
+// dereferences `item.filePath` must see only object rows.
+function safeItems(artifact) {
+  if (!artifact || typeof artifact !== 'object' || !Array.isArray(artifact.items)) {
+    return [];
+  }
+  return artifact.items.filter((entry) => entry && typeof entry === 'object');
+}
+
 export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5 } = {}) {
   const normalizedQuery = String(query ?? '').trim();
   if (!normalizedQuery) {
@@ -54,7 +65,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
 
     const directScores = new Map();
 
-    for (const file of files.items ?? []) {
+    for (const file of safeItems(files)) {
       const filePath = file.filePath;
       if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) {
         continue;
@@ -161,7 +172,7 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
     return Object.freeze([]);
   }
 
-  const rows = (safeSymbolsArtifact.items ?? [])
+  const rows = safeItems(safeSymbolsArtifact)
     .filter((item) => item?.filePath === filePath && item?.line !== null && item?.line !== undefined)
     .filter((item) => item?.type !== 'callable' || isFunctionLikeSignature(item?.signature))
     .sort((a, b) => a.line - b.line);
@@ -226,10 +237,10 @@ async function loadQuerySearchBundle(rootDir) {
         .then(([files, symbols]) => {
           const safeFiles = ensureArtifact(files);
           const safeSymbols = ensureArtifact(symbols);
-          const symbolMap = groupBy(safeSymbols.items ?? [], (item) => item.filePath);
+          const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
           return {
             files: safeFiles,
-            searchDescriptorsByFile: buildFileSearchDescriptors(safeFiles.items ?? [], symbolMap),
+            searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
           };
         })
         .catch((error) => {
@@ -263,24 +274,24 @@ async function loadQuerySupportBundle(rootDir) {
           const safeTestsMap = ensureArtifact(testsMap);
           const safeHotspots = ensureArtifact(hotspots);
           const safeArchetypes = ensureArtifact(archetypes);
-          const indexedFileSet = new Set((safeFiles.items ?? []).map((item) => item.filePath));
-          const aliasContextPromise = importsNeedAliasContext(safeImports.items ?? [])
+          const indexedFileSet = new Set(safeItems(safeFiles).map((item) => item.filePath));
+          const aliasContextPromise = importsNeedAliasContext(safeItems(safeImports))
             ? loadImportAliasContext({ rootDir: absoluteRoot })
             : Promise.resolve(null);
           return aliasContextPromise.then((importAliasContext) => {
             const { resolvedImportsBySource, importersByTarget } = buildResolvedImportGraphs(
               absoluteRoot,
-              safeImports.items ?? [],
+              safeItems(safeImports),
               indexedFileSet,
               importAliasContext,
             );
 
             return {
-              hotspotScores: new Map((safeHotspots.items ?? []).map((item) => [item.filePath, item.count])),
-              testsMapBySource: new Map((safeTestsMap.items ?? []).map((item) => [item.sourceFile, item.tests ?? []])),
+              hotspotScores: new Map(safeItems(safeHotspots).map((item) => [item.filePath, item.count])),
+              testsMapBySource: new Map(safeItems(safeTestsMap).map((item) => [item.sourceFile, item.tests ?? []])),
               resolvedImportsBySource,
               importersByTarget,
-              archetypeByFile: new Map((safeArchetypes.items ?? []).map((item) => [item.filePath, item.archetype])),
+              archetypeByFile: new Map(safeItems(safeArchetypes).map((item) => [item.filePath, item.archetype])),
             };
           });
         })
@@ -607,11 +618,15 @@ export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5
   const analogPromise = readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs)
     .then((analogs) => {
       const safeAnalogs = ensureArtifact(analogs);
-      const entry = (safeAnalogs.items ?? []).find((item) => item.filePath === normalizedFilePath);
+      const entry = safeItems(safeAnalogs).find((item) => item.filePath === normalizedFilePath);
       if (!entry) {
         return Object.freeze([]);
       }
-      return freezeAnalogResults(entry.analogs?.slice(0, limit) ?? []);
+      // `entry.analogs` is an item-row field that can be hand-corrupted into a
+      // truthy non-array (e.g. analogs: 42) — `?.slice` and `?? []` do not fire
+      // on those, so coerce before freezeAnalogResults' .map.
+      const entryAnalogs = Array.isArray(entry.analogs) ? entry.analogs : [];
+      return freezeAnalogResults(entryAnalogs.slice(0, limit));
     })
     .catch((error) => {
       ANALOG_RESULT_CACHE.delete(analogCacheKey);
@@ -675,8 +690,14 @@ function ensureArtifact(artifact) {
   }
   // A schema-current artifact whose `items` is not an array (truncated or
   // hand-corrupted JSON) must degrade to an empty item list — callers iterate
-  // `items` unconditionally and a non-array value crashes the query path.
-  return Array.isArray(artifact.items) ? artifact : { ...artifact, items: [] };
+  // `items` unconditionally and a non-array value crashes the query path. Rows
+  // that are not objects (null entries from partial writes) are dropped too.
+  return {
+    ...artifact,
+    items: Array.isArray(artifact.items)
+      ? artifact.items.filter((entry) => entry && typeof entry === 'object')
+      : [],
+  };
 }
 
 function escapeJsonString(value) {

package/src/index/relatedTests.js

@@ -123,8 +123,12 @@ export function buildRelatedTestLookups({
   relationsArtifact = { items: [] },
 } = {}) {
   return {
-    analogsMap: new Map((analogsArtifact.items ?? []).map((item) => [item.filePath, item.analogs ?? []])),
-    relationsMap: new Map((relationsArtifact.items ?? []).map((item) => [item.filePath, item.relations ?? {}])),
+    analogsMap: new Map(
+      safeItems(analogsArtifact).map((item) => [item.filePath, safeArray(item.analogs)]),
+    ),
+    relationsMap: new Map(
+      safeItems(relationsArtifact).map((item) => [item.filePath, normalizeRelations(item.relations)]),
+    ),
   };
 }
 
@@ -148,7 +152,7 @@ export function inferRelatedTestsFromArtifacts({
 
   for (const [candidateRank, candidateFile] of normalizedCandidates.entries()) {
     const rankPenalty = candidateRank * 5;
-    const relations = relationsMap.get(candidateFile) ?? {};
+    const relations = normalizeRelations(relationsMap.get(candidateFile));
 
     addTestsFromSource({
       sourceFilePath: candidateFile,
@@ -158,7 +162,7 @@ export function inferRelatedTestsFromArtifacts({
       reason: `direct test for ${candidateFile}`,
     });
 
-    for (const siblingFile of (relations.siblings ?? []).slice(0, 3)) {
+    for (const siblingFile of safeArray(relations.siblings).slice(0, 3)) {
       addTestsFromSource({
         sourceFilePath: siblingFile,
         relationsMap,
@@ -168,7 +172,9 @@ export function inferRelatedTestsFromArtifacts({
       });
     }
 
-    for (const analog of (analogsMap.get(candidateFile) ?? []).slice(0, 3)) {
+    for (const analog of safeArray(analogsMap.get(candidateFile))
+      .filter((analogRow) => analogRow && typeof analogRow.filePath === 'string')
+      .slice(0, 3)) {
       addTestsFromSource({
         sourceFilePath: analog.filePath,
         relationsMap,
@@ -179,7 +185,7 @@ export function inferRelatedTestsFromArtifacts({
     }
 
     for (const { key, label } of RELATED_TEST_RELATION_TYPES) {
-      for (const relatedFile of (relations[key] ?? []).slice(0, 2)) {
+      for (const relatedFile of safeArray(relations[key]).slice(0, 2)) {
         addTestsFromSource({
           sourceFilePath: relatedFile,
           relationsMap,
@@ -209,7 +215,7 @@ async function readArtifact(rootDir, artifactName) {
       RELATED_TEST_ARTIFACT_CACHE,
       artifactPath,
       fs.readFile(artifactPath, 'utf8')
-        .then((content) => JSON.parse(content))
+        .then((content) => ensureArtifact(JSON.parse(content)))
         .catch(() => {
           RELATED_TEST_ARTIFACT_CACHE.delete(artifactPath);
           return { items: [] };
@@ -220,6 +226,42 @@ async function readArtifact(rootDir, artifactName) {
   return RELATED_TEST_ARTIFACT_CACHE.get(artifactPath);
 }
 
+// Mirrors ensureArtifact in queryIndex.js: a shape-corrupt artifact (non-object
+// root, non-array `items`, or null item rows) degrades to an empty item list so
+// triage/context survive hand-edited or truncated `.cache/index/*.json` files.
+function ensureArtifact(artifact) {
+  if (!artifact || typeof artifact !== 'object') {
+    return { items: [] };
+  }
+  return { ...artifact, items: safeItems(artifact) };
+}
+
+function safeItems(artifact) {
+  if (!artifact || typeof artifact !== 'object' || !Array.isArray(artifact.items)) {
+    return [];
+  }
+  return artifact.items.filter((entry) => entry && typeof entry === 'object');
+}
+
+// Item-row fields (`analogs`, `relations.*`) can be hand-edited into non-array
+// shapes (e.g. analogs: "corrupted"). `?? []` does not fire on truthy
+// non-arrays, so coerce when building the lookup maps and again at consumers —
+// inferRelatedTestsFromArtifacts also accepts foreign maps.
+function safeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeRelations(relations) {
+  if (!relations || typeof relations !== 'object') {
+    return {};
+  }
+  const normalized = { ...relations };
+  for (const key of ['tests', 'siblings', 'styles', ...RELATED_TEST_RELATION_TYPES.map(({ key }) => key)]) {
+    normalized[key] = safeArray(normalized[key]);
+  }
+  return normalized;
+}
+
 function addTestsFromSource({
   sourceFilePath,
   relationsMap,
@@ -231,7 +273,7 @@ function addTestsFromSource({
     return;
   }
 
-  const tests = relationsMap.get(sourceFilePath)?.tests ?? [];
+  const tests = safeArray(relationsMap.get(sourceFilePath)?.tests);
   for (const testFilePath of tests) {
     if (!suggestions.has(testFilePath)) {
       suggestions.set(testFilePath, {

package/src/index/resolveContext.js

@@ -103,11 +103,13 @@ export async function resolveContext({
     const rels = relationsMap.get(primary) ?? {};
 
     // Related tests
-    for (const testPath of rels.tests ?? []) {
+    for (const testPath of Array.isArray(rels.tests) ? rels.tests : []) {
       addExplainedFile(result, 'relatedTests', testPath, `test linked to ${primary}`);
     }
 
-    for (const stylePath of rels.styles ?? []) {
+    // `styles` is a relations field that can carry a truthy non-array after
+    // hand-corruption (relations.styles: 42) — `?? []` does not fire on it.
+    for (const stylePath of Array.isArray(rels.styles) ? rels.styles : []) {
       addExplainedFile(result, 'styleFiles', stylePath, `style imported by ${primary}`);
     }
   }
@@ -160,8 +162,11 @@ export async function resolveContext({
 
     // Step 3: Find analog files for primary targets
     for (const primary of result.primaryTargets.slice(0, 2)) {
-      const analogs = analogsMap.get(primary) ?? [];
-      for (const analog of analogs.slice(0, 3)) {
+      const rawAnalogs = analogsMap.get(primary);
+      const analogs = Array.isArray(rawAnalogs) ? rawAnalogs : [];
+      for (const analog of analogs
+        .filter((analogRow) => analogRow && typeof analogRow.filePath === 'string')
+        .slice(0, 3)) {
         if (result.primaryTargets.includes(analog.filePath)) {
           continue;
         }

package/src/manifest/selectItems.js

@@ -18,8 +18,12 @@ export const OPTIONAL_ADAPTER_ITEM_IDS = new Set([
   'multi-omp-agent-ukit-vision-analyst',
 ]);
 
-function resolveItemOrder(items) {
-  const itemById = new Map(items.map((item) => [item.id, item]));
+// Resolve installation order over the selected items, auto-including required
+// dependencies that were filtered out of the selection (e.g. by pack or adapter
+// filtering). `requires` is a hard dependency, so a dep that exists in the
+// manifest is pulled in transitively; only deps absent from `allItems` throw.
+function resolveItemOrder(items, allItems) {
+  const itemById = new Map((allItems ?? items).map((item) => [item.id, item]));
   const visiting = new Set();
   const visited = new Set();
   const ordered = [];
@@ -81,5 +85,5 @@ export function selectManifestItems({ items, detectedPacks, selectedAdapterItemI
     return true;
   });
 
-  return resolveItemOrder(selected);
+  return resolveItemOrder(selected, items);
 }

package/src/render/instructionRenderer.js

@@ -183,19 +183,30 @@ const SOURCE_FILES = {
 /**
  * Read layout + sources + repo-vars + package.json version from disk, render
  * all outputs, and (write=true) write each target. Returns Map<target, content>.
+ * FR-015: every input read/parse failure is rethrown as a typed
+ * `Failed to read render input <rel>: <code|message>` naming the rel path.
+ * FR-016: target parent dirs are created before each write.
  */
 export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}) {
   const abs = (p) => path.join(repoRoot, p);
-  const layout = YAML.parse(
-    fs.readFileSync(abs('template_project/instructions/layout.yaml'), 'utf8'),
+  const readInput = (rel, parse) => {
+    try {
+      return parse(fs.readFileSync(abs(rel), 'utf8'));
+    } catch (err) {
+      const reason = err && err.code ? err.code : err && err.message ? err.message : String(err);
+      throw new Error(`Failed to read render input ${rel}: ${reason}`);
+    }
+  };
+  const layout = readInput('template_project/instructions/layout.yaml', (text) =>
+    YAML.parse(text),
   );
   const repoVars =
-    YAML.parse(fs.readFileSync(abs('template_project/instructions/repo-vars.yaml'), 'utf8')) || {};
-  const pkg = JSON.parse(fs.readFileSync(abs('package.json'), 'utf8'));
+    readInput('template_project/instructions/repo-vars.yaml', (text) => YAML.parse(text)) || {};
+  const pkg = readInput('package.json', (text) => JSON.parse(text));
 
   const sourceTexts = {};
   for (const [name, rel] of Object.entries(SOURCE_FILES)) {
-    sourceTexts[name] = fs.readFileSync(abs(rel), 'utf8');
+    sourceTexts[name] = readInput(rel, (text) => text);
   }
 
   const vars = { ...repoVars, ukit: { ...(repoVars.ukit || {}), version: pkg.version } };
@@ -203,6 +214,7 @@ export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}
 
   if (write) {
     for (const [target, content] of rendered) {
+      fs.mkdirSync(path.dirname(abs(target)), { recursive: true });
       fs.writeFileSync(abs(target), content);
     }
   }

package/template_project/.claude/ukit/index/lib/index-core.mjs

@@ -314,9 +314,9 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
       && Array.isArray(previousCallsArtifact.items);
 
     if (canReuseParsedArtifacts) {
-      const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
-      const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item.from);
-      const previousCallsByPath = groupBy(previousCallsArtifact.items ?? [], (item) => item.filePath);
+      const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item?.filePath);
+      const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item?.from);
+      const previousCallsByPath = groupBy(previousCallsArtifact.items ?? [], (item) => item?.filePath);
 
       for (const filePath of reusableCodeFiles) {
         symbols.push(...(previousSymbolsByPath.get(filePath) ?? []));
@@ -888,9 +888,9 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   }
   const styleFilePaths = styleEntries.filter(Boolean).map((entry) => normalizeRelative(absoluteRoot, entry.absolutePath));
 
-  const previousSymbolsByPath = groupBy(symbolsArtifact.items ?? [], (item) => item.filePath);
-  const previousImportsByPath = groupBy(importsArtifact.items ?? [], (item) => item.from);
-  const previousCallsByPath = groupBy(callsArtifact.items ?? [], (item) => item.filePath);
+  const previousSymbolsByPath = groupBy(symbolsArtifact.items ?? [], (item) => item?.filePath);
+  const previousImportsByPath = groupBy(importsArtifact.items ?? [], (item) => item?.from);
+  const previousCallsByPath = groupBy(callsArtifact.items ?? [], (item) => item?.filePath);
 
   const parsedSet = new Set(parsedFiles);
   const codeFiles = mergedFileRecords.filter((record) => CODE_EXTENSIONS.has(record.ext));
@@ -1149,7 +1149,7 @@ export async function getFileOutline({ rootDir = process.cwd(), filePath, limit
     return Object.freeze([]);
   }
 
-  const rows = (safeSymbolsArtifact.items ?? [])
+  const rows = safeItems(safeSymbolsArtifact)
     .filter((item) => item?.filePath === filePath && item?.line !== null && item?.line !== undefined)
     .filter((item) => item?.type !== 'callable' || isFunctionLikeSignature(item?.signature))
     .sort((a, b) => a.line - b.line);
@@ -1196,7 +1196,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
     const includeLikelyTestFiles = shouldIncludeLikelyTestFiles(queryDescriptor);
 
     const directScores = new Map();
-    for (const file of files.items ?? []) {
+    for (const file of safeItems(files)) {
       const filePath = file.filePath;
       if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) continue;
       const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
@@ -1275,9 +1275,13 @@ export async function queryAnalog({ rootDir = process.cwd(), filePath, limit = 5
   const analogPromise = readArtifact(absoluteRoot, INDEX_ARTIFACTS.analogs)
     .then((analogs) => {
       const safeAnalogs = ensureArtifact(analogs);
-      const entry = (safeAnalogs.items ?? []).find((item) => item.filePath === normalizedFilePath);
+      const entry = safeItems(safeAnalogs).find((item) => item.filePath === normalizedFilePath);
       if (!entry) return Object.freeze([]);
-      return freezeAnalogResults(entry.analogs?.slice(0, limit) ?? []);
+      // `entry.analogs` is an item-row field that can be hand-corrupted into a
+      // truthy non-array (e.g. analogs: 42) — `?.slice` and `?? []` do not fire
+      // on those, so coerce before freezeAnalogResults' .map.
+      const entryAnalogs = Array.isArray(entry.analogs) ? entry.analogs : [];
+      return freezeAnalogResults(entryAnalogs.slice(0, limit));
     })
     .catch((error) => {
       ANALOG_RESULT_CACHE.delete(analogCacheKey);
@@ -1336,14 +1340,31 @@ function freezeQueryResults(results) {
 function freezeAnalogResults(results) {
   return Object.freeze(results.map((item) => Object.freeze({ ...item })));
 }
+// Returns the artifact's item rows as plain objects, dropping poisoned rows
+// (null, undefined, primitives). Hand-corrupted or truncated `.cache/index/*.json`
+// files can carry `items: [null]` or `items: "corrupted"` — every consumer that
+// dereferences `item.filePath` must see only object rows.
+function safeItems(artifact) {
+  if (!artifact || typeof artifact !== 'object' || !Array.isArray(artifact.items)) {
+    return [];
+  }
+  return artifact.items.filter((entry) => entry && typeof entry === 'object');
+}
+
 function ensureArtifact(artifact) {
   if (!artifact || typeof artifact !== 'object') {
     return { items: [] };
   }
   // A schema-current artifact whose `items` is not an array (truncated or
   // hand-corrupted JSON) must degrade to an empty item list — callers iterate
-  // `items` unconditionally and a non-array value crashes the query path.
-  return Array.isArray(artifact.items) ? artifact : { ...artifact, items: [] };
+  // `items` unconditionally and a non-array value crashes the query path. Rows
+  // that are not objects (null entries from partial writes) are dropped too.
+  return {
+    ...artifact,
+    items: Array.isArray(artifact.items)
+      ? artifact.items.filter((entry) => entry && typeof entry === 'object')
+      : [],
+  };
 }
 
 function escapeJsonString(value) {
@@ -1359,6 +1380,8 @@ const TASK_TYPE_BUDGETS = {
   'non-trivial': { minFiles: 4, maxFiles: 8 },
 };
 
+const TRIVIAL_SIGNALS = ['typo', 'label', 'text', 'rename', 'color', 'spacing', 'toggle', 'config', 'comment'];
+
 const RISKY_SIGNALS = [
   'auth', 'authentication', 'authorization', 'security', 'migration', 'uninstall',
   'password', 'token', 'permission', 'delete all', 'drop table', 'race', 'flaky',
@@ -1449,10 +1472,12 @@ export async function resolveContext({
 
   for (const primary of result.primaryTargets) {
     const rels = relationsMap.get(primary) ?? {};
-    for (const testPath of rels.tests ?? []) {
+    for (const testPath of Array.isArray(rels.tests) ? rels.tests : []) {
       addExplainedFile(result, 'relatedTests', testPath, `test linked to ${primary}`);
     }
-    for (const stylePath of rels.styles ?? []) {
+    // `styles` is a relations field that can carry a truthy non-array after
+    // hand-corruption (relations.styles: 42) — `?? []` does not fire on it.
+    for (const stylePath of Array.isArray(rels.styles) ? rels.styles : []) {
       addExplainedFile(result, 'styleFiles', stylePath, `style imported by ${primary}`);
     }
   }
@@ -1501,8 +1526,11 @@ export async function resolveContext({
     });
 
     for (const primary of result.primaryTargets.slice(0, 2)) {
-      const analogs = analogsMap.get(primary) ?? [];
-      for (const analog of analogs.slice(0, 3)) {
+      const rawAnalogs = analogsMap.get(primary);
+      const analogs = Array.isArray(rawAnalogs) ? rawAnalogs : [];
+      for (const analog of analogs
+        .filter((analogRow) => analogRow && typeof analogRow.filePath === 'string')
+        .slice(0, 3)) {
         if (result.primaryTargets.includes(analog.filePath)) continue;
         addExplainedFile(
           result,
@@ -1696,8 +1724,12 @@ function buildRelatedTestLookups({
   relationsArtifact = { items: [] },
 } = {}) {
   return {
-    analogsMap: new Map((analogsArtifact.items ?? []).map((item) => [item.filePath, item.analogs ?? []])),
-    relationsMap: new Map((relationsArtifact.items ?? []).map((item) => [item.filePath, item.relations ?? {}])),
+    analogsMap: new Map(
+      safeItems(analogsArtifact).map((item) => [item.filePath, safeArray(item.analogs)]),
+    ),
+    relationsMap: new Map(
+      safeItems(relationsArtifact).map((item) => [item.filePath, normalizeRelations(item.relations)]),
+    ),
   };
 }
 
@@ -1721,7 +1753,7 @@ function inferRelatedTestsFromArtifacts({
 
   for (const [candidateRank, candidateFile] of normalizedCandidates.entries()) {
     const rankPenalty = candidateRank * 5;
-    const relations = relationsMap.get(candidateFile) ?? {};
+    const relations = normalizeRelations(relationsMap.get(candidateFile));
 
     addTestsFromSource({
       sourceFilePath: candidateFile,
@@ -1731,7 +1763,7 @@ function inferRelatedTestsFromArtifacts({
       reason: `direct test for ${candidateFile}`,
     });
 
-    for (const siblingFile of (relations.siblings ?? []).slice(0, 3)) {
+    for (const siblingFile of safeArray(relations.siblings).slice(0, 3)) {
       addTestsFromSource({
         sourceFilePath: siblingFile,
         relationsMap,
@@ -1741,7 +1773,9 @@ function inferRelatedTestsFromArtifacts({
       });
     }
 
-    for (const analog of (analogsMap.get(candidateFile) ?? []).slice(0, 3)) {
+    for (const analog of safeArray(analogsMap.get(candidateFile))
+      .filter((analogRow) => analogRow && typeof analogRow.filePath === 'string')
+      .slice(0, 3)) {
       addTestsFromSource({
         sourceFilePath: analog.filePath,
         relationsMap,
@@ -1752,7 +1786,7 @@ function inferRelatedTestsFromArtifacts({
     }
 
     for (const { key, label } of RELATED_TEST_RELATION_TYPES) {
-      for (const relatedFile of (relations[key] ?? []).slice(0, 2)) {
+      for (const relatedFile of safeArray(relations[key]).slice(0, 2)) {
         addTestsFromSource({
           sourceFilePath: relatedFile,
           relationsMap,
@@ -1785,7 +1819,7 @@ function addTestsFromSource({
     return;
   }
 
-  const tests = relationsMap.get(sourceFilePath)?.tests ?? [];
+  const tests = safeArray(relationsMap.get(sourceFilePath)?.tests);
   for (const testFilePath of tests) {
     if (!suggestions.has(testFilePath)) {
       suggestions.set(testFilePath, {
@@ -1803,6 +1837,25 @@ function addTestsFromSource({
   }
 }
 
+// Item-row fields (`analogs`, `relations.*`) can be hand-edited into non-array
+// shapes (e.g. analogs: "corrupted"). `?? []` does not fire on truthy
+// non-arrays, so coerce when building the lookup maps and again at consumers —
+// inferRelatedTestsFromArtifacts also accepts foreign maps.
+function safeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function normalizeRelations(relations) {
+  if (!relations || typeof relations !== 'object') {
+    return {};
+  }
+  const normalized = { ...relations };
+  for (const key of ['tests', 'siblings', 'styles', ...RELATED_TEST_RELATION_TYPES.map(({ key }) => key)]) {
+    normalized[key] = safeArray(normalized[key]);
+  }
+  return normalized;
+}
+
 // ── Bug Triage ──
 
 export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
@@ -1837,9 +1890,10 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
       limit: 3,
     });
 
-  const analogFiles = top
-    ? (relatedArtifacts?.analogsMap.get(top.filePath) ?? []).slice(0, 2)
-    : [];
+  const topAnalogs = top ? relatedArtifacts?.analogsMap.get(top.filePath) : null;
+  const analogFiles = (Array.isArray(topAnalogs) ? topAnalogs : [])
+    .filter((analog) => analog && typeof analog.filePath === 'string')
+    .slice(0, 2);
 
   return {
     signature,
@@ -1960,7 +2014,7 @@ const ARCHETYPE_RULES = [
 ];
 
 function classifyArchetypes(fileRecords, symbols) {
-  const symbolNamesByPath = groupBy(symbols, (s) => s.filePath);
+  const symbolNamesByPath = groupBy(symbols, (s) => s?.filePath);
 
   return fileRecords
     .filter((f) => CODE_EXTENSIONS.has(f.ext))
@@ -1980,12 +2034,13 @@ function classifyArchetypes(fileRecords, symbols) {
 
       if (!archetype) {
         const fileSymbols = symbolNamesByPath.get(file.filePath) ?? [];
-        const hasDefaultExport = fileSymbols.some((s) => s.name === 'default');
+        const hasDefaultExport = fileSymbols.some((s) => s?.name === 'default');
         const hasComponentSignal = file.ext === '.vue'
           || fileSymbols.some((s) =>
-            s.type === 'component-name'
-            || s.name.toLowerCase().includes('component')
-            || s.name.toLowerCase().includes('page'),
+            s?.type === 'component-name'
+            || (typeof s?.name === 'string'
+              && (s.name.toLowerCase().includes('component')
+                || s.name.toLowerCase().includes('page'))),
           );
 
         if ((hasDefaultExport || file.ext === '.vue') && hasComponentSignal) {
@@ -2875,10 +2930,10 @@ async function loadQuerySearchBundle(rootDir) {
         .then(([files, symbols]) => {
           const safeFiles = ensureArtifact(files);
           const safeSymbols = ensureArtifact(symbols);
-          const symbolMap = groupBy(safeSymbols.items ?? [], (item) => item.filePath);
+          const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
           return {
             files: safeFiles,
-            searchDescriptorsByFile: buildFileSearchDescriptors(safeFiles.items ?? [], symbolMap),
+            searchDescriptorsByFile: buildFileSearchDescriptors(safeItems(safeFiles), symbolMap),
           };
         })
         .catch((error) => {
@@ -2911,23 +2966,23 @@ async function loadQuerySupportBundle(rootDir) {
           const safeTestsMap = ensureArtifact(testsMap);
           const safeHotspots = ensureArtifact(hotspots);
           const safeArchetypes = ensureArtifact(archetypes);
-          const indexedFileSet = new Set((safeFiles.items ?? []).map((item) => item.filePath));
-          const importAliasContext = importsNeedAliasContext(safeImports.items ?? [])
+          const indexedFileSet = new Set(safeItems(safeFiles).map((item) => item.filePath));
+          const importAliasContext = importsNeedAliasContext(safeItems(safeImports))
             ? await loadImportAliasContext({ rootDir: absoluteRoot })
             : null;
           const { resolvedImportsBySource, importersByTarget } = buildResolvedImportGraphs(
             absoluteRoot,
-            safeImports.items ?? [],
+            safeItems(safeImports),
             indexedFileSet,
             importAliasContext,
           );
 
           return {
-            hotspotScores: new Map((safeHotspots.items ?? []).map((item) => [item.filePath, item.count])),
-            testsMapBySource: new Map((safeTestsMap.items ?? []).map((item) => [item.sourceFile, item.tests ?? []])),
+            hotspotScores: new Map(safeItems(safeHotspots).map((item) => [item.filePath, item.count])),
+            testsMapBySource: new Map(safeItems(safeTestsMap).map((item) => [item.sourceFile, item.tests ?? []])),
             resolvedImportsBySource,
             importersByTarget,
-            archetypeByFile: new Map((safeArchetypes.items ?? []).map((item) => [item.filePath, item.archetype])),
+            archetypeByFile: new Map(safeItems(safeArchetypes).map((item) => [item.filePath, item.archetype])),
           };
         })
         .catch((error) => {