@renzrollon/interlock 1.4.1 → 1.5.0

package/lib/graph/extract/walk.mjs

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { rel } from '../paths.mjs';
+import { readIndexed, rel } from '../paths.mjs';
 
 const DEFAULT_SKIP_DIRS = new Set([
   'node_modules',
@@ -39,6 +39,9 @@ const SOURCE_EXTS = new Set([
   '.pyi',
   '.sh',
   '.bash',
+  '.cs',
+  '.csproj',
+  '.bicep',
 ]);
 
 /**
@@ -65,12 +68,24 @@ const CONFIG_JSON_NAMES = new Set([
 
 const CONFIG_JSON_MAX_BYTES = 64 * 1024;
 
-function loadIgnorePatterns(root) {
+function loadIgnorePatterns(root, skips) {
   const patterns = [];
   for (const name of ['.gitignore', '.interlockignore']) {
     const p = path.join(root, name);
     if (!fs.existsSync(p)) continue;
-    for (const line of fs.readFileSync(p, 'utf8').split('\n')) {
+    let text;
+    if (skips) {
+      // An unreadable ignore file contributes no patterns; the walk goes on as if it were absent.
+      const got = readIndexed(p);
+      if (!got.ok) {
+        skips.add(p, got.code, 'its patterns were not applied');
+        continue;
+      }
+      text = got.text;
+    } else {
+      text = fs.readFileSync(p, 'utf8');
+    }
+    for (const line of text.split('\n')) {
       const t = line.trim();
       if (!t || t.startsWith('#')) continue;
       patterns.push(t.replace(/\/$/, ''));
@@ -126,19 +141,26 @@ function shouldSkipDir(root, dir, entName, relPath) {
 
 /**
  * Walk root for source + curated config files. Returns absolute paths.
+ *
+ * `skips` is an optional collector (`createSkips`): with one, a directory that
+ * cannot be listed, a `.json` that cannot be stat'ed and an unreadable ignore
+ * file are recorded instead of passing in silence.
  */
-export function walkSourceFiles(root, { extraSkip = [] } = {}) {
+export function walkSourceFiles(root, { extraSkip = [], skips } = {}) {
   const skipExtra = new Set(extraSkip);
-  const patterns = loadIgnorePatterns(root);
+  const patterns = loadIgnorePatterns(root, skips);
   const out = [];
 
   function visit(dir) {
     let entries;
     try {
       entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
+    } catch (error) {
+      if (skips) skips.add(dir, error);
       return;
     }
+    // A .NET build writes generated sources under bin/ and obj/ next to the project file.
+    const holdsProject = entries.some((e) => e.name.endsWith('.csproj') && !e.isDirectory());
     for (const ent of entries) {
       const full = path.join(dir, ent.name);
       const r = rel(root, full);
@@ -146,6 +168,7 @@ export function walkSourceFiles(root, { extraSkip = [] } = {}) {
         if (skipExtra.has(ent.name) || shouldSkipDir(root, dir, ent.name, r) || ignored(r, patterns)) {
           continue;
         }
+        if (holdsProject && (ent.name === 'bin' || ent.name === 'obj')) continue;
         visit(full);
         continue;
       }
@@ -161,7 +184,8 @@ export function walkSourceFiles(root, { extraSkip = [] } = {}) {
         let size = 0;
         try {
           size = fs.statSync(full).size;
-        } catch {
+        } catch (error) {
+          if (skips) skips.add(full, error);
           continue;
         }
         if (isConfigJson(ent.name, r, size)) out.push(full);
@@ -176,7 +200,7 @@ export function walkSourceFiles(root, { extraSkip = [] } = {}) {
 // Accepts directories or individual markdown files, so callers can mix a docs
 // directory with root-level files such as README.md — on many repos those root
 // files are the only real documentation.
-export function walkMarkdown(root, subdirs) {
+export function walkMarkdown(root, subdirs, { skips } = {}) {
   const out = [];
   for (const sub of subdirs) {
     const base = path.join(root, sub);
@@ -186,24 +210,25 @@ export function walkMarkdown(root, subdirs) {
     } catch {
       continue;
     }
-    if (stat.isDirectory()) walkMd(base, out);
+    if (stat.isDirectory()) walkMd(base, out, skips);
     else if (/\.mdx?$/i.test(base)) out.push(base);
   }
   return [...new Set(out)].sort();
 }
 
-function walkMd(dir, out) {
+function walkMd(dir, out, skips) {
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
+  } catch (error) {
+    if (skips) skips.add(dir, error);
     return;
   }
   for (const ent of entries) {
     const full = path.join(dir, ent.name);
     if (ent.isDirectory()) {
       if (ent.name === 'node_modules' || ent.name === '.git' || ent.name === '__pycache__') continue;
-      walkMd(full, out);
+      walkMd(full, out, skips);
       continue;
     }
     if (ent.isFile() && ent.name.endsWith('.md')) out.push(full);

package/lib/graph/graph/build.mjs

@@ -5,15 +5,17 @@ import { extractOpenspec } from '../extract/openspec.mjs';
 import { extractMemory } from '../extract/memory.mjs';
 import { walkSourceFiles } from '../extract/walk.mjs';
 import {
+  createSkips,
   ensureGraphDir,
   graphPath,
   loadJson,
   manifestPath,
+  readIndexed,
   rel,
   reportPath,
-  sha256File,
   writeJson,
 } from '../paths.mjs';
+import { linkCsharp } from './link-csharp.mjs';
 import { writeReport } from './report.mjs';
 
 function langOf(filePath) {
@@ -21,6 +23,9 @@ function langOf(filePath) {
   if (ext === '.py' || ext === '.pyi') return 'python';
   if (ext === '.sh' || ext === '.bash') return 'shell';
   if (ext === '.json') return 'json';
+  if (ext === '.cs') return 'csharp';
+  if (ext === '.csproj') return 'csproj';
+  if (ext === '.bicep') return 'bicep';
   return 'js';
 }
 
@@ -106,6 +111,34 @@ function resolveJsImport(fromFile, specifier, fileIndex) {
   return { kind: 'unresolved', id: `unresolved:${candidate}`, path: candidate };
 }
 
+/**
+ * A project path is an identity compared in a Set, so it is normalized here and
+ * nowhere else: backslashes become forward slashes and the result is resolved
+ * against the referencing project's directory. A value holding an MSBuild
+ * property, and one that names no walked file, is unresolved — no edge to a
+ * file is invented for it.
+ */
+function resolveCsprojImport(fromFile, specifier, fileIndex) {
+  const spelled = String(specifier).replace(/\\/g, '/');
+  if (spelled.includes('$(') || path.posix.isAbsolute(spelled) || /^[A-Za-z]:\//.test(spelled)) {
+    return { kind: 'unresolved', id: `unresolved:${spelled}`, path: spelled };
+  }
+  const candidate = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spelled));
+  if (fileIndex.has(candidate)) return { kind: 'file', id: `file:${candidate}`, path: candidate };
+  return { kind: 'unresolved', id: `unresolved:${candidate}`, path: candidate };
+}
+
+// A registry (`br:`, `br/<alias>:`) or template-spec (`ts:`, `ts/<alias>:`) module reference.
+const BICEP_EXTERNAL_RE = /^(?:br|ts)(?::|\/[^/:]+:)/;
+
+function resolveBicepImport(fromFile, specifier, fileIndex) {
+  const spec = String(specifier);
+  if (BICEP_EXTERNAL_RE.test(spec)) return { kind: 'external', id: `external:${spec}` };
+  const candidate = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
+  if (fileIndex.has(candidate)) return { kind: 'file', id: `file:${candidate}`, path: candidate };
+  return { kind: 'unresolved', id: `unresolved:${candidate}`, path: candidate };
+}
+
 /**
  * Resolve an import/require/source specifier against an importing file.
  */
@@ -113,6 +146,11 @@ export function resolveImport(fromFile, specifier, fileIndex) {
   const lang = langOf(fromFile);
   if (lang === 'python') return resolvePythonImport(fromFile, specifier, fileIndex);
   if (lang === 'shell') return resolveShellImport(fromFile, specifier, fileIndex);
+  if (lang === 'csproj') return resolveCsprojImport(fromFile, specifier, fileIndex);
+  if (lang === 'bicep') return resolveBicepImport(fromFile, specifier, fileIndex);
+  // A C# `using` names a namespace, not a path; linkCsharp places it. Nothing
+  // is resolved against the file set here.
+  if (lang === 'csharp') return { kind: 'external', id: `external:${specifier}` };
   if (lang === 'json') {
     // package.json main/bin paths are usually relative to package root
     if (fileIndex.has(specifier)) return { kind: 'file', id: `file:${specifier}`, path: specifier };
@@ -141,17 +179,21 @@ function moduleIdFor(filePath) {
 }
 
 /**
- * Build a full graph for root. Returns { graph, stats, extractorMode }.
+ * Build a full graph for root. Returns { graph, stats, hashes, skipped, extractorMode }.
+ *
+ * `skips` is the command's collector (`createSkips`). A path under the root that
+ * cannot be read is added to it and contributes nothing: no hash, no node, no
+ * edge, and no place in the file set imports resolve against. `skipped` is the
+ * collector's list when the build ends.
  */
-export function buildGraph(root, { fileFilter = null } = {}) {
+export function buildGraph(root, { fileFilter = null, skips = createSkips(root) } = {}) {
   const extractor = createExtractor(root);
-  let files = walkSourceFiles(root);
+  let files = walkSourceFiles(root, { skips });
   if (fileFilter) {
     const allow = new Set(fileFilter);
     files = files.filter((f) => allow.has(rel(root, f)));
   }
 
-  const fileIndex = new Set(files.map((f) => rel(root, f)));
   const nodes = new Map();
   const edges = [];
   const symbolByName = new Map(); // name -> [symbol ids]
@@ -161,11 +203,24 @@ export function buildGraph(root, { fileFilter = null } = {}) {
     if (!nodes.has(node.id)) nodes.set(node.id, node);
   }
 
+  // Read every file once, before anything is resolved: the file set an import
+  // resolves against must hold only what was actually read.
+  const read = [];
   for (const absPath of files) {
     const filePath = rel(root, absPath);
-    hashes[filePath] = sha256File(absPath);
-    const source = fs.readFileSync(absPath, 'utf8');
-    const extracted = extractor.extract(filePath, source);
+    const got = readIndexed(absPath);
+    if (!got.ok) {
+      skips.add(absPath, got.code);
+      continue;
+    }
+    hashes[filePath] = got.sha256;
+    read.push({ filePath, extracted: extractor.extract(filePath, got.text) });
+  }
+  const fileIndex = new Set(read.map((r) => r.filePath));
+  const csharpRecords = [];
+
+  for (const { filePath, extracted } of read) {
+    if (extracted.csharp) csharpRecords.push({ filePath, csharp: extracted.csharp });
 
     addNode({
       id: `file:${filePath}`,
@@ -276,8 +331,14 @@ export function buildGraph(root, { fileFilter = null } = {}) {
     }
   }
 
+  // C# is linked across files: a `using` names a namespace, and a namespace is
+  // declared in many files. External targets it names get their nodes below.
+  const csharp = linkCsharp(csharpRecords);
+  for (const n of csharp.nodes) addNode(n);
+  for (const e of csharp.edges) edges.push(e);
+
   const knownSymbols = new Set(symbolByName.keys());
-  const openspec = extractOpenspec(root, knownSymbols, fileIndex);
+  const openspec = extractOpenspec(root, knownSymbols, fileIndex, { skips });
   for (const n of openspec.nodes) addNode(n);
   for (const e of openspec.edges) {
     if (e.target.startsWith('symbol-name:')) {
@@ -292,7 +353,7 @@ export function buildGraph(root, { fileFilter = null } = {}) {
     }
   }
 
-  const memory = extractMemory(root, fileIndex);
+  const memory = extractMemory(root, fileIndex, { skips });
   for (const n of memory.nodes) addNode(n);
   for (const e of memory.edges) {
     if (nodes.has(e.source) && nodes.has(e.target)) edges.push(e);
@@ -349,18 +410,21 @@ export function buildGraph(root, { fileFilter = null } = {}) {
     extractor: extractor.mode,
   };
 
-  return { graph, stats, hashes, extractorMode: extractor.mode };
+  return { graph, stats, hashes, skipped: skips.list(), extractorMode: extractor.mode };
 }
 
-export function writeGraphArtifacts(root, { graph, stats, hashes }) {
+export function writeGraphArtifacts(root, { graph, stats, hashes, skipped = [] }) {
   ensureGraphDir(root);
   writeJson(graphPath(root), graph);
+  // The manifest keeps the path and the code; a skip's note is said on stderr.
+  const recorded = skipped.map(({ path: skippedPath, code }) => ({ path: skippedPath, code }));
   writeJson(manifestPath(root), {
     built_at: graph.graph.built_at,
     files: hashes,
+    skipped: recorded,
     stats,
   });
-  const report = writeReport(root, graph, stats);
+  const report = writeReport(root, graph, stats, recorded);
   fs.writeFileSync(reportPath(root), report);
   return { graphPath: graphPath(root), reportPath: reportPath(root), stats };
 }

package/lib/graph/graph/link-csharp.mjs

@@ -0,0 +1,210 @@
+// C# is linked in a pass after the per-file loop: a `using` names a namespace, and a
+// namespace is declared across many files, so it cannot be resolved against a set of
+// paths. This module is pure (no `node:` import) -- it takes every `extractCsharp`
+// record and returns `{ nodes, edges }`, the shape the OpenSpec and memory overlays
+// already return.
+
+const INFERRED_REFERENCE_WEIGHT = 0.5;
+
+function nameOf(entry) {
+  return typeof entry === 'string' ? entry : entry?.name;
+}
+
+function lineOf(entry, fallback = 1) {
+  const line = entry && typeof entry === 'object' ? entry.line : undefined;
+  return Number.isInteger(line) && line > 0 ? line : fallback;
+}
+
+function ascending(lines) {
+  if (!Array.isArray(lines)) return [];
+  return lines.filter((n) => Number.isInteger(n)).sort((a, b) => a - b);
+}
+
+/** `A.B.C` -> ['A.B.C', 'A.B', 'A'] */
+function dotPrefixes(name) {
+  const parts = name.split('.');
+  const out = [];
+  for (let i = parts.length; i > 0; i -= 1) out.push(parts.slice(0, i).join('.'));
+  return out;
+}
+
+function compare(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Link C# records into namespace nodes, test nodes and their edges.
+ *
+ * @param {Array<{filePath: string, csharp?: object}>} records `extractCsharp` results
+ * @returns {{ nodes: object[], edges: object[] }}
+ */
+export function linkCsharp(records) {
+  const files = (Array.isArray(records) ? records : [])
+    .filter((r) => r && typeof r.filePath === 'string' && r.csharp)
+    .sort((a, b) => compare(a.filePath, b.filePath));
+
+  const nodes = [];
+  const edges = [];
+  const nodeIds = new Set();
+  const edgeKeys = new Set();
+
+  function addNode(node) {
+    if (nodeIds.has(node.id)) return;
+    nodeIds.add(node.id);
+    nodes.push(node);
+  }
+
+  function addEdge(edge) {
+    const key = `${edge.source}\u0000${edge.target}\u0000${edge.relation}\u0000${edge.source_location}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push(edge);
+  }
+
+  // Pass 1: every namespace the repository declares, and the types each one holds.
+  const declared = new Set();
+  const typesByNamespace = new Map(); // namespace -> Map(typeName -> [declFile])
+  for (const rec of files) {
+    for (const ns of rec.csharp.namespaces || []) {
+      const name = nameOf(ns);
+      if (!name) continue;
+      declared.add(name);
+      const id = `namespace:${name}`;
+      if (!nodeIds.has(id)) {
+        // First declaring file in path order, its first declaration.
+        const first = (rec.csharp.namespaces || [])
+          .filter((n) => nameOf(n) === name)
+          .reduce((best, n) => Math.min(best, lineOf(n)), Infinity);
+        addNode({
+          id,
+          type: 'namespace',
+          label: name,
+          source_file: rec.filePath,
+          source_location: `L${first}`,
+        });
+      }
+    }
+    for (const type of rec.csharp.types || []) {
+      const name = nameOf(type);
+      if (!name) continue;
+      const ns = type && typeof type === 'object' && typeof type.namespace === 'string' ? type.namespace : '';
+      if (!typesByNamespace.has(ns)) typesByNamespace.set(ns, new Map());
+      const byName = typesByNamespace.get(ns);
+      if (!byName.has(name)) byName.set(name, []);
+      if (!byName.get(name).includes(rec.filePath)) byName.get(name).push(rec.filePath);
+    }
+  }
+
+  const declaredByLength = [...declared].sort((a, b) => b.length - a.length || compare(a, b));
+  function resolveNamespace(name) {
+    return declaredByLength.find((d) => name === d || name.startsWith(`${d}.`)) || null;
+  }
+
+  // Pass 2: edges, per file in path order.
+  for (const rec of files) {
+    const fileId = `file:${rec.filePath}`;
+    const cs = rec.csharp;
+    const visible = new Set();
+
+    for (const ns of cs.namespaces || []) {
+      const name = nameOf(ns);
+      if (!name) continue;
+      addEdge({
+        source: fileId,
+        target: `namespace:${name}`,
+        relation: 'declares',
+        confidence: 'EXTRACTED',
+        source_file: rec.filePath,
+        source_location: `L${lineOf(ns)}`,
+        weight: 1,
+      });
+      for (const p of dotPrefixes(name)) visible.add(p);
+    }
+
+    for (const using of cs.usings || []) {
+      const name = nameOf(using);
+      if (!name) continue;
+      const hit = resolveNamespace(name);
+      if (hit) visible.add(hit);
+      addEdge({
+        source: fileId,
+        target: hit ? `namespace:${hit}` : `external:${name}`,
+        relation: 'imports',
+        confidence: 'EXTRACTED',
+        source_file: rec.filePath,
+        source_location: `L${lineOf(using)}`,
+        weight: 1,
+      });
+    }
+
+    const tests = [];
+    for (const t of cs.tests || []) {
+      if (!t || !t.name) continue;
+      const label = `${t.type}.${t.name}`;
+      const id = `test:${rec.filePath}#${label}`;
+      addNode({
+        id,
+        type: 'test',
+        label,
+        source_file: rec.filePath,
+        source_location: `L${lineOf(t)}`,
+      });
+      addEdge({
+        source: fileId,
+        target: id,
+        relation: 'exports',
+        confidence: 'EXTRACTED',
+        source_file: rec.filePath,
+        source_location: `L${lineOf(t)}`,
+        weight: 1,
+      });
+      tests.push({
+        id,
+        start: Number.isInteger(t.start) ? t.start : lineOf(t),
+        end: Number.isInteger(t.end) ? t.end : Infinity,
+      });
+    }
+
+    const ownTypes = new Set((cs.types || []).map(nameOf).filter(Boolean));
+    const identifiers = cs.identifiers || {};
+    for (const ident of Object.keys(identifiers).sort()) {
+      if (ownTypes.has(ident)) continue;
+      const lines = ascending(identifiers[ident]);
+      if (lines.length === 0) continue;
+      const targets = new Set();
+      for (const ns of visible) {
+        for (const declFile of typesByNamespace.get(ns)?.get(ident) || []) {
+          targets.add(`symbol:${declFile}#${ident}`);
+        }
+      }
+      for (const target of [...targets].sort()) {
+        addEdge({
+          source: fileId,
+          target,
+          relation: 'references',
+          confidence: 'INFERRED',
+          source_file: rec.filePath,
+          source_location: `L${lines[0]}`,
+          weight: INFERRED_REFERENCE_WEIGHT,
+          name: ident,
+        });
+        for (const test of tests) {
+          const at = lines.find((n) => n >= test.start && n <= test.end);
+          if (at === undefined) continue;
+          addEdge({
+            source: test.id,
+            target,
+            relation: 'references',
+            confidence: 'INFERRED',
+            source_file: rec.filePath,
+            source_location: `L${at}`,
+            weight: INFERRED_REFERENCE_WEIGHT,
+            name: ident,
+          });
+        }
+      }
+    }
+  }
+
+  return { nodes, edges };
+}

package/lib/graph/graph/query.mjs

@@ -134,6 +134,8 @@ export function consumers(graph, target) {
         );
         if (src?.type === 'file') {
           lines.push(`    consumer_file: ${src.source_file}`);
+        } else if (src?.type === 'test') {
+          lines.push(`    consumer_test: ${src.source_file}:${src.source_location} ${src.label}`);
         }
       }
     }

package/lib/graph/graph/report.mjs

@@ -1,7 +1,11 @@
 /**
  * Generate GRAPH_REPORT.md content from a graph.
+ *
+ * `skipped` is the build's list of paths it could not read (`[{ path, code }]`).
+ * They are in no node, so the report names them in a section of their own; with
+ * none, the report is what it was before the section existed.
  */
-export function writeReport(_root, graph, stats) {
+export function writeReport(_root, graph, stats, skipped = []) {
   const degree = new Map();
   for (const n of graph.nodes) degree.set(n.id, { in: 0, out: 0, node: n });
   for (const e of graph.links) {
@@ -60,6 +64,12 @@ export function writeReport(_root, graph, stats) {
   lines.push(`- Symbols: ${stats.symbols}`);
   lines.push(`- Modules: ${stats.modules}`);
   lines.push('');
+  if (Array.isArray(skipped) && skipped.length > 0) {
+    lines.push('## Not indexed (unreadable)');
+    lines.push('');
+    for (const entry of skipped) lines.push(`- ${entry.path} (${entry.code})`);
+    lines.push('');
+  }
   lines.push('## God nodes (highest degree)');
   lines.push('');
   if (hubs.length === 0) {

package/lib/graph/graph/update.mjs

@@ -1,6 +1,7 @@
-import fs from 'node:fs';
+import { extractMemory } from '../extract/memory.mjs';
+import { extractOpenspec } from '../extract/openspec.mjs';
 import { walkSourceFiles } from '../extract/walk.mjs';
-import { loadJson, manifestPath, rel, sha256File } from '../paths.mjs';
+import { createSkips, loadJson, manifestPath, readIndexed, rel } from '../paths.mjs';
 import { buildGraph, writeGraphArtifacts } from './build.mjs';
 
 /**
@@ -8,40 +9,79 @@ import { buildGraph, writeGraphArtifacts } from './build.mjs';
  * (v1 keeps it simple — detect staleness, then full rebuild of affected set + dependents
  * is complex; we do full rebuild when any hash differs, which is still fast for mid-size repos).
  *
- * Returns { updated: boolean, stats, reason }.
+ * Readability is compared as well as content. A path that was skipped by the
+ * recorded build and is still unreadable is not a change: it can never be
+ * hashed, so without the manifest's record it would look changed on every run.
+ * A path that was indexed and can no longer be read, and one that was skipped
+ * and can now be read, each rebuild.
+ *
+ * `skips` is the command's collector (`createSkips`). It holds the currently
+ * unreadable paths when this returns, whether or not the graph was rebuilt.
+ *
+ * Returns { updated: boolean, stats, reason, skipped }.
  */
-export function updateGraph(root) {
+export function updateGraph(root, { skips = createSkips(root) } = {}) {
   const manifest = loadJson(manifestPath(root), null);
   if (!manifest?.files) {
-    const result = buildGraph(root);
+    const result = buildGraph(root, { skips });
     writeGraphArtifacts(root, result);
-    return { updated: true, stats: result.stats, reason: 'no-manifest' };
+    return { updated: true, stats: result.stats, reason: 'no-manifest', skipped: result.skipped };
   }
 
-  const currentFiles = walkSourceFiles(root).map((f) => rel(root, f));
   const prevFiles = new Set(Object.keys(manifest.files));
   const changed = [];
 
-  for (const f of currentFiles) {
-    const abs = `${root}/${f}`;
-    if (!fs.existsSync(abs)) continue;
-    const hash = sha256File(abs);
-    if (manifest.files[f] !== hash) changed.push(f);
+  for (const abs of walkSourceFiles(root, { skips })) {
+    const f = rel(root, abs);
+    const got = readIndexed(abs);
+    if (!got.ok) {
+      // Unreadable now, not removed. Whether that is news is decided below,
+      // against the recorded skips.
+      skips.add(abs, got.code);
+      prevFiles.delete(f);
+      continue;
+    }
+    if (manifest.files[f] !== got.sha256) changed.push(f);
     prevFiles.delete(f);
   }
   const removed = [...prevFiles];
 
-  if (changed.length === 0 && removed.length === 0) {
-    return { updated: false, stats: manifest.stats, reason: 'up-to-date' };
+  // The overlays read prose the hashes above do not cover, and a build records
+  // what they could not read. Run the same readers so the two sets are compared
+  // like for like; what they extract is not used here.
+  extractOpenspec(root, new Set(), new Set(), { skips });
+  extractMemory(root, new Set(), { skips });
+
+  // A manifest written before skips were recorded reads as one with none.
+  const recorded = new Set(
+    (Array.isArray(manifest.skipped) ? manifest.skipped : []).map((entry) => entry?.path).filter(Boolean),
+  );
+  const current = skips.list();
+  const unreadableNow = current.filter((entry) => !recorded.has(entry.path)).map((entry) => entry.path);
+  const currentPaths = new Set(current.map((entry) => entry.path));
+  const readableNow = [...recorded].filter((p) => !currentPaths.has(p));
+
+  if (
+    changed.length === 0 &&
+    removed.length === 0 &&
+    unreadableNow.length === 0 &&
+    readableNow.length === 0
+  ) {
+    return { updated: false, stats: manifest.stats, reason: 'up-to-date', skipped: current };
   }
 
-  const result = buildGraph(root);
+  const result = buildGraph(root, { skips });
   writeGraphArtifacts(root, result);
+  const readability =
+    unreadableNow.length || readableNow.length
+      ? ` unreadable=${unreadableNow.length} readable=${readableNow.length}`
+      : '';
   return {
     updated: true,
     stats: result.stats,
-    reason: `changed=${changed.length} removed=${removed.length}`,
+    reason: `changed=${changed.length} removed=${removed.length}${readability}`,
     changed,
     removed,
+    skipped: result.skipped,
   };
 }