@imenam/mcp-feature-analyzer 1.0.3 → 1.0.4

package/dist/src/gui-worker.js

@@ -7,7 +7,7 @@ import path from "path";
 import fs from "fs";
 import { fileURLToPath } from "url";
 import { IPCMessageSchema, PUSHED_EVENT_TYPES } from "../shared/schemas/ipc.schema.js";
-import { AddNoteBodySchema, DeleteNoteBodySchema, SetFileReviewedBodySchema, SetFindingStatusBodySchema, SubmitReviewBodySchema, } from "../shared/schemas/api.schema.js";
+import { AddNoteBodySchema, DeleteNoteBodySchema, SetFileReviewedBodySchema, SetFindingStatusBodySchema, SubmitReviewBodySchema, UpdateNoteBodySchema, } from "../shared/schemas/api.schema.js";
 import { resolveLogDir } from "./core/log-dir.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function findProjectRoot(startDir) {
@@ -256,6 +256,12 @@ app.post("/api/analyses/:id/notes", async (c) => {
         return read.response;
     return forward(c, "ADD_NOTE", { analysisId: c.req.param("id"), body: read.body });
 });
+app.patch("/api/analyses/:id/notes/:noteId", async (c) => {
+    const read = await readBody(c, UpdateNoteBodySchema);
+    if ("response" in read)
+        return read.response;
+    return forward(c, "UPDATE_NOTE", { analysisId: c.req.param("id"), noteId: c.req.param("noteId"), body: read.body });
+});
 app.delete("/api/analyses/:id/notes/:noteId", async (c) => {
     const read = await readBody(c, DeleteNoteBodySchema);
     if ("response" in read)

package/dist/src/index.js

@@ -16,10 +16,10 @@ import { DEFAULT_HEAD_REF, localRepo } from "./core/git.js";
 import { agentRepo } from "./core/agent-repo.js";
 import { EXEC_ARG, handleAgentExec } from "./core/gateway-exec.js";
 import { resolveRole } from "./core/role.js";
-import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview } from "./core/review-actions.js";
+import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview, updateNote } from "./core/review-actions.js";
 import { GUI_REQUEST_TYPES, IPCMessageSchema } from "../shared/schemas/ipc.schema.js";
-import { AddNoteRequestSchema, AnalysisRequestSchema, DeleteNoteRequestSchema, SetFileReviewedRequestSchema, SetFindingStatusRequestSchema, SubmitReviewRequestSchema, } from "../shared/schemas/api.schema.js";
-import { ANALYSIS_MODES, DIAGRAM_KINDS, FINDING_KINDS, NODE_SHAPES, NODE_STATUSES, SEVERITIES, } from "../shared/schemas/analysis.schema.js";
+import { AddNoteRequestSchema, AnalysisRequestSchema, DeleteNoteRequestSchema, SetFileReviewedRequestSchema, SetFindingStatusRequestSchema, SubmitReviewRequestSchema, UpdateNoteRequestSchema, } from "../shared/schemas/api.schema.js";
+import { ANALYSIS_MODES, DIAGRAM_KINDS, EXPLANATION_SIDES, FINDING_KINDS, NODE_SHAPES, NODE_STATUSES, SEVERITIES, } from "../shared/schemas/analysis.schema.js";
 import { errorResult, textResult } from "./tools/types.js";
 import { createAnalysis } from "./tools/create-analysis.js";
 import { listAnalyses } from "./tools/list-analyses.js";
@@ -30,6 +30,9 @@ import { updateAnalysis } from "./tools/update-analysis.js";
 import { addFindings } from "./tools/add-findings.js";
 import { updateFinding } from "./tools/update-finding.js";
 import { deleteFindings } from "./tools/delete-findings.js";
+import { addExplanations } from "./tools/add-explanations.js";
+import { updateExplanation } from "./tools/update-explanation.js";
+import { deleteExplanations } from "./tools/delete-explanations.js";
 import { DEFAULT_NODE_SHAPE, DEFAULT_NODE_STATUS, setDiagram } from "./tools/set-diagram.js";
 import { deleteDiagram } from "./tools/delete-diagram.js";
 import { getReviewFeedback } from "./tools/get-review-feedback.js";
@@ -88,6 +91,7 @@ Concepts:
 - A **project** groups the analyses of one product or feature; the GUI files analyses by project.
 - The **overview** is your global analysis of the feature: its objective (what it lets users do), its approach (architecture choices, main flow) and the attention points the reviewer should check first. The **summary** lists the functional changes of the feature, one bullet per change, not one bullet per file.
 - A **finding** is a point for the reviewer: an issue anchored on changed lines, or a requirement_gap for requested behaviour that is missing (location optional). Severity: ${SEVERITIES.join(", ")}.
+- An **explanation** describes what a block of added or removed code does and how it works, so that the reviewer understands it before judging it. It is not a finding: it judges nothing and asks for nothing. It is anchored on new-side lines (added code) or old-side lines (removed code), and shown in the diff above the lines it describes.
 - A **diagram** is a flow, layers or mindmap picture of the feature. You give nodes and links only; the GUI lays them out.
 - The **review** belongs to the reviewer: files marked reviewed, findings ignored, notes, and a submitted decision with a prompt for you.
 
@@ -95,11 +99,19 @@ Workflow:
 1. list_analyses (with project) to find an analysis of the same feature: reuse it with update_analysis and refresh_analysis instead of creating a duplicate. Otherwise create_analysis with its project once the feature is developed.
 2. get_diff to read the frozen diff.
 3. update_analysis with the overview (objective, approach, attention_points) and the summary (the functional changes).
-4. add_findings for every problem, including requirement_gap findings for requested behaviour that is missing.
-5. set_diagram when a picture helps (impacted layers, process flow, concept tree).
-6. Tell the user to review the analysis in the GUI (the link is in the tool results).
-7. get_review_feedback to read the decision, the selected points and the prompt.
-8. Fix the code, then refresh_analysis to recompute the diff for a new review round.
+4. add_explanations for the long or complex blocks of added or removed code (see Explanation rules).
+5. add_findings for every problem, including requirement_gap findings for requested behaviour that is missing.
+6. set_diagram when a picture helps (impacted layers, process flow, concept tree).
+7. Tell the user to review the analysis in the GUI (the link is in the tool results).
+8. get_review_feedback to read the decision, the selected points and the prompt.
+9. Fix the code, then refresh_analysis to recompute the diff for a new review round; re-anchor or rewrite the outdated findings and explanations.
+
+Explanation rules:
+- Write one for every added or removed block that is long (a function or a block of about 30 lines or more) or complex (non-trivial algorithm, state machine, concurrency, recursion, tricky regular expression or data transformation). A 100-line function always gets one.
+- Cover the whole block, from its first to its last line. Title: the name of the block and its role, e.g. "parseUnifiedDiff: diff text to hunks".
+- Body: what the block does (inputs, outputs, effects), then how it works, step by step, in the order of the code; name the key variables and the edge cases it handles. For removed code, say what it did and what replaces it, if anything.
+- Describe, never judge: problems go in findings.
+- Skip trivial code (imports, getters, simple wiring): an explanation there only adds noise.
 
 Diagram rules:
 - One subject per diagram, 5 to 12 nodes; split a bigger picture into several diagrams.
@@ -108,7 +120,7 @@ Diagram rules:
 - flow for a process with steps and decisions; layers for the impact perimeter across architecture layers; mindmap for a tree of concepts (one root, one parent per node).
 
 Rules:
-- Line numbers are always NEW-side numbers, as shown by get_diff.
+- Line numbers are NEW-side numbers, as shown by get_diff, except for explanations of removed code, which use OLD-side numbers (side "old").
 - Nothing is ever written to the repository: suggestions are displayed to the reviewer only.
 - The reviewer alone decides which findings are ignored and when the review is submitted; you cannot change either.`;
 const server = new Server({ name: "mcp-feature-analyzer", version: APP_VERSION }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
@@ -192,6 +204,12 @@ function handleGuiRequest(msg) {
             afterUserMutation(analysis.id);
             return { analysis };
         }
+        case "UPDATE_NOTE": {
+            const request = parseRequest(UpdateNoteRequestSchema, msg.data);
+            const analysis = updateNote(store, request.analysisId, request.noteId, request.body);
+            afterUserMutation(analysis.id);
+            return { analysis };
+        }
         case "DELETE_NOTE": {
             const request = parseRequest(DeleteNoteRequestSchema, msg.data);
             const analysis = deleteNote(store, request.analysisId, request.noteId, request.body);
@@ -305,6 +323,18 @@ const LOCATION_PROPERTIES = {
     start_line: { type: "integer", minimum: 1, description: `First targeted line. ${LINE_NUMBERS_DOC}` },
     end_line: { type: "integer", minimum: 1, description: "Last targeted line, inclusive (default: start_line)." },
 };
+const EXPLANATION_LOCATION_PROPERTIES = {
+    path: LOCATION_PROPERTIES.path,
+    side: {
+        type: "string",
+        enum: [...EXPLANATION_SIDES],
+        description: 'Side of the diff the lines belong to (default "new"): "new" for added or kept code, with NEW-side numbers (second column of get_diff); ' +
+            '"old" for removed code, with OLD-side numbers (first column of get_diff), all shown in the diff and at least one removed.',
+    },
+    start_line: { type: "integer", minimum: 1, description: "First described line, on the side given by side." },
+    end_line: { type: "integer", minimum: 1, description: "Last described line, inclusive (default: start_line)." },
+};
+const EXPLANATION_BODY_DOC = "What the code does (inputs, outputs, effects), then how it works, step by step in the order of the code. Describe, never judge. Plain text; line breaks are kept.";
 const SEVERITY_DOC = `Severity: ${SEVERITIES.join(", ")} (from most to least serious).`;
 const FINDING_KIND_DOC = `Kind (default "issue"): "issue" is a problem in the changed code and needs a location; ` +
     `"requirement_gap" is requested behaviour that is missing and may have no location.`;
@@ -503,6 +533,61 @@ const TOOLS = [
             required: ["analysis_id", "finding_ids"],
         },
     },
+    {
+        name: "add_explanations",
+        description: "Explain blocks of added or removed code to the reviewer, as a batch: what each block does and how it works. " +
+            "Write one for every long (about 30 lines or more) or complex block; skip trivial code. An explanation judges nothing: problems go in findings. " +
+            "Each location is checked against the frozen diff and its lines are copied; if any explanation is invalid, nothing is added and every problem is reported.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanations: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Optional id (letters, digits, '_' or '-'); generated when omitted." },
+                            title: { type: "string", description: 'Name of the block and its role, e.g. "parseUnifiedDiff: diff text to hunks".' },
+                            body: { type: "string", description: EXPLANATION_BODY_DOC },
+                            ...EXPLANATION_LOCATION_PROPERTIES,
+                        },
+                        required: ["title", "body", "path", "start_line"],
+                    },
+                },
+            },
+            required: ["analysis_id", "explanations"],
+        },
+    },
+    {
+        name: "update_explanation",
+        description: "Change one explanation: title, body or location. A new location (path and start_line, with side for removed code) is checked against the diff " +
+            "and makes an outdated explanation current again; rewrite the body too when the code changed.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanation_id: { type: "string", description: "Id of the explanation, as shown by get_analysis." },
+                title: { type: "string", description: "New title." },
+                body: { type: "string", description: EXPLANATION_BODY_DOC },
+                ...EXPLANATION_LOCATION_PROPERTIES,
+            },
+            required: ["analysis_id", "explanation_id"],
+        },
+    },
+    {
+        name: "delete_explanations",
+        description: "Delete explanations by id, e.g. when the code they describe is gone. If any id is unknown, nothing is deleted.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                analysis_id: { type: "string", description: ANALYSIS_ID_DOC },
+                explanation_ids: { type: "array", minItems: 1, items: { type: "string" }, description: "Ids of the explanations to delete." },
+            },
+            required: ["analysis_id", "explanation_ids"],
+        },
+    },
     {
         name: "set_diagram",
         description: "Create a diagram, or fully replace the one with diagram_id, when a picture helps the reviewer (impact perimeter, process flow, concept map). " +
@@ -647,6 +732,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return afterMutation(updateFinding(store, params));
             case "delete_findings":
                 return afterMutation(deleteFindings(store, params));
+            case "add_explanations":
+                return afterMutation(addExplanations(store, params));
+            case "update_explanation":
+                return afterMutation(updateExplanation(store, params));
+            case "delete_explanations":
+                return afterMutation(deleteExplanations(store, params));
             case "set_diagram":
                 return afterMutation(setDiagram(store, params));
             case "delete_diagram":

package/dist/src/tools/add-explanations.d.ts

@@ -0,0 +1,9 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+export declare const EXPLANATION_INPUT_FIELDS: readonly ["id", "title", "body", "path", "side", "start_line", "end_line"];
+/**
+ * Ajoute un lot d'explications. Tout le lot est validé (champs, identifiants,
+ * emplacements résolus sur le snapshot) avant l'écriture : une seule explication
+ * invalide et rien n'est ajouté.
+ */
+export declare function addExplanations(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/add-explanations.js

@@ -0,0 +1,73 @@
+import { AnalysisError } from "../core/errors.js";
+import { itemId } from "../core/ids.js";
+import { resolveExplanationLocation } from "../core/locations.js";
+import { explanationLine } from "./format.js";
+import { readExplanationLocation, readItemId } from "./inputs.js";
+import { rejectUnknownFields, requireArray, requireObject, requireString, requireText, textResult, } from "./types.js";
+export const EXPLANATION_INPUT_FIELDS = ["id", "title", "body", "path", "side", "start_line", "end_line"];
+/**
+ * Ajoute un lot d'explications. Tout le lot est validé (champs, identifiants,
+ * emplacements résolus sur le snapshot) avant l'écriture : une seule explication
+ * invalide et rien n'est ajouté.
+ */
+export function addExplanations(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "explanations"]);
+    const id = requireString(args, "analysis_id");
+    const items = requireArray(args, "explanations", 1);
+    const analysis = store.get(id);
+    const snapshot = store.getSnapshot(id);
+    const taken = new Set(analysis.explanations.map((explanation) => explanation.id));
+    const batchIds = new Set();
+    const prepared = [];
+    const errors = [];
+    items.forEach((raw, index) => {
+        try {
+            const item = requireObject(raw, `explanations[${index}]`);
+            rejectUnknownFields(item, EXPLANATION_INPUT_FIELDS);
+            const explanationId = readItemId(item, "id");
+            if (explanationId !== undefined) {
+                if (taken.has(explanationId))
+                    throw new Error(`id "${explanationId}" is already used by another explanation of this analysis.`);
+                if (batchIds.has(explanationId))
+                    throw new Error(`id "${explanationId}" appears twice in this batch.`);
+                batchIds.add(explanationId);
+            }
+            const title = requireString(item, "title");
+            const body = requireText(item, "body");
+            const location = readExplanationLocation(item);
+            if (location === undefined) {
+                throw new Error(`an explanation describes lines of code: give "path" and "start_line" (and "side": "old" for removed code).`);
+            }
+            const { anchorText, ...resolved } = resolveExplanationLocation(snapshot, analysis.files, location);
+            prepared.push({ id: explanationId, title, body, location: resolved, anchorText });
+        }
+        catch (err) {
+            errors.push(`- explanations[${index}]: ${err.message}`);
+        }
+    });
+    if (errors.length > 0) {
+        throw new AnalysisError(`No explanation was added: ${errors.length} of ${items.length} explanation(s) are invalid. Fix them and send the whole batch again.\n` +
+            errors.join("\n"));
+    }
+    const added = [];
+    const updated = store.mutate(id, "agent", (draft) => {
+        if (draft.snapshotAt !== analysis.snapshotAt) {
+            throw new AnalysisError(`The diff of analysis "${id}" was recomputed while the explanations were validated. Send the batch again.`);
+        }
+        const ids = new Set([...draft.explanations.map((explanation) => explanation.id), ...batchIds]);
+        const now = new Date().toISOString();
+        for (const explanation of prepared) {
+            const newId = explanation.id ?? itemId("explanation", ids);
+            ids.add(newId);
+            const created = { ...explanation, id: newId, status: "current", createdAt: now };
+            added.push(created);
+            draft.explanations.push(created);
+        }
+    });
+    const lines = [
+        `Added ${added.length} explanation(s) to "${updated.title}" (${updated.id}):`,
+        ...added.map((explanation) => `  ${explanationLine(explanation)}`),
+        `The analysis has ${updated.explanations.length} explanation(s). The reviewer reads them in the diff, above the lines they describe.`,
+    ];
+    return { result: textResult(lines.join("\n")), analysisId: updated.id };
+}

package/dist/src/tools/create-analysis.js

@@ -31,6 +31,6 @@ export async function createAnalysis(store, args, repoFor = localRepo) {
     else {
         lines.push(`Changed files (${fileTotals(analysis.files)}):`, ...analysis.files.map((file) => `  ${fileLine(file)}`));
     }
-    lines.push("", "Next steps:", `1. Read the frozen diff with get_diff (analysis_id "${analysis.id}"); anchor findings on its new-side line numbers.`, "2. Write the overview (objective, approach, attention_points) and the summary (the functional changes of the feature) with update_analysis.", "3. Record problems with add_findings, including requirement_gap findings for requested behaviour that is missing.", "4. Add diagrams with set_diagram when a picture helps the reviewer: one subject each, 5 to 12 nodes, no crossing.", "5. Ask the user to review the analysis in the GUI, then read the outcome with get_review_feedback.");
+    lines.push("", "Next steps:", `1. Read the frozen diff with get_diff (analysis_id "${analysis.id}"); anchor findings on its new-side line numbers.`, "2. Write the overview (objective, approach, attention_points) and the summary (the functional changes of the feature) with update_analysis.", "3. Explain every long (about 30 lines or more) or complex block of added or removed code with add_explanations: what it does and how it works.", "4. Record problems with add_findings, including requirement_gap findings for requested behaviour that is missing.", "5. Add diagrams with set_diagram when a picture helps the reviewer: one subject each, 5 to 12 nodes, no crossing.", "6. Ask the user to review the analysis in the GUI, then read the outcome with get_review_feedback.");
     return { result: textResult(lines.join("\n")), analysisId: analysis.id };
 }

package/dist/src/tools/delete-explanations.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+/** Supprime des explications par identifiant. Un identifiant inconnu fait échouer l'appel sans rien supprimer. */
+export declare function deleteExplanations(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/delete-explanations.js

@@ -0,0 +1,23 @@
+import { AnalysisError } from "../core/errors.js";
+import { rejectUnknownFields, requireString, requireStringArray, textResult } from "./types.js";
+/** Supprime des explications par identifiant. Un identifiant inconnu fait échouer l'appel sans rien supprimer. */
+export function deleteExplanations(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "explanation_ids"]);
+    const id = requireString(args, "analysis_id");
+    const ids = [...new Set(requireStringArray(args, "explanation_ids", 1))];
+    const updated = store.mutate(id, "agent", (draft) => {
+        const known = new Set(draft.explanations.map((explanation) => explanation.id));
+        const unknown = ids.filter((explanationId) => !known.has(explanationId));
+        if (unknown.length > 0) {
+            const existing = draft.explanations.map((explanation) => explanation.id).join(", ") || "none";
+            throw new AnalysisError(`No explanation was deleted: unknown explanation id(s) ${unknown.join(", ")} in analysis "${id}". Existing explanations: ${existing}.`);
+        }
+        const removed = new Set(ids);
+        draft.explanations = draft.explanations.filter((explanation) => !removed.has(explanation.id));
+    });
+    return {
+        result: textResult(`Deleted ${ids.length} explanation(s) from "${updated.title}" (${updated.id}): ${ids.join(", ")}. ` +
+            `${updated.explanations.length} explanation(s) remain.`),
+        analysisId: updated.id,
+    };
+}

package/dist/src/tools/format.d.ts

@@ -1,4 +1,4 @@
-import { type Analysis, type FileEntry, type Finding, type Note, type Overview, type ReviewProgress, type ReviewProgressState, type Severity } from "../../shared/schemas/analysis.schema.js";
+import { type Analysis, type Explanation, type FileEntry, type Finding, type Note, type Overview, type ReviewProgress, type ReviewProgressState, type Severity } from "../../shared/schemas/analysis.schema.js";
 /** Sha abrégé à 7 caractères. */
 export declare function shortSha(sha: string | null): string;
 /** Refs d'une analyse : `branch master...HEAD` ou `working_tree (changes against HEAD)`. */
@@ -15,6 +15,8 @@ export declare function locationLabel(finding: Pick<Finding, "location">): strin
 export declare function noteLocationLabel(note: Pick<Note, "location">): string;
 /** Ligne d'un constat : id, gravité, nature, statut, emplacement, titre. */
 export declare function findingLine(finding: Finding): string;
+/** Ligne d'une explication : id, statut, emplacement avec son côté, titre. */
+export declare function explanationLine(explanation: Explanation): string;
 /** `1 critical, 2 major` ; `none` quand tous les compteurs sont à zéro. */
 export declare function severityCountsLabel(counts: Record<Severity, number>): string;
 /** Préfixe chaque ligne non vide de `indent`. */

package/dist/src/tools/format.js

@@ -52,6 +52,11 @@ export function noteLocationLabel(note) {
 export function findingLine(finding) {
     return `${finding.id} [${finding.severity}] ${finding.kind}, ${finding.status} — ${locationLabel(finding)} — ${finding.title}`;
 }
+/** Ligne d'une explication : id, statut, emplacement avec son côté, titre. */
+export function explanationLine(explanation) {
+    const { path, side, startLine, endLine } = explanation.location;
+    return `${explanation.id} ${explanation.status} — ${path}:${lineRange(startLine, endLine)} (${side} side) — ${explanation.title}`;
+}
 /** `1 critical, 2 major` ; `none` quand tous les compteurs sont à zéro. */
 export function severityCountsLabel(counts) {
     const parts = SEVERITIES.filter((severity) => counts[severity] > 0).map((severity) => `${counts[severity]} ${severity}`);

package/dist/src/tools/get-analysis.js

@@ -2,7 +2,7 @@ import { summarize } from "../core/analysis-store.js";
 import { diagramQuality } from "../../shared/diagram-quality.js";
 import { reviewProgress } from "../../shared/review-state.js";
 import { sortBySeverity } from "../../shared/severity.js";
-import { fileLine, fileTotals, findingLine, noteLocationLabel, overviewLines, progressLabel, severityCountsLabel, snapshotLabel, } from "./format.js";
+import { fileLine, explanationLine, fileTotals, findingLine, noteLocationLabel, overviewLines, progressLabel, severityCountsLabel, snapshotLabel, } from "./format.js";
 import { rejectUnknownFields, requireString, textResult } from "./types.js";
 function noteLine(note) {
     return `${note.id} — ${noteLocationLabel(note)} — ${note.text.replace(/\n/g, " / ")}`;
@@ -74,6 +74,11 @@ export function getAnalysis(store, args) {
     if (analysis.findings.length === 0)
         lines.push("  none (record them with add_findings)");
     lines.push(...sortBySeverity(analysis.findings).map((finding) => `  ${findingLine(finding)}`), "");
+    const outdatedExplanations = analysis.explanations.filter((explanation) => explanation.status === "outdated").length;
+    lines.push(`Explanations (${analysis.explanations.length}: ${outdatedExplanations} outdated):`);
+    if (analysis.explanations.length === 0)
+        lines.push("  none (explain long or complex blocks with add_explanations)");
+    lines.push(...analysis.explanations.map((explanation) => `  ${explanationLine(explanation)}`), "");
     lines.push(`Reviewer notes (${analysis.notes.length}):`);
     if (analysis.notes.length === 0)
         lines.push("  none");

package/dist/src/tools/get-diff.js

@@ -52,7 +52,8 @@ export function getDiff(store, args) {
     const lines = [
         `Frozen diff of "${analysis.title}" (${analysis.id}): ${snapshotLabel(analysis)}.`,
         "Columns: old line | new line, then + (added), - (removed) or a space (context). " +
-            "Anchor findings on the NEW-side numbers (second column).",
+            "Anchor findings and explanations of added code on the NEW-side numbers (second column); " +
+            'explanations of removed code use the OLD-side numbers (first column) with "side": "old".',
     ];
     if (entries.length === 0)
         lines.push("", "The analysis has no changed files.");

package/dist/src/tools/inputs.d.ts

@@ -1,3 +1,4 @@
+import { type ExplanationSide } from "../../shared/schemas/analysis.schema.js";
 import { type Args } from "./types.js";
 /** Emplacement demandé par l'agent : `null` pour retirer l'emplacement, `undefined` s'il n'en donne pas. */
 export type LocationInput = {
@@ -10,5 +11,18 @@ export type LocationInput = {
  * `end_line` vaut `start_line` quand il est omis. `path: null` retire l'emplacement.
  */
 export declare function readLocation(args: Args, prefix?: string): LocationInput;
+/** Emplacement d'une explication demandé par l'agent ; `undefined` s'il n'en donne pas. */
+export type ExplanationLocationInput = {
+    path: string;
+    side: ExplanationSide;
+    startLine: number;
+    endLine: number | undefined;
+} | undefined;
+/**
+ * Lit `path`, `side`, `start_line` et `end_line` d'une explication. `path` et
+ * `start_line` vont ensemble ; `side` vaut `new` quand il est omis ; `end_line`
+ * vaut `start_line` quand il est omis. Une explication a toujours un emplacement.
+ */
+export declare function readExplanationLocation(args: Args, prefix?: string): ExplanationLocationInput;
 /** Lit un identifiant d'élément facultatif fourni par l'agent. */
 export declare function readItemId(args: Args, field: string, prefix?: string): string | undefined;

package/dist/src/tools/inputs.js

@@ -1,5 +1,5 @@
-import { ITEM_ID_PATTERN } from "../../shared/schemas/analysis.schema.js";
-import { has, nullableString, optionalPositiveInt } from "./types.js";
+import { EXPLANATION_SIDES, ITEM_ID_PATTERN } from "../../shared/schemas/analysis.schema.js";
+import { has, nullableString, optionalEnum, optionalPositiveInt } from "./types.js";
 /**
  * Lit `path`, `start_line` et `end_line`. `path` et `start_line` vont ensemble ;
  * `end_line` vaut `start_line` quand il est omis. `path: null` retire l'emplacement.
@@ -28,6 +28,24 @@ export function readLocation(args, prefix = "") {
     }
     return { path, startLine, endLine };
 }
+/**
+ * Lit `path`, `side`, `start_line` et `end_line` d'une explication. `path` et
+ * `start_line` vont ensemble ; `side` vaut `new` quand il est omis ; `end_line`
+ * vaut `start_line` quand il est omis. Une explication a toujours un emplacement.
+ */
+export function readExplanationLocation(args, prefix = "") {
+    const side = optionalEnum(args, "side", EXPLANATION_SIDES, prefix);
+    const location = readLocation(args, prefix);
+    if (location === null) {
+        throw new Error(`"${prefix}path" cannot be null: an explanation always describes lines of a changed file.`);
+    }
+    if (location === undefined) {
+        if (side !== undefined)
+            throw new Error(`"${prefix}side" needs "${prefix}path" and "${prefix}start_line": give the lines it refers to.`);
+        return undefined;
+    }
+    return { ...location, side: side ?? "new" };
+}
 /** Lit un identifiant d'élément facultatif fourni par l'agent. */
 export function readItemId(args, field, prefix = "") {
     if (!has(args, field))

package/dist/src/tools/refresh-analysis.js

@@ -1,5 +1,5 @@
 import { computeSnapshot, localRepo } from "../core/git.js";
-import { snapshotLabel } from "./format.js";
+import { explanationLine, snapshotLabel } from "./format.js";
 import { rejectUnknownFields, requireString, textResult } from "./types.js";
 /**
  * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse, lus par
@@ -19,6 +19,8 @@ export async function refreshAnalysis(store, args, repoFor = localRepo) {
         `Reviewed files: ${stats.reviewedKept} kept (diff unchanged), ${stats.reviewedReset} reset to unreviewed (diff changed).`,
         `Findings: ${stats.findingsOutdated} became outdated (their lines changed or left the diff), ` +
             `${stats.findingsRestored} back to open (their lines match again); ${outdated.length} outdated in total.`,
+        `Explanations: ${stats.explanationsOutdated} became outdated (the code they describe changed or left the diff), ` +
+            `${stats.explanationsRestored} current again.`,
     ];
     if (previousReview.state === "submitted") {
         lines.push(`Review: the previous feedback (decision ${previousReview.decision}, submitted at ${previousReview.submittedAt}) was discarded; the review is pending again.`);
@@ -26,9 +28,13 @@ export async function refreshAnalysis(store, args, repoFor = localRepo) {
     else {
         lines.push("Review: pending; the previous feedback, decision and selection in progress were discarded.");
     }
-    lines.push("", "Next steps:", "- Re-read the changed files with get_diff.", "- For each outdated finding: re-anchor it with update_finding (a new location reopens it), or remove it with delete_findings if it is solved.", "- Ask the user to review the analysis again in the GUI.");
+    lines.push("", "Next steps:", "- Re-read the changed files with get_diff.", "- For each outdated finding: re-anchor it with update_finding (a new location reopens it), or remove it with delete_findings if it is solved.", "- For each outdated explanation: re-anchor it and rewrite its body with update_explanation, or remove it with delete_explanations.", "- Explain the new long or complex blocks with add_explanations.", "- Ask the user to review the analysis again in the GUI.");
     if (outdated.length > 0) {
         lines.push("", "Outdated findings:", ...outdated.map((finding) => `  ${finding.id} [${finding.severity}] ${finding.title}`));
     }
+    const outdatedExplanations = analysis.explanations.filter((explanation) => explanation.status === "outdated");
+    if (outdatedExplanations.length > 0) {
+        lines.push("", "Outdated explanations:", ...outdatedExplanations.map((explanation) => `  ${explanationLine(explanation)}`));
+    }
     return { result: textResult(lines.join("\n")), analysisId: analysis.id };
 }

package/dist/src/tools/update-explanation.d.ts

@@ -0,0 +1,7 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+/**
+ * Modifie une explication. Un nouvel emplacement est résolu sur le snapshot et
+ * remet une explication `outdated` à `current`.
+ */
+export declare function updateExplanation(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/update-explanation.js

@@ -0,0 +1,57 @@
+import { AnalysisError } from "../core/errors.js";
+import { resolveExplanationLocation } from "../core/locations.js";
+import { explanationLine } from "./format.js";
+import { readExplanationLocation } from "./inputs.js";
+import { has, optionalString, rejectUnknownFields, requireString, requireText, textResult } from "./types.js";
+const EDITABLE = ["title", "body", "path", "side", "start_line", "end_line"];
+/**
+ * Modifie une explication. Un nouvel emplacement est résolu sur le snapshot et
+ * remet une explication `outdated` à `current`.
+ */
+export function updateExplanation(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "explanation_id", ...EDITABLE]);
+    const id = requireString(args, "analysis_id");
+    const explanationId = requireString(args, "explanation_id");
+    const given = EDITABLE.filter((field) => has(args, field));
+    if (given.length === 0) {
+        throw new Error(`Give at least one field to change: ${EDITABLE.join(", ")}.`);
+    }
+    const title = optionalString(args, "title");
+    const body = has(args, "body") ? requireText(args, "body") : undefined;
+    const location = readExplanationLocation(args);
+    const analysis = store.get(id);
+    const current = analysis.explanations.find((explanation) => explanation.id === explanationId);
+    if (!current) {
+        const known = analysis.explanations.map((explanation) => explanation.id).join(", ") || "none";
+        throw new AnalysisError(`Explanation "${explanationId}" not found in analysis "${id}". Existing explanations: ${known}.`);
+    }
+    const resolved = location === undefined ? undefined : resolveExplanationLocation(store.getSnapshot(id), analysis.files, location);
+    const previousStatus = current.status;
+    const updated = store.mutate(id, "agent", (draft) => {
+        if (draft.snapshotAt !== analysis.snapshotAt) {
+            throw new AnalysisError(`The diff of analysis "${id}" was recomputed while the explanation was validated. Send the update again.`);
+        }
+        const explanation = draft.explanations.find((entry) => entry.id === explanationId);
+        if (!explanation)
+            throw new AnalysisError(`Explanation "${explanationId}" was deleted in the meantime from analysis "${id}".`);
+        if (title !== undefined)
+            explanation.title = title;
+        if (body !== undefined)
+            explanation.body = body;
+        if (resolved) {
+            const { anchorText, ...newLocation } = resolved;
+            explanation.location = newLocation;
+            explanation.anchorText = anchorText;
+            explanation.status = "current";
+        }
+    });
+    const explanation = updated.explanations.find((entry) => entry.id === explanationId);
+    const lines = [`Updated explanation ${explanationId} (${given.join(", ")}):`, `  ${explanationLine(explanation)}`];
+    if (previousStatus === "outdated" && explanation.status === "current") {
+        lines.push("It was outdated; the new location made it current again.");
+    }
+    else if (explanation.status === "outdated") {
+        lines.push("It is still outdated: re-read the code with get_diff, then give its new location (path, side, start_line) and rewrite the body if the code changed, or delete it with delete_explanations.");
+    }
+    return { result: textResult(lines.join("\n")), analysisId: updated.id };
+}

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.3";
+export declare const APP_VERSION = "1.0.4";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.3';
+export const APP_VERSION = '1.0.4';