Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

fix(finalizer): roll back the graph and fingerprints when the baseline patch fails (#753)

06FallingLight90bd9d0f3b4542
diff --git a/understand-anything-plugin/skills/understand/finalize-incremental.mjs b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
index f32d453f..5847c128 100644
--- a/understand-anything-plugin/skills/understand/finalize-incremental.mjs
+++ b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
@@ -401,12 +401,19 @@ async function main() {
}
const graphPath = join(uaDir, 'knowledge-graph.json');
+ const fingerprintPath = join(uaDir, 'fingerprints.json');
const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)
? plan.importMapRefreshPaths
: [];
+ // Rollback material: capture the previous graph before any write below. A
+ // graph save that succeeds while the fingerprint/meta patch below fails must
+ // not leave the NEW graph published with a non-zero exit — the previous
+ // code-lessons sidecar would sit beside a tour it no longer matches.
+ let previousGraph = readJson(graphPath, null);
+ let graphWritten = false;
+
if (plan.action === 'SKIP') {
- const previousGraph = readJson(graphPath);
if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {
throw new Error('knowledge-graph.json is missing or invalid; baseline not advanced');
}
@@ -419,10 +426,11 @@ async function main() {
...refreshedGraph,
project: projectMetadata(previousGraph.project, plan, scan),
});
+ graphWritten = true;
}
if (plan.action !== 'SKIP') {
- const previousGraph = readJson(graphPath, {});
+ const baseGraph = previousGraph ?? {};
const assembledRaw = readJson(join(intermediateDir, 'assembled-graph.json'));
if (!assembledRaw || !Array.isArray(assembledRaw.nodes) || !Array.isArray(assembledRaw.edges)) {
throw new Error('assembled-graph.json is missing or invalid; baseline not advanced');
@@ -451,16 +459,16 @@ async function main() {
}
const rawLayers = plan.rerunArchitecture
? readJson(join(intermediateDir, 'layers.json'))
- : previousGraph.layers ?? [];
+ : baseGraph.layers ?? [];
const rawTour = plan.rerunTour
? readJson(join(intermediateDir, 'tour.json'))
- : previousGraph.tour ?? [];
+ : baseGraph.tour ?? [];
const now = new Date().toISOString();
const graph = {
- ...previousGraph,
- version: previousGraph.version ?? '1.0.0',
+ ...baseGraph,
+ version: baseGraph.version ?? '1.0.0',
project: {
- ...projectMetadata(previousGraph.project, plan, scan),
+ ...projectMetadata(baseGraph.project, plan, scan),
analyzedAt: now,
},
nodes: assembled.nodes,
@@ -476,10 +484,29 @@ async function main() {
process.stderr.write(`${formatSymbolReport(symbolReport)}\n`);
if (!symbolReport.ok) throw new Error('Unresolved incremental symbol loss; baseline not advanced');
atomicWriteJson(graphPath, graph);
+ graphWritten = true;
}
- patchFingerprints(uaDir, plan, patch);
- advanceMeta(uaDir, plan, scan.totalFiles);
+ // Snapshot the fingerprint store before patching so a failure below can
+ // restore both the old graph and the old fingerprint baseline. Restoring
+ // fingerprints matters as much as restoring the graph: a stale graph with
+ // fresh fingerprints would make the next run misclassify every change.
+ const fingerprintBackup = readJson(fingerprintPath, null);
+ try {
+ patchFingerprints(uaDir, plan, patch);
+ advanceMeta(uaDir, plan, scan.totalFiles);
+ } catch (error) {
+ if (graphWritten) {
+ if (previousGraph && Array.isArray(previousGraph.nodes)) {
+ atomicWriteJson(graphPath, previousGraph);
+ }
+ if (fingerprintBackup && typeof fingerprintBackup === 'object' && !Array.isArray(fingerprintBackup)) {
+ atomicWriteJson(fingerprintPath, fingerprintBackup);
+ }
+ process.stderr.write('Rolled back knowledge-graph.json and fingerprints.json to their previous state\n');
+ }
+ throw error;
+ }
process.stdout.write(
`Incremental update finalized: ${plan.action}; analyzedFiles=${scan.totalFiles}\n`,
);