> {
diff --git a/src/export.ts b/src/export.ts
index c8d9bc9..f3083f8 100644
--- a/src/export.ts
+++ b/src/export.ts
@@ -1,3 +1,5 @@
+import { tourAnchors, tourCode, tourCoverage } from "./tour-evidence.ts";
+import type { TourStep } from "./types.ts";
import { briefingFingerprint, briefingIntent } from "./briefing.ts";
import { briefingMarkdown, withBriefingExport } from "./briefing-export.ts";
import type { ReviewSession } from "./session.ts";
@@ -515,10 +517,25 @@ function markdown(session: ReviewSession, options: HtmlExportOptions = {}): stri
for (const step of phase.steps) {
stopNumber += 1;
lines.push(`#### Stop ${stopNumber}: ${markdownText(step.title)}`, "", `${markdownText(step.anchor.path)}:${step.anchor.startLine}-${step.anchor.endLine} (${step.anchor.side})`, "", markdownText(step.objective), "");
+ lines.push(`Importance: ${step.importance ?? "normal"}. Freshness: ${step.freshness ?? "unverified"}.`, "");
+ for (const anchor of step.relatedAnchors ?? []) lines.push(`Related: ${markdownText(anchor.path)}:${anchor.startLine}-${anchor.endLine} (${anchor.side})`, "");
if (step.explanation) lines.push(markdownText(step.explanation), "");
+ if (step.explanationDetail) lines.push("More detail:", "", markdownText(step.explanationDetail), "");
+ for (const note of step.notes ?? []) {
+ lines.push(`**${note.kind}${note.outdated ? " · Out of date" : ""}:** ${markdownText(note.text)}`, "");
+ if (note.scope) lines.push(`Inspected scope: ${markdownText(note.scope)}`, "");
+ for (const source of note.sources) lines.push(`${markdownText(source.anchor.path)}:${source.anchor.startLine}-${source.anchor.endLine} (${source.anchor.side})`, "", ...source.quote.split("\n").map(line => `> ${markdownText(line)}`), "");
+ }
}
});
}
+ if (outline) {
+ const coverage = (session.snapshot?.().tourCoverage ?? tourCoverage(session.outline, session.comparison));
+ lines.push("## Not covered by the tour", "", `${coverage.covered} of ${coverage.total} changed blocks fully covered; ${coverage.partial} partly covered. Coverage describes the tour, not reviewer completion.`, "");
+ for (const block of coverage.uncovered) lines.push(`- ${markdownText(block.path)}${block.anchor ? `:${block.anchor.startLine}-${block.anchor.endLine} (${block.anchor.side})` : ""} — ${markdownText(block.reason)}`);
+ if (coverage.omitted) lines.push(`- ${coverage.omitted} more changed blocks outside this list.`);
+ lines.push("");
+ }
if (outline?.behaviorArchitecture || outline?.architecture) {
lines.push("## Architecture", "");
if (outline.behaviorArchitecture) lines.push(...markdownArchitecture(`${outline.behaviorArchitectureStatus === "proposed" ? "Proposed" : "Implemented"} behaviour`, outline.behaviorArchitecture));
@@ -851,11 +868,12 @@ export function htmlHighlightGroups(session: ReviewSession): HighlightGroup[] {
}),
})).filter((group) => group.lines.some(Boolean));
}));
- const tourPaths = session.outline?.phases.flatMap((phase) => phase.steps.map((step) => step.anchor.path)) ?? [];
+ const tourSteps = session.outline?.phases.flatMap(phase => phase.steps) ?? [];
+ const tourPaths = tourSteps.flatMap(step => tourAnchors(step).map(anchor => anchor.path));
for (const artifact of session.outline?.archifyArtifacts ?? []) {
if (artifact.type === "sequence") groups.push(...sequencePreviewGroups(sequenceArtifactSources(artifact, session.outline?.flows ?? [], session.comparison), artifact.id));
}
- const currentPath = tourPaths[session.currentStepIndex];
+ const currentPath = tourSteps[session.currentStepIndex]?.anchor.path;
const priorities = new Map([...new Set([currentPath, ...tourPaths].filter((path): path is string => Boolean(path)))].map((path, index) => [path, index]));
const ordered = groups.map((group, index) => ({ group, index })).sort((left, right) =>
(priorities.get(left.group.path) ?? Number.MAX_SAFE_INTEGER) - (priorities.get(right.group.path) ?? Number.MAX_SAFE_INTEGER) || left.index - right.index,
@@ -1034,12 +1052,18 @@ function html(session: ReviewSession, options: HtmlExportOptions): string {
const archify = includeDiagrams ? `${(outline?.archifyArtifacts ?? []).filter((artifact) => !artifact.id.startsWith("structural-") && artifact.type !== "workflow").map(archifyArtifact).join("")}${(outline?.archifyArtifacts ?? []).some((artifact) => artifact.comparison?.before || artifact.comparison?.delta) ? archifyExportComparisonScript : ""}` : "";
const archifyFailures = includeDiagrams ? (outline?.archifyFailures ?? []).map((failure) => `Archify ${escapeHtml(failure.type)} unavailable ${escapeHtml(failure.message)}
${failure.preservedLastValid ? "The last validated artifact remains embedded above." : "The validated Mermaid fallback remains available."} Not covered · ${coverage.total - coverage.covered} blocks ${coverage.covered} of ${coverage.total} changed blocks fully covered; ${coverage.partial} partly covered. Coverage describes the tour, not reviewer completion.
${coverage.uncovered.map(block => `${escapeHtml(block.path)}${block.anchor ? `:${block.anchor.startLine}–${block.anchor.endLine}` : ""} ${escapeHtml(block.reason)}
`).join("")}${coverage.omitted ? `${coverage.omitted} more changed blocks outside this list.
` : ""}${escapeHtml(step.importance ?? "normal")} · ${escapeHtml(step.freshness ?? "unverified")}
${step.explanationDetail ? `More detail ${renderedMarkdown(step.explanationDetail)}
${escapeHtml(note.kind)}${note.outdated ? " · Out of date" : ""} ${renderedMarkdown(note.text)}
${note.scope ? `Inspected scope: ${escapeHtml(note.scope)}
` : ""}Source evidence ${note.sources.map(source => `${escapeHtml(source.anchor.path)}:${source.anchor.startLine}–${source.anchor.endLine} (${source.anchor.side})
${escapeHtml(source.quote)} `).join("")}Read this step’s code ${code.freshness !== "current" ? `${code.freshness === "outdated" ? "Code changed or could not be matched uniquely. This explanation is out of date." : "This saved tour has no content fingerprints. Freshness is unverified."}
` : ""}${code.groups.map(group => `${escapeHtml(group.path)} · Open full file
${group.rows.map(row => `${row.oldLine ?? ""} ${row.newLine ?? ""} ${row.kind === "addition" ? "+" : row.kind === "deletion" ? "−" : " "} ${escapeHtml(row.content)}`).join("\n")} ${group.limited ? "Excerpt limited. Open the full file for all context.
" : ""}${escapeHtml(anchor.path)}:${anchor.startLine}–${anchor.endLine} (${anchor.side})
`).join("")}Phase ${phaseIndex + 1}
${escapeHtml(phase.title)} ${escapeHtml(phase.summary)}
Files in this phase ${phase.fileChanges.length} ${phase.fileChanges.map((change) => { const file = filesByPath.get(change.path); return `${escapeHtml(change.path)} ${escapeHtml(change.summary)} +${file.additions} −${file.deletions}
Phase findings ${phaseFindings.length} ${escapeHtml(step.anchor.path)}:${step.anchor.startLine}-${step.anchor.endLine}${escapeHtml(step.title)} ${escapeHtml(step.objective)}
${renderedMarkdown(step.explanation ?? "Explanation unavailable.")}
Agent analysis
Current stop findings ${scoped.length} Phase ${phaseIndex + 1}
${escapeHtml(phase.title)} ${escapeHtml(phase.summary)}
Files in this phase ${phase.fileChanges.length} ${phase.fileChanges.map((change) => { const file = filesByPath.get(change.path); return `${escapeHtml(change.path)} ${escapeHtml(change.summary)} +${file.additions} −${file.deletions}
Phase findings ${phaseFindings.length} ${escapeHtml(step.anchor.path)}:${step.anchor.startLine}-${step.anchor.endLine}${escapeHtml(step.title)} ${escapeHtml(step.objective)}
${renderedMarkdown(step.explanation ?? "Explanation unavailable.")}
${reading(step)}Agent analysis
Current stop findings ${scoped.length} ${escapeHtml(flow.summary)}
${escapeHtml(flow.mermaid)}
Mermaid source ${escapeHtml(flow.mermaid)} ${escapeHtml(session.comparison.repositoryName)} · ${escapeHtml(session.comparison.base)} → ${escapeHtml(session.comparison.branch ?? session.comparison.head.slice(0, 8))} ${escapeHtml(outline?.title ?? `Code review: ${session.comparison.repositoryName}`)} ${tabs} Changed files ${session.comparison.files.length} ${fileButtons}
${changeSummaries ? `` : ""}${callFlows ? `Analysis Call flows ${callFlows}
Analysis Sequence diagrams ${flows}
All findings ${allFindings || 'No evidence-backed findings were generated.
'} ${escapeHtml(session.comparison.repositoryName)} · ${escapeHtml(session.comparison.base)} → ${escapeHtml(session.comparison.branch ?? session.comparison.head.slice(0, 8))} ${escapeHtml(outline?.title ?? `Code review: ${session.comparison.repositoryName}`)} ${tabs} Changed files ${session.comparison.files.length} ${fileButtons}
${changeSummaries ? `` : ""}${callFlows ? `Analysis Call flows ${callFlows}
Analysis Sequence diagrams ${flows}
All findings ${allFindings || 'No evidence-backed findings were generated.
'} = {
+ "tour-reading.mjs": { body: String(tourReadingScript), contentType: "text/javascript; charset=utf-8" },
...BRAND_FILES,
"index.html": { body: String(indexHtml), contentType: "text/html; charset=utf-8" },
"app.js": { body: String(diagramLabelsScript) + "\n" + String(semanticPresentationScript) + "\n" + String(semanticDiffScript) + "\n" + `${callTreeScript}\n${briefingScript}` + "\n" + String(appScript) + "\n" + String(mapPresentationScript), contentType: "text/javascript; charset=utf-8" },
@@ -246,6 +249,7 @@ export function createRequestHandler(session: ReviewSession, sessionDirectory =
});
}
if (request.method === "GET" && url.pathname === "/api/session") return json(session.snapshot());
+ if (request.method === "GET" && url.pathname === "/api/tour/code") return json(session.tourCode(url.searchParams.get("stepId") ?? ""));
if (request.method === "GET" && url.pathname === "/api/diff/sources") {
const comparison = session.comparison;
const path = url.searchParams.get("path");
diff --git a/src/session.ts b/src/session.ts
index 02b9d2a..bbfa022 100644
--- a/src/session.ts
+++ b/src/session.ts
@@ -1,3 +1,5 @@
+import { captureTourEvidence, reconcileTourEvidence, tourCode, tourCoverage } from "./tour-evidence.ts";
+import { explanationFields, reconcileTourNotes } from "./tour-reading.ts";
import { captureBriefingDiagrams } from "./briefing-diagrams.ts";
import { buildBriefing, briefingFingerprint, briefingIntent, resolveBriefingQuestion, type BriefingQuestionRequest } from "./briefing.ts";
import { captureBriefingDiffs } from "./briefing-diff.ts";
@@ -179,6 +181,7 @@ export class ReviewSession {
private readonly sessionName?: string;
private readonly archived: boolean;
private fullComparison: GitComparison;
+ private coverageCache?: { comparison: GitComparison; signature: string; value: ReturnType };
private currentRevisionSummary: RevisionSummary;
private currentSinceFiles: DiffFile[] = [];
private resolveClosed!: (outcome: ReviewOutcome) => void;
@@ -238,6 +241,7 @@ export class ReviewSession {
this.comparisonView = persisted?.comparisonView ?? "full";
this.selectedCheckpointId = persisted?.selectedCheckpointId;
this.fullComparison = comparison;
+ reconcileTourEvidence(this.outline, comparison);
this.currentRevisionSummary = { changedFiles: 0, additions: 0, deletions: 0, newFiles: [], changedAgainFiles: [], resolvedFiles: [], unchangedFiles: [], text: "No review checkpoint yet. Create one before refreshing to preserve reviewed files." };
this.selection = persisted?.selection
? {
@@ -683,9 +687,8 @@ export class ReviewSession {
comment.status = range.lineContent === comment.lineContent && (!comment.context || range.context === comment.context) ? "active" : "outdated";
} catch { comment.status = "outdated"; }
}
- for (const step of tourSteps(this.outline)) {
- step.outdated = changedPaths.has(step.anchor.path) || !this.findRow(step.anchor.path, step.anchor.side, step.anchor.startLine);
- }
+ reconcileTourEvidence(this.outline, full);
+ await reconcileTourNotes(this.outline, full);
for (const finding of this.outline?.findings ?? []) {
const row = this.findRow(finding.path, finding.side, finding.line);
finding.outdated = changedPaths.has(finding.path) || row?.content !== finding.lineContent;
@@ -898,6 +901,7 @@ export class ReviewSession {
const session = new ReviewSession(comparison, adapters, { ...defaults, attached, preferences, includeFindings }, bridge, persisted, globalDiffPreferences);
// Renderer choice belongs to the reviewer, including when resuming an older review.
session.diffRenderer = await loadGlobalDiffRenderer(preferenceDirectory);
+ await reconcileTourNotes(session.outline, session.fullComparison);
await session.selectComparisonView();
await session.updateRevisionSummary(session.fullComparison).catch(() => undefined);
if (session.outline && !session.outline.briefing) session.outline.briefing = await buildBriefing(session.comparison, session.outline, session.briefingIntent());
@@ -1026,6 +1030,20 @@ export class ReviewSession {
this.agentActivity = structuredClone(interactive ?? background ?? latestTerminal ?? activity);
}
+ tourCode(stepId: string) {
+ const step = tourSteps(this.outline).find(step => step.id === stepId);
+ if (!step) throw new ReviewError("This tour stop does not exist.");
+ return { ...tourCode(step, this.fullComparison), revision: this.revision };
+ }
+
+ private currentTourCoverage() {
+ const signature = JSON.stringify(tourSteps(this.outline).map(step => [step.anchor, step.relatedAnchors, step.freshness, step.outdated]));
+ if (this.coverageCache?.comparison !== this.fullComparison || this.coverageCache.signature !== signature) {
+ this.coverageCache = { comparison: this.fullComparison, signature, value: tourCoverage(this.outline, this.fullComparison) };
+ }
+ return structuredClone(this.coverageCache.value);
+ }
+
snapshot() {
const { patch: _patch, ...rawComparison } = this.comparison;
const diffRowCount = rawComparison.files.reduce(
@@ -1057,6 +1075,7 @@ export class ReviewSession {
return {
comparison,
outline,
+ tourCoverage: this.currentTourCoverage(),
currentStepIndex: this.currentStepIndex,
comments: this.comments.map(comment => {
const githubUnavailableReason = this.githubCommentUnavailableReason(comment);
@@ -1462,13 +1481,14 @@ export class ReviewSession {
const current = tourSteps(this.outline).find((candidate) => candidate.id === stepId);
if (!current || current.explanation) return;
const previousRevision = this.revision;
- current.explanation = generated.value;
+ const previous = { explanation: current.explanation, explanationDetail: current.explanationDetail, notes: current.notes };
+ Object.assign(current, explanationFields(generated.value));
this.revision += 1;
try {
await this.persistAgentResult(generated.receipts);
} catch (error) {
- if (current.explanation === generated.value && this.revision === previousRevision + 1) {
- current.explanation = undefined;
+ if (current.explanation === generated.value.summary && this.revision === previousRevision + 1) {
+ Object.assign(current, previous);
this.revision = previousRevision;
}
throw error;
@@ -1664,6 +1684,8 @@ export class ReviewSession {
receipts.push(...linked.receipts);
delete generated.value.briefingProposal;
this.outline = generated.value;
+ for (const step of tourSteps(this.outline)) step.evidence = captureTourEvidence(step, this.comparison);
+ reconcileTourEvidence(this.outline, this.fullComparison);
this.currentStepIndex = 0;
} else if (this.currentStepIndex < 0 || this.currentStepIndex >= tourSteps(this.outline).length) {
this.currentStepIndex = 0;
@@ -1677,7 +1699,7 @@ export class ReviewSession {
const explanation = await this.agent.explainStep(step, this.currentStepIndex, steps.length, this.outline);
receipts.push(...explanation.receipts);
this.ensureComparisonCurrent(comparisonGeneration);
- step.explanation = explanation.value;
+ Object.assign(step, explanationFields(explanation.value));
}
this.ensureOpen();
this.revision += 1;
@@ -1734,7 +1756,7 @@ export class ReviewSession {
await this.persistAgentResult(receipts);
return this.snapshot();
}
- step.explanation = explanation.value;
+ Object.assign(step, explanationFields(explanation.value));
}
this.ensureOpen();
this.currentStepIndex = index;
@@ -2444,9 +2466,6 @@ export class ReviewSession {
comment.status = "outdated";
}
}
- for (const step of tourSteps(this.outline)) {
- step.outdated = !this.findRow(step.anchor.path, step.anchor.side, step.anchor.startLine);
- }
this.refreshFindingLifecycles();
if (proposal && proposed && activeRequest) {
this.recordAgentActivity(activeRequest.baselineComparison.files, proposed.files, context, proposal);
@@ -2617,7 +2636,6 @@ export class ReviewSession {
comment.status = "outdated";
}
}
- for (const step of tourSteps(this.outline)) step.outdated = !this.findRow(step.anchor.path, step.anchor.side, step.anchor.startLine);
this.refreshFindingLifecycles();
await this.persist();
return this.snapshot();
diff --git a/src/store.ts b/src/store.ts
index d23a99e..ac3042a 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -116,6 +116,32 @@ function validAnchor(value: unknown): boolean {
Number.isInteger(value.endLine) && Number(value.endLine) >= Number(value.startLine);
}
+function validTourReading(step: Record, paths: Set): boolean {
+ if (step.relatedAnchors !== undefined && (!Array.isArray(step.relatedAnchors) || step.relatedAnchors.length > 7 || !step.relatedAnchors.every(anchor => validAnchor(anchor) && paths.has(anchor.path) && anchor.endLine - anchor.startLine <= 500))) return false;
+ if (step.importance !== undefined && !["key", "normal", "context"].includes(String(step.importance))) return false;
+ if (step.explanationDetail !== undefined && !nonEmptyString(step.explanationDetail, 500_000)) return false;
+ if (step.freshness !== undefined && !["current", "outdated", "unverified"].includes(String(step.freshness))) return false;
+ if (step.missingEvidence !== undefined && (!Number.isSafeInteger(step.missingEvidence) || Number(step.missingEvidence) < 0 || Number(step.missingEvidence) > 4_008)) return false;
+ if (step.notes !== undefined && (!Array.isArray(step.notes) || step.notes.length > 2 || !step.notes.every(note => record(note) &&
+ ["decision", "upkeep", "limitation", "divergence", "test-gap"].includes(String(note.kind)) && nonEmptyString(note.text, 2_000) &&
+ (note.scope === undefined || nonEmptyString(note.scope, 2_000)) && (note.kind !== "test-gap" || nonEmptyString(note.scope, 2_000)) &&
+ (note.outdated === undefined || typeof note.outdated === "boolean") && Array.isArray(note.sources) && note.sources.length >= (note.kind === "divergence" ? 2 : 1) && note.sources.length <= 4 &&
+ note.sources.every(source => record(source) && validAnchor(source.anchor) && nonEmptyString(source.quote, 20_000) &&
+ (source.blob === undefined || (typeof source.blob === "string" && /^[0-9a-f]{40,64}$/.test(source.blob))))))) return false;
+ const evidence = step.evidence;
+ if (evidence !== undefined) {
+ if (!record(evidence) || evidence.version !== 1 || !Array.isArray(evidence.anchors) || evidence.anchors.length !== 1 + (Array.isArray(step.relatedAnchors) ? step.relatedAnchors.length : 0)) return false;
+ for (const saved of evidence.anchors) {
+ if (!record(saved) || !validAnchor(saved.anchor) || !Array.isArray(saved.blocks) || saved.blocks.length > 501) return false;
+ for (const block of saved.blocks) {
+ if (!record(block) || typeof block.fingerprint !== "string" || !/^[0-9a-f]{64}$/.test(block.fingerprint) ||
+ !Number.isSafeInteger(block.startOffset) || Number(block.startOffset) < 0 || !Number.isSafeInteger(block.endOffset) || Number(block.endOffset) < Number(block.startOffset)) return false;
+ }
+ }
+ }
+ return true;
+}
+
function validOutline(value: unknown): boolean {
if (!record(value) || !nonEmptyString(value.title, 8_000) || !nonEmptyString(value.summary, 50_000)) return false;
if (value.planningNotes !== undefined && (!Array.isArray(value.planningNotes) || value.planningNotes.length > 20 || !value.planningNotes.every((note) => nonEmptyString(note, 2_000)))) return false;
@@ -142,6 +168,7 @@ function validOutline(value: unknown): boolean {
if (!record(step) || !nonEmptyString(step.id, 128) || stepIds.has(step.id) || !nonEmptyString(step.title, 8_000) ||
!nonEmptyString(step.objective, 50_000) || !validAnchor(step.anchor) || !filePaths.has(String((step.anchor as Record).path)) ||
(step.explanation !== undefined && !nonEmptyString(step.explanation, 500_000)) ||
+ !validTourReading(step, filePaths) ||
(step.outdated !== undefined && typeof step.outdated !== "boolean")) return false;
stepIds.add(step.id);
phaseSteps.set(step.id, step);
diff --git a/src/tour-evidence.ts b/src/tour-evidence.ts
new file mode 100644
index 0000000..ec4e70d
--- /dev/null
+++ b/src/tour-evidence.ts
@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+import type { DiffFile, DiffHunk, DiffRow, GitComparison, TourAnchor, TourOutline, TourStep, TourStepEvidence } from "./types.ts";
+import { tourSteps } from "./tour.ts";
+
+export const MAX_TOUR_ANCHORS = 8;
+export const tourAnchors = (step: TourStep): TourAnchor[] => [step.anchor, ...(step.relatedAnchors ?? [])];
+const lineAt = (row: DiffRow, side: TourAnchor["side"]) => side === "old" ? row.oldLine : row.newLine;
+const fingerprint = (hunk: DiffHunk) => createHash("sha256").update(JSON.stringify(hunk.rows.map(row => [row.kind, row.content]))).digest("hex");
+const firstLine = (hunk: DiffHunk, side: TourAnchor["side"]) => hunk.rows.map(row => lineAt(row, side)).find((line): line is number => line !== null);
+const intersects = (hunk: DiffHunk, anchor: TourAnchor) => hunk.rows.some(row => {
+ const line = lineAt(row, anchor.side);
+ return line !== null && line >= anchor.startLine && line <= anchor.endLine;
+});
+
+export function validTourAnchor(value: unknown, comparison: GitComparison, paths?: ReadonlySet): value is TourAnchor {
+ if (!value || typeof value !== "object") return false;
+ const a = value as TourAnchor;
+ if (typeof a.path !== "string" || !["old", "new"].includes(a.side) || !Number.isSafeInteger(a.startLine) || !Number.isSafeInteger(a.endLine) || a.startLine < 1 || a.endLine < a.startLine || a.endLine - a.startLine > 500 || (paths && !paths.has(a.path))) return false;
+ const file = comparison.files.find(file => file.path === a.path);
+ if (!file) return false;
+ const lines = new Set(file.hunks.flatMap(hunk => hunk.rows.map(row => lineAt(row, a.side))));
+ for (let line = a.startLine; line <= a.endLine; line++) if (!lines.has(line)) return false;
+ return true;
+}
+
+/** Store content identities and range offsets, not line-number identities. */
+export function captureTourEvidence(step: TourStep, comparison: GitComparison): TourStepEvidence {
+ return { version: 1, anchors: tourAnchors(step).map(anchor => {
+ const file = comparison.files.find(file => file.path === anchor.path);
+ const blocks = (file?.hunks ?? []).filter(hunk => intersects(hunk, anchor)).map(hunk => {
+ const start = firstLine(hunk, anchor.side)!;
+ const lines = hunk.rows.map(row => lineAt(row, anchor.side)).filter((line): line is number => line !== null && line >= anchor.startLine && line <= anchor.endLine);
+ return { fingerprint: fingerprint(hunk), startOffset: Math.min(...lines) - start, endOffset: Math.max(...lines) - start };
+ });
+ return { anchor: { ...anchor }, blocks };
+ }) };
+}
+
+/** Missing or ambiguous content stays stale; never accept whatever moved onto the old line. */
+export function reconcileTourEvidence(outline: TourOutline | undefined, comparison: GitComparison): void {
+ const indexed = new Map(comparison.files.map(file => [file.path, file.hunks.map(hunk => ({ hunk, fingerprint: fingerprint(hunk) }))]));
+ for (const step of tourSteps(outline)) {
+ if (step.evidence?.version !== 1 || !step.evidence.anchors?.length) {
+ step.freshness = step.outdated ? "outdated" : "unverified";
+ continue;
+ }
+ let missing = 0;
+ const anchors: TourAnchor[] = [];
+ for (const saved of step.evidence.anchors) {
+ const ranges: Array<[number, number]> = [];
+ const file = comparison.files.find(file => file.path === saved.anchor.path);
+ const entries = file ? indexed.get(file.path) ?? [] : [];
+ if (!saved.blocks.length) missing++;
+ for (const block of saved.blocks) {
+ const matches = entries.filter(entry => entry.fingerprint === block.fingerprint);
+ if (matches.length !== 1) { missing++; continue; }
+ const start = firstLine(matches[0]!.hunk, saved.anchor.side);
+ if (start === undefined) { missing++; continue; }
+ ranges.push([start + block.startOffset, start + block.endOffset]);
+ }
+ if (ranges.length && file) anchors.push({ ...saved.anchor, path: file.path, startLine: Math.min(...ranges.map(range => range[0])), endLine: Math.max(...ranges.map(range => range[1])) });
+ }
+ step.missingEvidence = missing;
+ step.outdated = missing > 0 || anchors.length !== step.evidence.anchors.length;
+ step.freshness = step.outdated ? "outdated" : "current";
+ if (!step.outdated) {
+ step.anchor = anchors[0]!;
+ if (anchors.length > 1) step.relatedAnchors = anchors.slice(1);
+ }
+ }
+}
+
+export interface UncoveredTourBlock {
+ id: string; path: string; anchor?: TourAnchor; reason: string; partial: boolean;
+}
+export interface TourCoverage {
+ total: number; covered: number; partial: number; unverifiedSteps: number;
+ uncovered: UncoveredTourBlock[]; omitted: number;
+}
+function blockAnchor(file: DiffFile, hunk: DiffHunk): TourAnchor | undefined {
+ const side = file.status === "deleted" ? "old" : "new";
+ const lines = hunk.rows.map(row => lineAt(row, side)).filter((line): line is number => line !== null);
+ return lines.length ? { path: file.path, side, startLine: Math.min(...lines), endLine: Math.max(...lines) } : undefined;
+}
+const generated = (path: string) => /(?:^|\/)(?:Cargo\.lock|package-lock\.json|bun\.lockb?|yarn\.lock|pnpm-lock\.yaml|go\.sum)$|\.min\.[cm]?js$|\.snap$/.test(path);
+
+/** Count changed rows, not surrounding context. A partial block is never reported covered. */
+export function tourCoverage(outline: TourOutline | undefined, comparison: GitComparison): TourCoverage {
+ const steps = tourSteps(outline);
+ const anchors = steps.filter(step => step.freshness === "current" && !step.outdated).flatMap(tourAnchors);
+ const result: TourCoverage = { total: 0, covered: 0, partial: 0, unverifiedSteps: steps.filter(step => step.freshness === "unverified").length, uncovered: [], omitted: 0 };
+ const append = (block: UncoveredTourBlock) => result.uncovered.length < 100 ? result.uncovered.push(block) : result.omitted++;
+ for (const file of comparison.files) {
+ const hunks = file.hunks.filter(hunk => hunk.rows.some(row => row.kind === "addition" || row.kind === "deletion"));
+ if (!hunks.length) {
+ result.total++;
+ append({ id: `${file.path}:metadata`, path: file.path, partial: false, reason: "Binary, empty-file, rename or metadata change; inspect this file separately." });
+ continue;
+ }
+ for (const [index, hunk] of hunks.entries()) {
+ result.total++;
+ const changed = hunk.rows.filter(row => row.kind === "addition" || row.kind === "deletion");
+ // A before/after replacement is one change. Covering its new range also
+ // covers the paired deletions (and vice versa), but not a separate edit.
+ let covered = 0;
+ for (let at = 0; at < hunk.rows.length;) {
+ if (!["addition", "deletion"].includes(hunk.rows[at]!.kind)) { at++; continue; }
+ const run: DiffRow[] = [];
+ while (at < hunk.rows.length && ["addition", "deletion"].includes(hunk.rows[at]!.kind)) run.push(hunk.rows[at++]!);
+ const sides = (["old", "new"] as const).map(side => run.filter(row => lineAt(row, side) !== null));
+ const complete = sides.some((rows, i) => rows.length && rows.every(row => anchors.some(anchor => anchor.path === file.path && anchor.side === (i ? "new" : "old") && lineAt(row, anchor.side)! >= anchor.startLine && lineAt(row, anchor.side)! <= anchor.endLine)));
+ if (complete) covered += run.length;
+ else covered += run.filter(row => anchors.some(anchor => anchor.path === file.path && lineAt(row, anchor.side) !== null && lineAt(row, anchor.side)! >= anchor.startLine && lineAt(row, anchor.side)! <= anchor.endLine)).length;
+ }
+ if (covered === changed.length) { result.covered++; continue; }
+ if (covered) result.partial++;
+ append({ id: `${file.path}:${fingerprint(hunk)}:${index}`, path: file.path, anchor: blockAnchor(file, hunk), partial: covered > 0,
+ reason: covered ? "Only part of this changed block is covered by current tour stops." : generated(file.path) ? "Generated or lockfile change outside the current tour stops." : "No current tour stop covers this changed block." });
+ }
+ }
+ return result;
+}
+
+/** Small, read-only before/after groups for the focused step viewer. */
+export function tourCode(step: TourStep, comparison: GitComparison) {
+ const groups: Array<{ id: string; path: string; anchor: TourAnchor; rows: DiffRow[]; limited: boolean }> = [];
+ let budget = 600;
+ let characters = 100_000;
+ let limited = false;
+ const used = new Set();
+ if (!step.outdated) for (const anchor of tourAnchors(step)) {
+ const file = comparison.files.find(file => file.path === anchor.path);
+ for (const hunk of file?.hunks ?? []) {
+ if (!intersects(hunk, anchor) || (used.has(hunk) && hunk.rows.length <= 160)) continue;
+ used.add(hunk);
+ const hit = hunk.rows.findIndex(row => {
+ const line = lineAt(row, anchor.side);
+ return line !== null && line >= anchor.startLine;
+ });
+ const start = hunk.rows.length > 160 ? Math.max(0, hit - 4) : 0;
+ const rows: DiffRow[] = [];
+ for (const row of hunk.rows.slice(start, start + Math.min(160, budget))) {
+ if (row.content.length > characters) { limited = true; break; }
+ rows.push(row); characters -= row.content.length;
+ }
+ if (!rows.length) { limited = true; continue; }
+ budget -= rows.length;
+ groups.push({ id: `tour-${groups.length}`, path: file!.path, anchor, rows, limited: rows.length !== hunk.rows.length });
+ }
+ }
+ return { stepId: step.id, freshness: step.freshness ?? "unverified", groups, limited: limited || budget <= 0 };
+}
diff --git a/src/tour-reading.ts b/src/tour-reading.ts
new file mode 100644
index 0000000..5fbdab9
--- /dev/null
+++ b/src/tour-reading.ts
@@ -0,0 +1,70 @@
+import { loadCapturedSource } from "./diff-sources.ts";
+import { ReviewError } from "./errors.ts";
+import { tourSteps } from "./tour.ts";
+import type { GitComparison, TourAnchor, TourExplanation, TourNote, TourOutline, TourStep } from "./types.ts";
+
+export class TourExplanationError extends ReviewError {}
+const text = (value: unknown, max: number): value is string => typeof value === "string" && Boolean(value.trim()) && value.length <= max;
+const kinds = new Set(["decision", "upkeep", "limitation", "divergence", "test-gap"]);
+
+export const TOUR_READING_PROMPT = `Return JSON with {"summary":"2–4 short sentences, at most 100 words", "detail":"optional additional explanation in Markdown", "notes":[]}.
+The summary must stand alone. Put deeper mechanics in detail without repeating the summary. Detail is optional, at most 600 words. Use short active sentences and plain technical language.
+Most stops need no notes. At most two notes per stop, only when useful and supported by inspected repository evidence. A note has {"kind":"decision|upkeep|limitation|divergence|test-gap", "text":"concise observation", "scope":"required for test-gap: exact inspected test files and cases", "sources":[{"anchor":{"path":"repo-relative path","side":"new","startLine":1,"endLine":2},"quote":"exact complete source lines"}]}.
+Inspect captured source, callers, guards, and tests before making behavioral claims, including questions. A payload-free state does not prove a transition is reachable. Do not invent intent or alternative designs. For divergence cite both implementations. A test-gap is limited to named, inspected cases, never an assertion that no tests exist anywhere. Quotes are checked against captured Git source; they establish provenance, not proof of your inference. Do not pad the tour with notes or questions. Return only the finished reviewer-facing JSON; keep tool/progress commentary separate. Do not predict the next stop or add navigation instructions.`;
+
+/** Plain text remains readable for existing attached agents and saved sessions. */
+export async function parseTourExplanation(message: string, comparison?: GitComparison): Promise {
+ let raw = message.trim();
+ const fenced = /^```(?:json)?\s*\n([\s\S]*)\n```$/.exec(raw);
+ if (fenced && /^[{[]/.test(fenced[1]!.trim())) raw = fenced[1]!.trim();
+ if (!/^[{[]/.test(raw)) {
+ if (!text(raw, 50_000)) throw new TourExplanationError("The explanation is empty or too long.");
+ const paragraphs = raw.split(/\n\s*\n/);
+ return { summary: paragraphs.shift()!, ...(paragraphs.length ? { detail: paragraphs.join("\n\n") } : {}) };
+ }
+ let value: TourExplanation;
+ try { value = JSON.parse(raw); } catch { throw new TourExplanationError("Return valid explanation JSON."); }
+ if (!value || !text(value.summary, 4_000) || value.summary.trim().split(/\s+/).length > 100 || (value.detail !== undefined && (!text(value.detail, 20_000) || value.detail.trim().split(/\s+/).length > 600))) throw new TourExplanationError("Use a summary of at most 100 words and optional detail of at most 600 words.");
+ if (value.notes !== undefined && (!Array.isArray(value.notes) || value.notes.length > 2)) throw new TourExplanationError("Supply at most two grounded notes; omit notes when unnecessary.");
+ const notes: TourNote[] = [];
+ const sources = new Map>();
+ for (const note of value.notes ?? []) {
+ if (!note || !kinds.has(note.kind) || !text(note.text, 2_000) || (note.scope !== undefined && !text(note.scope, 2_000)) || (note.kind === "test-gap" && !text(note.scope, 2_000)) || !Array.isArray(note.sources) || note.sources.length < (note.kind === "divergence" ? 2 : 1) || note.sources.length > 4) throw new TourExplanationError("Each note needs inspected source quotes; test-gap also needs its inspected scope, divergence needs both sources.");
+ const checked: TourNote["sources"] = [];
+ for (const source of note.sources) {
+ const a = source?.anchor as TourAnchor | undefined;
+ if (!comparison || !a || !text(a.path, 4_096) || !["old", "new"].includes(a.side) || !Number.isSafeInteger(a.startLine) || !Number.isSafeInteger(a.endLine) || a.startLine < 1 || a.endLine < a.startLine || a.endLine - a.startLine > 100 || !text(source.quote, 20_000)) throw new TourExplanationError("Use bounded source anchors with exact complete-line quotes.");
+ const key = `${a.side}:${a.path}`;
+ let captured;
+ try {
+ if (!sources.has(key)) sources.set(key, loadCapturedSource(comparison, a.side, a.path));
+ captured = await sources.get(key)!;
+ } catch { throw new TourExplanationError(`Cannot verify note source ${a.path}. Omit the unsupported note or use captured source.`); }
+ const lines = captured.text.split("\n");
+ if (lines.at(-1) === "") lines.pop();
+ if (a.endLine > lines.length) throw new TourExplanationError(`Note range exceeds captured source ${a.path}.`);
+ const quote = lines.slice(a.startLine - 1, a.endLine).join("\n");
+ if (!quote || quote !== source.quote || !captured.blob) throw new TourExplanationError(`Note quote does not match ${a.path}:${a.startLine}-${a.endLine}. Inspect the captured source; do not invent evidence.`);
+ checked.push({ anchor: { path: a.path, side: a.side, startLine: a.startLine, endLine: a.endLine }, quote, blob: captured.blob });
+ }
+ notes.push({ kind: note.kind, text: note.text.trim(), ...(note.scope ? { scope: note.scope.trim() } : {}), sources: checked });
+ }
+ return { summary: value.summary.trim(), ...(value.detail ? { detail: value.detail.trim() } : {}), ...(notes.length ? { notes } : {}) };
+}
+
+export function explanationFields(value: TourExplanation): Pick {
+ return { explanation: value.summary, explanationDetail: value.detail, notes: value.notes };
+}
+
+/** Changed supporting files invalidate notes too, even when their displayed quote survives. */
+export async function reconcileTourNotes(outline: TourOutline | undefined, comparison: GitComparison): Promise {
+ const sources = new Map>();
+ for (const step of tourSteps(outline)) for (const note of step.notes ?? []) {
+ note.outdated = Boolean(step.outdated) || !note.sources?.length;
+ for (const source of note.sources ?? []) {
+ const key = `${source.anchor.side}:${source.anchor.path}`;
+ if (!sources.has(key)) sources.set(key, loadCapturedSource(comparison, source.anchor.side, source.anchor.path).then(value => value.blob).catch(() => null));
+ if (!source.blob || await sources.get(key) !== source.blob) note.outdated = true;
+ }
+ }
+}
diff --git a/src/types.ts b/src/types.ts
index 2096565..99cc5b6 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -89,10 +89,42 @@ export interface TourStep {
title: string;
objective: string;
anchor: TourAnchor;
+ /** Other changed source ranges needed to explain the same behavior. */
+ relatedAnchors?: TourAnchor[];
+ importance?: "key" | "normal" | "context";
explanation?: string;
+ explanationDetail?: string;
+ notes?: TourNote[];
+ /** Captured by the server, never trusted from a generated outline. */
+ evidence?: TourStepEvidence;
+ freshness?: "current" | "outdated" | "unverified";
+ missingEvidence?: number;
outdated?: boolean;
}
+export interface TourNote {
+ kind: "decision" | "upkeep" | "limitation" | "divergence" | "test-gap";
+ text: string;
+ /** Scope is required for absence claims; source quotes are checked separately. */
+ scope?: string;
+ sources: Array<{ anchor: TourAnchor; quote: string; blob?: string }>;
+ outdated?: boolean;
+}
+
+export interface TourStepEvidence {
+ version: 1;
+ anchors: Array<{
+ anchor: TourAnchor;
+ blocks: Array<{ fingerprint: string; startOffset: number; endOffset: number }>;
+ }>;
+}
+
+export interface TourExplanation {
+ summary: string;
+ detail?: string;
+ notes?: TourNote[];
+}
+
export interface TourFileChange {
path: string;
summary: string;
diff --git a/tests/agent.test.ts b/tests/agent.test.ts
index d800285..fb57096 100644
--- a/tests/agent.test.ts
+++ b/tests/agent.test.ts
@@ -308,15 +308,12 @@ test("asks for short plain-language stop explanations", async () => {
expect(event.prompt).toContain("If the state writer is not implemented yet");
expect(event.prompt).toContain("label documented transitions as planned rather than verified runtime behavior");
expect(event.prompt).toContain("Correct an unsupported premise instead of repeating it");
- expect(event.prompt).toContain("a complete explanation needs no question");
expect(event.prompt).toContain("next link in the tour's causal journey");
- expect(event.prompt).toContain("Keep it under 150 words");
- expect(event.prompt).toContain("Return only the finished reviewer-facing explanation");
- expect(event.prompt).toContain("skill announcements, or tool-use commentary");
- expect(event.prompt).toContain("Use short active sentences, one idea per sentence");
- expect(event.prompt).toContain("Avoid metaphors and idioms");
- expect(event.prompt).toContain("Do not predict, name, or summarize the next step");
- expect(event.prompt).toContain("select Next when ready");
+ expect(event.prompt).toContain("at most 100 words");
+ expect(event.prompt).toContain("Most stops need no notes");
+ expect(event.prompt).toContain("Quotes are checked against captured Git source");
+ expect(event.prompt).toContain("A payload-free state does not prove a transition is reachable");
+ expect(event.prompt).toContain("Do not predict the next stop");
expect(activities.at(-1)).toMatchObject({
status: "waiting",
label: "Preparing a tour stop",
@@ -325,10 +322,27 @@ test("asks for short plain-language stop explanations", async () => {
totalSteps: 2,
});
await bridge.respond(event!.id, "The value now changes here. Check the result.");
- expect((await pending).value).toBe("The value now changes here. Check the result.");
+ expect((await pending).value).toEqual({ summary: "The value now changes here. Check the result." });
expect(activities.at(-1)).toMatchObject({ status: "completed" });
});
+test("repairs unsupported explanation notes before returning a completed stop", async () => {
+ const bridge = new AttachedAgentBridge();
+ const agent = new TourAgent("/tmp/repository", { adapterId: "attached", modelId: "current-session" }, bridge);
+ const step = { id: "step", title: "Read code", objective: "Inspect the changed behavior", anchor: { path: "app.ts", side: "new" as const, startLine: 1, endLine: 1 } };
+ const pending = agent.explainStep(step, 0, 1, { title: "Review", summary: "Review", phases: [{ id: "phase", title: "Phase", summary: "Phase", fileChanges: [], steps: [step] }], callFlows: [], flows: [], findings: [] });
+ const [first] = await bridge.eventsAfter(0, 1_000);
+ if (!first || first.type !== "agent.prompt") throw new Error("Expected prompt");
+ await bridge.respond(first.id, JSON.stringify({ summary: "A summary.", notes: [{ kind: "test-gap", text: "There are no tests anywhere.", sources: [] }] }));
+ await bridge.ack(first.id);
+ const [retry] = await bridge.eventsAfter(first.sequence, 1_000);
+ if (!retry || retry.type !== "agent.prompt") throw new Error("Expected repair prompt");
+ expect(retry.prompt).toContain("Omit unsupported notes"); expect(retry.prompt).toContain("inspected scope");
+ await bridge.respond(retry.id, JSON.stringify({ summary: "The selected code changes the returned value.", detail: "Check its consumer in the captured source." }));
+ expect((await pending).value).toEqual({ summary: "The selected code changes the returned value.", detail: "Check its consumer in the captured source." });
+ agent.cancel();
+});
+
test("bounds tour prompts to a first-read comparison and orders phases as conceptual layers", async () => {
const bridge = new AttachedAgentBridge();
const agent = new TourAgent("/tmp/repository", { adapterId: "attached", modelId: "current-session", includeArchitecture: false, includeFindings: false }, bridge);
diff --git a/tests/briefing-sources.test.ts b/tests/briefing-sources.test.ts
index 85b1e6a..e4e2981 100644
--- a/tests/briefing-sources.test.ts
+++ b/tests/briefing-sources.test.ts
@@ -176,6 +176,10 @@ test("new tours complete diagram source links before saving their first Briefing
if (!linking || linking.type !== "agent.prompt") throw new Error("Missing source linking request");
expect(linking.prompt).toContain("attaching inspected source");
await session.bridge!.respond(linking.id, JSON.stringify({ decisions: decisions() })); await session.bridge!.ack(linking.id);
+ const explanation = (await session.bridge!.eventsAfter(linking.sequence, 3000)).find(event => event.type === "agent.prompt");
+ if (!explanation || explanation.type !== "agent.prompt") throw new Error("Missing grounded explanation request");
+ expect(explanation.kind).toBe("tour.explanation");
+ await session.bridge!.respond(explanation.id, JSON.stringify({ summary: "The named subtotal retains the original item reduction." })); await session.bridge!.ack(explanation.id);
await generation;
const persisted = await loadPersistedSession(stateFile);
expect(persisted.outline!.briefing!.diagrams.find(d => d.id === diagramId)!.elements.find(e => e.id === callId)!.sourceReview?.status).toBe("bound");
diff --git a/tests/outline-repair.test.ts b/tests/outline-repair.test.ts
index e882882..40f05e3 100644
--- a/tests/outline-repair.test.ts
+++ b/tests/outline-repair.test.ts
@@ -62,6 +62,16 @@ test("repairs invalid call evidence with exact diagnostics and the original resp
expect(result.receipts).toEqual([first.id, retry.id]);
});
+test("keeps grouped anchors and importance while stripping generator-owned freshness and explanation fields", async () => {
+ const { bridge, pending } = start();
+ const value = outline(true);
+ Object.assign(value.phases[0]!.steps[0]!, { relatedAnchors: [{ path: "app.ts", side: "new", startLine: 1, endLine: 1 }], importance: "key", evidence: { version: 1, anchors: [] }, freshness: "current", outdated: false, explanation: "Unvalidated prose", notes: [{ text: "Unvalidated note" }] });
+ await respond(bridge, 0, value);
+ const step = (await pending).value.phases[0]!.steps[0]!;
+ expect(step.relatedAnchors).toHaveLength(1); expect(step.importance).toBe("key");
+ expect(step.evidence).toBeUndefined(); expect(step.freshness).toBeUndefined(); expect(step.explanation).toBeUndefined(); expect(step.notes).toBeUndefined();
+});
+
test("after two retries keeps the valid route and scenarios with a bounded visible warning", async () => {
const { bridge, pending } = start();
const value = { ...outline(), planningNotes: Array.from({ length: 20 }, (_, i) => `Note ${i}`) };
diff --git a/tests/semantic-diff-tour.test.ts b/tests/semantic-diff-tour.test.ts
index e76c364..2c12fb3 100644
--- a/tests/semantic-diff-tour.test.ts
+++ b/tests/semantic-diff-tour.test.ts
@@ -127,14 +127,14 @@ test("agent requests captured facts after live edits, with unchanged source navi
if (!event || event.type !== "agent.prompt") throw new Error("Expected tour prompt");
const evidence = data(event.prompt);
expect(evidence.status).toBe("analysed"); expect(evidence.changes.find((entry: SemanticChange) => entry.name === "total").inputs.added).toEqual([{ name: "discount", optional: true }]);
- expect(event.prompt).not.toContain("liveOnly"); expect(event.prompt).toContain(fixture.comparison.patch); expect(event.prompt).toContain("Anchor: cart.ts:1-1 (new side)");
+ expect(event.prompt).not.toContain("liveOnly"); expect(event.prompt).toContain(fixture.comparison.patch); expect(event.prompt).toContain("Code ranges for this stop: cart.ts:1-1 (new side)");
expect(event.prompt).toContain("A review question is optional"); expect(event.prompt).toContain("do not pair ambiguous versions or infer rationale");
expect(event.prompt).toContain(`Captured source: before ${fixture.comparison.mergeBase}, after ${fixture.comparison.sourceTree}`);
expect(event.prompt).toContain("inspect these exact Git objects with git show");
expect(event.prompt).toContain("Never substitute current workspace files");
expect(cachedSemanticSummaries(fixture.comparison)).toHaveLength(1);
await bridge.respond(event.id, "The total accepts an optional discount. Check the omitted-discount case.");
- expect((await pending).value).toContain("optional discount"); agent.cancel();
+ expect((await pending).value.summary).toContain("optional discount"); agent.cancel();
const added = data(await syntaxContextForTourStep(fixture.comparison, { ...realStep, anchor: { ...realStep.anchor, path: "New.kt" } }));
expect(added.language).toBe("kotlin"); expect(added.changes[0].categories).toEqual(["added"]);
const removed = data(await syntaxContextForTourStep(fixture.comparison, { ...realStep, anchor: { ...realStep.anchor, path: "removed.ts", side: "old" } }));
diff --git a/tests/store.test.ts b/tests/store.test.ts
index 838eb15..e9364cc 100644
--- a/tests/store.test.ts
+++ b/tests/store.test.ts
@@ -69,6 +69,20 @@ function persistedSession(): PersistedReviewSession {
};
}
+test("persists bounded reading metadata and rejects malformed related anchors, notes and fingerprints", async () => {
+ const path = await temporaryStateFile(), session = persistedSession(), step = session.outline!.phases[0]!.steps[0]!;
+ step.relatedAnchors = [{ ...step.anchor, side: "old" }]; step.importance = "key"; step.explanationDetail = "Additional detail.";
+ step.notes = [{ kind: "limitation", text: "A scoped limitation.", sources: [{ anchor: step.anchor, quote: "return result;", blob: "a".repeat(40) }] }];
+ step.evidence = { version: 1, anchors: [step.anchor, ...step.relatedAnchors].map(anchor => ({ anchor, blocks: [{ fingerprint: "a".repeat(64), startOffset: 0, endOffset: 0 }] })) };
+ await savePersistedSession(path, session);
+ expect((await loadPersistedSession(path)).outline!.phases[0]!.steps[0]).toEqual(step);
+ for (const fields of [{ relatedAnchors: [{ ...step.anchor, path: "outside-phase.ts" }] }, { importance: "critical" }, { notes: [{ kind: "test-gap", text: "No tests", sources: [] }] }, { evidence: { version: 1, anchors: [] } }, { freshness: "trusted" }]) {
+ const invalid = structuredClone(session); Object.assign(invalid.outline!.phases[0]!.steps[0]!, fields);
+ await savePersistedSession(path, invalid);
+ await expect(loadPersistedSession(path)).rejects.toThrow("invalid schema");
+ }
+});
+
test("persists a complete session atomically and with owner-only permissions where supported", async () => {
const path = await temporaryStateFile();
const expected = persistedSession();
diff --git a/tests/tour-evidence.test.ts b/tests/tour-evidence.test.ts
new file mode 100644
index 0000000..e0567c3
--- /dev/null
+++ b/tests/tour-evidence.test.ts
@@ -0,0 +1,94 @@
+import { expect, test } from "bun:test";
+import { parseUnifiedDiff } from "../src/diff.ts";
+import { captureTourEvidence, reconcileTourEvidence, tourCode, tourCoverage, validTourAnchor } from "../src/tour-evidence.ts";
+import type { GitComparison, TourOutline, TourStep } from "../src/types.ts";
+
+const patch = `diff --git a/app.ts b/app.ts
+--- a/app.ts
++++ b/app.ts
+@@ -1,5 +1,5 @@
+ first
+-oldOne()
++newOne()
+ middle
+-oldTwo()
++newTwo()
+ last
+diff --git a/test.ts b/test.ts
+--- a/test.ts
++++ b/test.ts
+@@ -1 +1 @@
+-oldTest()
++newTest()
+diff --git a/image.png b/image.png
+Binary files a/image.png and b/image.png differ
+`;
+const comparison = (): GitComparison => ({ repositoryRoot: "/tmp/test", repositoryName: "test", base: "main", head: "head", mergeBase: "base", patch, repositoryFiles: [], files: parseUnifiedDiff(patch) });
+const step = (): TourStep => ({ id: "one", title: "Change", objective: "Read the change", anchor: { path: "app.ts", side: "new", startLine: 2, endLine: 2 } });
+const outline = (...steps: TourStep[]): TourOutline => ({ title: "Tour", summary: "Summary", phases: [{ id: "one", title: "Phase", summary: "Summary", fileChanges: [], steps }], callFlows: [], flows: [], findings: [] });
+function stamped(s = step(), c = comparison()) { s.evidence = captureTourEvidence(s, c); const o = outline(s); reconcileTourEvidence(o, c); return { s, o, c }; }
+
+test("coverage distinguishes partial blocks, grouped tests and binary changes", () => {
+ const { s, o, c } = stamped();
+ expect(tourCoverage(o, c)).toMatchObject({ total: 3, covered: 0, partial: 1 });
+ s.relatedAnchors = [{ path: "app.ts", side: "old", startLine: 4, endLine: 4 }, { path: "test.ts", side: "new", startLine: 1, endLine: 1 }];
+ s.evidence = captureTourEvidence(s, c); reconcileTourEvidence(o, c);
+ const coverage = tourCoverage(o, c);
+ expect(coverage).toMatchObject({ total: 3, covered: 2, partial: 0 });
+ expect(coverage.uncovered).toHaveLength(1); expect(coverage.uncovered[0]?.path).toBe("image.png");
+ expect(tourCode(s, c).groups.map(group => group.path)).toEqual(["app.ts", "test.ts"]);
+});
+
+test("covering a subset of contiguous added lines is partial, not complete or absent", () => {
+ const c = comparison(); c.files[0]!.hunks[0]!.rows = [1, 2, 3].map(line => ({ kind: "addition", content: `line ${line}`, oldLine: null, newLine: line }));
+ const { o } = stamped(step(), c);
+ expect(tourCoverage(o, c)).toMatchObject({ covered: 0, partial: 1 });
+});
+
+test("content identities relocate both sides after line shifts and survive serialization", () => {
+ const { s, o, c } = stamped(); s.relatedAnchors = [{ ...s.anchor, side: "old" }]; s.evidence = captureTourEvidence(s, c);
+ const restored = JSON.parse(JSON.stringify(o)) as TourOutline;
+ for (const row of c.files[0]!.hunks[0]!.rows) { if (row.oldLine !== null) row.oldLine += 20; if (row.newLine !== null) row.newLine += 30; }
+ reconcileTourEvidence(restored, c);
+ expect(restored.phases[0]!.steps[0]).toMatchObject({ freshness: "current", anchor: { startLine: 32 }, relatedAnchors: [{ startLine: 22 }] });
+});
+
+test("changed, removed and ambiguous evidence stays stale even when old line numbers exist", () => {
+ for (const mode of ["changed", "removed", "ambiguous"]) {
+ const { s, o, c } = stamped();
+ const hunk = c.files[0]!.hunks[0]!;
+ if (mode === "changed") hunk.rows[2]!.content = "different()";
+ if (mode === "removed") c.files[0]!.hunks = [];
+ if (mode === "ambiguous") c.files[0]!.hunks.push(structuredClone(hunk));
+ reconcileTourEvidence(o, c);
+ expect(s.freshness).toBe("outdated"); expect(s.missingEvidence).toBeGreaterThan(0);
+ expect(tourCode(s, c).groups).toEqual([]); expect(tourCoverage(o, c).covered).toBe(0);
+ }
+});
+
+test("legacy stops remain readable but cannot claim verified coverage", () => {
+ const s = step(), o = outline(s), c = comparison(); reconcileTourEvidence(o, c);
+ expect(s.freshness).toBe("unverified"); expect(tourCoverage(o, c)).toMatchObject({ covered: 0, unverifiedSteps: 1 });
+ expect(tourCode(s, c).groups).toHaveLength(1);
+});
+
+test("anchor validation rejects missing paths, invalid sides, gaps and unbounded ranges", () => {
+ const c = comparison(), a = step().anchor;
+ expect(validTourAnchor(a, c)).toBe(true);
+ for (const override of [{ path: "missing" }, { side: "both" }, { startLine: 0 }, { endLine: Infinity }, { endLine: 600 }, { startLine: 6, endLine: 6 }]) expect(validTourAnchor({ ...a, ...override }, c)).toBe(false);
+ expect(validTourAnchor(a, c, new Set(["test.ts"]))).toBe(false);
+});
+
+test("deleted-only files have old-side coverage links; large excerpts stay bounded", () => {
+ const c = comparison(); c.files[0]!.status = "deleted"; c.files[0]!.hunks[0]!.rows = Array.from({ length: 1_000 }, (_, i) => ({ kind: "deletion", content: `old ${i}`, oldLine: i + 1, newLine: null }));
+ const { s, o } = stamped({ ...step(), anchor: { path: "app.ts", side: "old", startLine: 950, endLine: 952 } }, c);
+ expect(tourCoverage(o, c).uncovered[0]?.anchor?.side).toBe("old");
+ const group = tourCode(s, c).groups[0]!;
+ expect(group.rows.some(row => row.oldLine === 950)).toBe(true); expect(group.limited).toBe(true); expect(group.rows.length).toBeLessThanOrEqual(160);
+});
+
+test("an oversized source line is omitted with a visible limit, never silently truncated", () => {
+ const c = comparison(); c.files[0]!.hunks[0]!.rows = [{ kind: "addition", content: "x".repeat(100_001), oldLine: null, newLine: 2 }];
+ const { s } = stamped(step(), c);
+ expect(tourCode(s, c)).toMatchObject({ groups: [], limited: true });
+});
diff --git a/tests/tour-reading-session.test.ts b/tests/tour-reading-session.test.ts
new file mode 100644
index 0000000..0d8d1d8
--- /dev/null
+++ b/tests/tour-reading-session.test.ts
@@ -0,0 +1,64 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { prepareTestFixture } from "../src/test-fixture.ts";
+import { loadPersistedSession, savePersistedSession } from "../src/store.ts";
+import { loadComparison } from "../src/git.ts";
+import { captureTourEvidence } from "../src/tour-evidence.ts";
+import { parseTourExplanation } from "../src/tour-reading.ts";
+import { ReviewSession } from "../src/session.ts";
+import { createRequestHandler } from "../src/server.ts";
+import { exportReview } from "../src/export.ts";
+
+const roots: string[] = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
+
+test("persisted tours retain grouped sources and coverage, relocate content on refresh, then reject changed evidence", async () => {
+ const root = await mkdtemp(join(tmpdir(), "diffcompass-tour-reading-")); roots.push(root);
+ const before = Array.from({ length: 100 }, (_, i) => i === 59 ? "export const value = 1;" : `// stable context ${i + 1}`).join("\n") + "\n";
+ const after = before.replace("value = 1", "value = 2");
+ const fixture = await prepareTestFixture({ root: join(root, "fixture"), extraFiles: { "src/fresh.ts": { before, after } } });
+ const saved = await loadPersistedSession(fixture.stateFile);
+ const comparison = await loadComparison(fixture.repository, saved.base);
+ const first = saved.outline!.phases[0]!.steps[0]!;
+ saved.outline!.phases[0]!.fileChanges.push({ path: "src/fresh.ts", summary: "Changes the value." }, { path: "src/receipt.ts", summary: "Formats the value." });
+ first.anchor = { path: "src/fresh.ts", side: "new", startLine: 60, endLine: 60 };
+ first.relatedAnchors = [{ path: "src/receipt.ts", side: "new", startLine: 3, endLine: 5 }];
+ first.importance = "key"; first.explanationDetail = "Details retained in saved tours.";
+ first.notes = (await parseTourExplanation(JSON.stringify({ summary: "Summary", notes: [{ kind: "limitation", text: "The value is fixed.", sources: [{ anchor: first.anchor, quote: "export const value = 2;" }] }] }), comparison)).notes;
+ for (const step of saved.outline!.phases.flatMap(phase => phase.steps)) step.evidence = captureTourEvidence(step, comparison);
+ saved.preferences = { ...saved.preferences!, prefetchSteps: 0 }; saved.pullRequest = undefined; delete saved.outline!.issueAssessment;
+ await savePersistedSession(fixture.stateFile, saved);
+ const defaults = { resume: true, stateFile: fixture.stateFile, attached: true, agentAdapters: [], diffPreferenceDirectory: join(root, "preferences") };
+ const session = await ReviewSession.create(fixture.repository, undefined, defaults);
+ expect(session.outline!.phases[0]!.steps[0]!.freshness).toBe("current");
+ expect(session.tourCode(first.id).groups.map(group => group.path)).toEqual(["src/fresh.ts", "src/receipt.ts"]);
+ const initialCoverage = session.snapshot().tourCoverage;
+ expect(initialCoverage.covered).toBeGreaterThan(0);
+ expect(initialCoverage.uncovered.some(block => block.path === "screens/receipt.png")).toBe(true);
+ for (const format of ["markdown", "html"] as const) {
+ const result = exportReview(session, format).content;
+ expect(result).toContain("Details retained in saved tours."); expect(result).toContain("Not covered"); expect(result).toContain("The value is fixed.");
+ }
+ const handler = createRequestHandler(session, join(root, "sessions"));
+ const url = "http://127.0.0.1:47550/api/tour/code?stepId=" + first.id;
+ expect((await handler(new Request(url))).status).toBe(401);
+ const response = await handler(new Request(url, { headers: { "x-diffcompass-token": session.browserToken } }));
+ expect(response.status).toBe(200); expect(response.headers.get("cache-control")).toBe("no-store");
+ expect((await response.json()).groups).toHaveLength(2);
+ await writeFile(join(fixture.repository, "src/fresh.ts"), "// inserted outside the changed block\n" + after);
+ await session.refreshComparison({ source: "manual" });
+ const relocated = session.outline!.phases[0]!.steps[0]!;
+ expect(relocated.freshness).toBe("current"); expect(relocated.anchor.startLine).toBe(61);
+ expect(relocated.notes?.[0]?.outdated).toBe(true); // Conservative supporting-file freshness.
+ expect(session.snapshot().tourCoverage.covered).toBe(initialCoverage.covered);
+ expect(session.snapshot().tourCoverage.total).toBe(initialCoverage.total + 1);
+ const current = await readFile(join(fixture.repository, "src/fresh.ts"), "utf8");
+ await writeFile(join(fixture.repository, "src/fresh.ts"), current.replace("value = 2", "value = 3"));
+ await session.refreshComparison({ source: "manual" });
+ expect(session.outline!.phases[0]!.steps[0]!.freshness).toBe("outdated"); expect(session.tourCode(first.id).groups).toEqual([]);
+ const resumed = await ReviewSession.create(fixture.repository, undefined, defaults);
+ expect(resumed.outline!.phases[0]!.steps[0]!.freshness).toBe("outdated");
+ expect(resumed.snapshot().tourCoverage).toEqual(session.snapshot().tourCoverage);
+}, 20_000);
diff --git a/tests/tour-reading.test.ts b/tests/tour-reading.test.ts
new file mode 100644
index 0000000..f20ac42
--- /dev/null
+++ b/tests/tour-reading.test.ts
@@ -0,0 +1,38 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadComparison } from "../src/git.ts";
+import { runProcess } from "../src/process.ts";
+import { parseTourExplanation, reconcileTourNotes } from "../src/tour-reading.ts";
+import type { TourOutline } from "../src/types.ts";
+const roots: string[] = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
+
+test("short summaries, expandable detail, and old attached-agent text are compatible", async () => {
+ expect(await parseTourExplanation("First paragraph.\n\nMore mechanics.")).toEqual({ summary: "First paragraph.", detail: "More mechanics." });
+ expect(await parseTourExplanation("First paragraph.\n\n```ts\ncall()\n```")).toEqual({ summary: "First paragraph.", detail: "```ts\ncall()\n```" });
+ expect(await parseTourExplanation('```json\n{"summary":"Short.","detail":"Details."}\n```')).toEqual({ summary: "Short.", detail: "Details." });
+ for (const message of ['{"summary":', '{"summary":""}', JSON.stringify({ summary: "word ".repeat(101) }), '{"summary":"Short.","notes":[{"kind":"test-gap","text":"No tests"}]}']) await expect(parseTourExplanation(message)).rejects.toThrow();
+});
+
+test("notes use immutable captured source, reject fabricated quotes, and stale on supporting changes", async () => {
+ const root = await mkdtemp(join(tmpdir(), "diffcompass-tour-notes-")); roots.push(root);
+ const git = (...args: string[]) => runProcess(["git", ...args], root);
+ await git("init", "-b", "main"); await git("config", "user.name", "Test"); await git("config", "user.email", "test@example.invalid");
+ await writeFile(join(root, "app.ts"), "old()\n"); await writeFile(join(root, "guard.ts"), "if (state === Failed) retry()\n");
+ await git("add", "."); await git("commit", "-m", "base"); await writeFile(join(root, "app.ts"), "newCode()\n");
+ const comparison = await loadComparison(root, "HEAD");
+ const anchor = { path: "guard.ts", side: "new" as const, startLine: 1, endLine: 1 };
+ const note = { kind: "limitation", text: "Retry is guarded by the failed state.", sources: [{ anchor, quote: "if (state === Failed) retry()" }] };
+ await writeFile(join(root, "guard.ts"), "if (state === Shown) retry()\n");
+ const value = await parseTourExplanation(JSON.stringify({ summary: "The guard limits retry.", notes: [note] }), comparison);
+ expect(value.notes?.[0]?.sources[0]?.blob).toMatch(/^[a-f0-9]{40,64}$/);
+ await expect(parseTourExplanation(JSON.stringify({ summary: "Summary", notes: [{ ...note, sources: [{ anchor: { ...anchor, endLine: 50 }, quote: note.sources[0]!.quote }] }] }), comparison)).rejects.toThrow("exceeds captured source");
+ await expect(parseTourExplanation(JSON.stringify({ summary: "Summary", notes: [{ ...note, sources: [{ anchor, quote: "if (state === Shown) retry()" }] }] }), comparison)).rejects.toThrow("does not match");
+ const outline = { phases: [{ steps: [{ notes: value.notes }] }] } as TourOutline;
+ await reconcileTourNotes(outline, comparison); expect(value.notes?.[0]?.outdated).toBe(false);
+ const refreshed = await loadComparison(root, "HEAD"); await reconcileTourNotes(outline, refreshed); expect(value.notes?.[0]?.outdated).toBe(true);
+ await expect(parseTourExplanation(JSON.stringify({ summary: "Summary", notes: [{ ...note, kind: "divergence" }] }), comparison)).rejects.toThrow("both sources");
+ await expect(parseTourExplanation(JSON.stringify({ summary: "Summary", notes: [{ ...note, kind: "test-gap" }] }), comparison)).rejects.toThrow("inspected scope");
+});
diff --git a/tests/ui-file-navigation.test.ts b/tests/ui-file-navigation.test.ts
index 2a2be6c..81fde54 100644
--- a/tests/ui-file-navigation.test.ts
+++ b/tests/ui-file-navigation.test.ts
@@ -10,7 +10,7 @@ function harness(monaco: boolean) {
const state = { tourMode:false, fileRequestId:0, collapsedFiles:new Set(["src/cart.ts"]), session:{comparison:{diffMode:"full"}}, monacoRenderer:{active:monaco, owns:()=>monaco, reveal:(...args: unknown[])=>{calls.push(["monaco",...args]);return pending;}} };
const elements = { diff:{querySelector:(selector: string)=>({scrollIntoView:(options: unknown)=>calls.push(["scroll",selector,options])})} };
const noop = () => {};
- const show = new Function("state","elements","CSS","filteredChangedFiles","renderActiveTab","renderDiff","renderComments","renderFindings","revealCodeLocation","renderTourAnnotation", `${source}; return showChangedFile;`)(
+ const show = new Function("state","elements","CSS","filteredChangedFiles","renderActiveTab","renderDiff","renderComments","renderFindings","revealCodeLocation","renderTourAnnotation", `const tourReading = { closeCode() {} }; ${source}; return showChangedFile;`)(
state,elements,{escape:(path: string)=>path},()=>[{path:"src/cart.ts"}],noop,noop,noop,noop,
(...args: unknown[])=>{calls.push(["line",...args]);return pending;},noop,
) as (path: string,line?: number,side?: string)=>Promise;
diff --git a/tests/ui-preparation-update.test.ts b/tests/ui-preparation-update.test.ts
index ed44763..022b30a 100644
--- a/tests/ui-preparation-update.test.ts
+++ b/tests/ui-preparation-update.test.ts
@@ -24,6 +24,7 @@ function harness(previous = snapshot()) {
let tick: () => Promise;
let renders = 0;
let explanationWrites = 0;
+ let readingWrites = 0;
let renderedExplanation = "";
let commentRenders = 0;
let activityRenders = 0;
@@ -48,6 +49,7 @@ function harness(previous = snapshot()) {
diff: { querySelectorAll: () => [anchor] },
"feedback-button": { classList: { toggle() {}, remove() {} } },
"tour-scroll": tourScroll,
+ "step-detail-body": { set innerHTML(_value: string) { readingWrites += 1; tourScroll.scrollTop = 0; } },
"step-explanation": { set innerHTML(value: string) {
explanationWrites += 1;
renderedExplanation = value;
@@ -55,7 +57,7 @@ function harness(previous = snapshot()) {
} },
};
const commentActions = app.slice(app.indexOf("async function saveInlineComment("), app.indexOf("async function askAgent("));
- const run = new Function("state", "elements", "window", "api", "reviewIsOpen", "currentStep", "renderMarkdown", "renderAgentActivity", "renderSession", "beginCloseCountdownForTransition", "renderComments", "closeInlineCommentEditor", "toast", "renderFindings", "renderTour", "focusCurrentStep", "renderMessages", "renderReviewerTaskAssessmentStatus", "renderActivities", "renderPullRequest", `${helpers}\n${commentActions}\n${poll}\nreturn { classify: isInPlaceSessionUpdate, classifyNavigation: isSamePhaseNavigationUpdate, saveInlineComment, deleteReviewComment };`);
+ const run = new Function("state", "elements", "window", "api", "reviewIsOpen", "currentStep", "renderMarkdown", "renderAgentActivity", "renderSession", "beginCloseCountdownForTransition", "renderComments", "closeInlineCommentEditor", "toast", "renderFindings", "renderTour", "focusCurrentStep", "renderMessages", "renderReviewerTaskAssessmentStatus", "renderActivities", "renderPullRequest", `const tourReading = { render() { elements["step-detail-body"].innerHTML = "updated"; } }; ${helpers}\n${commentActions}\n${poll}\nreturn { classify: isInPlaceSessionUpdate, classifyNavigation: isSamePhaseNavigationUpdate, saveInlineComment, deleteReviewComment };`);
const actions = run(state, elements, { setInterval(fn: () => Promise) { tick = fn; } },
async () => structuredClone(next), () => state.session.status === "open",
() => state.session.outline.phases.flatMap((phase) => phase.steps)[state.session.currentStepIndex],
@@ -81,6 +83,7 @@ function harness(previous = snapshot()) {
get tourRenders() { return tourRenders; },
get focusCalls() { return focusCalls; },
get explanationWrites() { return explanationWrites; },
+ get readingWrites() { return readingWrites; },
get renderedExplanation() { return renderedExplanation; },
};
}
@@ -165,6 +168,15 @@ test("the current explanation appears immediately without moving either pane", a
expect(h.renders).toBe(0);
});
+test("prepared detail and notes update in place without losing reading position", async () => {
+ const previous = snapshot(), h = harness(previous), next = structuredClone(previous);
+ next.revision += 1;
+ Object.assign(next.outline.phases[0]!.steps[0]!, { explanationDetail: "Extra mechanics.", notes: [{ kind: "limitation", text: "A scoped limit", sources: [] }] });
+ await h.poll(next);
+ expect(h.renders).toBe(0); expect(h.readingWrites).toBe(1);
+ expect(h.explanationWrites).toBe(0); expect(h.tourScroll.scrollTop).toBe(430); expect(h.diffNode.scrollTop).toBe(1700);
+});
+
test("structural updates and terminal state still render normally", async () => {
const mutations = [
(s: ReturnType) => { s.comparison.head = "def"; },
diff --git a/tests/ui.test.ts b/tests/ui.test.ts
index a86c7f4..f3c19aa 100644
--- a/tests/ui.test.ts
+++ b/tests/ui.test.ts
@@ -253,7 +253,7 @@ test("tour rendering annotates code without continuously stealing navigation", a
expect(html).toContain('id="current-step-return"');
expect(app).toContain("function updateCurrentStepReturnVisibility()");
expect(app).toContain('elements["diff-panel"].addEventListener("scroll", scheduleCurrentStepReturnUpdate');
- expect(app).toContain('elements["current-step-return"].addEventListener("click", () => void focusCurrentStep())');
+ expect(app).toContain('elements["current-step-return"].addEventListener("click", () => void (state.tourMode ? focusCurrentStep() : beginPreparedTour()))');
expect(styles).toContain(".diff-return { position: fixed;");
expect(renderTour).not.toContain("scrollIntoView");
expect(renderTour).not.toContain("showChangedFile");
@@ -523,7 +523,7 @@ test("tour mode scopes diffs to the current phase and can restore the baseline r
expect(app).toContain("if (phasePaths) return state.session.comparison.files.filter((file) => phasePaths.has(file.path))");
expect(app).toContain('const changedPathsOnly = state.tourMode || state.treeMode === "changes" || filtering');
expect(app).toContain("async function ensureTourPhaseDiffs()");
- expect(app).toContain('elements["tour-mode-toggle"].textContent = state.tourMode ? "Exit tour" : "Resume tour"');
+ expect(app).toContain('elements["tour-mode-toggle"].classList.toggle("hidden", !state.tourMode)');
expect(app).toContain('toast("Tour exited. All changed files are visible.")');
expect(app).toContain('toast("Tour resumed. Diffs are scoped to this phase.")');
expect(app).toContain('{ duration: 9_000, tone: "warning" }');