@imenam/mcp-feature-analyzer 1.0.2 → 1.0.4

package/dist/src/index.js

@@ -12,11 +12,14 @@ import { resolveDataDir } from "./core/data-dir.js";
 import { resolveLogDir } from "./core/log-dir.js";
 import { AnalysisStore } from "./core/analysis-store.js";
 import { AnalysisError, NotFoundError, RevisionConflictError } from "./core/errors.js";
-import { DEFAULT_HEAD_REF } from "./core/git.js";
-import { addNote, deleteNote, setFileReviewed, setFindingStatus, submitReview } from "./core/review-actions.js";
+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, 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";
@@ -27,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";
@@ -66,6 +72,15 @@ function getConfig() {
     return { proxyUrl: process.env.PROXY_URL, appPort: process.env.APP_PORT, version: APP_VERSION };
 }
 getConfig();
+let role;
+try {
+    role = resolveRole();
+}
+catch (err) {
+    logger.error(err.message);
+    console.error(err.message);
+    process.exit(1);
+}
 const dataDir = resolveDataDir(rootDir);
 const store = new AnalysisStore(dataDir);
 /** Présentation du serveur transmise au client MCP : concepts, déroulé et règles. */
@@ -76,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.
 
@@ -83,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.
@@ -96,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 });
@@ -180,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);
@@ -293,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.`;
@@ -334,7 +376,12 @@ const TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
-                repo_path: { type: "string", description: "Absolute path of the root of the git repository." },
+                repo_path: {
+                    type: "string",
+                    description: role === "remote"
+                        ? "Absolute path of the root of the git repository on your machine: git runs there, through the agent relay of mcp-http-gateway."
+                        : "Absolute path of the root of the git repository.",
+                },
                 project: { type: "string", description: PROJECT_DOC },
                 title: { type: "string", description: "Short title of the feature, e.g. \"OAuth token refresh\"." },
                 mode: {
@@ -486,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). " +
@@ -592,9 +694,20 @@ function afterMutation({ result, analysisId }) {
     notifyAnalysisChanged(analysisId);
     return { ...result, content: [{ type: "text", text: result.content[0].text + guiHint(analysisId) }] };
 }
+/**
+ * Donne à `fn` l'accès aux dépôts du rôle : git local en `standalone` ; en `remote`,
+ * commandes exécutées sur la machine de l'agent par le relais, qui annonce cette
+ * possibilité dans l'argument `exec`.
+ */
+function withRepoAccess(exec, fn) {
+    if (role === "standalone")
+        return fn(localRepo);
+    return handleAgentExec(exec, (run) => fn((repoPath) => agentRepo(repoPath, run)));
+}
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    const params = (args ?? {});
+    // L'argument réservé du relais agent accompagne tous les appels d'une route listée dans GATEWAY_EXEC_ROUTES.
+    const { [EXEC_ARG]: exec, ...params } = (args ?? {});
     try {
         switch (name) {
             case "list_analyses":
@@ -605,11 +718,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return getDiff(store, params);
             case "get_review_feedback":
                 return getReviewFeedback(store, params);
-            case "create_analysis": {
-                const mutation = await createAnalysis(store, params);
-                notifyAnalysesListChanged();
-                return afterMutation(mutation);
-            }
+            case "create_analysis":
+                return await withRepoAccess(exec, async (repoFor) => {
+                    const mutation = await createAnalysis(store, params, repoFor);
+                    notifyAnalysesListChanged();
+                    return afterMutation(mutation);
+                });
             case "update_analysis":
                 return afterMutation(updateAnalysis(store, params));
             case "add_findings":
@@ -618,12 +732,18 @@ 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":
                 return afterMutation(deleteDiagram(store, params));
             case "refresh_analysis":
-                return afterMutation(await refreshAnalysis(store, params));
+                return await withRepoAccess(exec, async (repoFor) => afterMutation(await refreshAnalysis(store, params, repoFor)));
             case "delete_analysis": {
                 const { result, analysisId } = deleteAnalysis(store, params);
                 notifyAnalysisChanged(analysisId);
@@ -643,7 +763,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info(`MCP Server connected and running on stdio (data dir: ${dataDir})`);
+    logger.info(`MCP Server connected and running on stdio (role: ${role}, data dir: ${dataDir})`);
     launchGUI();
 }
 main().catch((err) => {

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.d.ts

@@ -1,4 +1,5 @@
 import type { AnalysisStore } from "../core/analysis-store.js";
+import { type RepoAccess } from "../core/git.js";
 import { type Args, type MutationResult } from "./types.js";
-/** Calcule et fige le diff du dépôt, puis crée l'analyse. */
-export declare function createAnalysis(store: AnalysisStore, args: Args): Promise<MutationResult>;
+/** Calcule et fige le diff du dépôt, lu par `repoFor(repo_path)` (git local par défaut), puis crée l'analyse. */
+export declare function createAnalysis(store: AnalysisStore, args: Args, repoFor?: (repoPath: string) => RepoAccess): Promise<MutationResult>;

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

@@ -1,10 +1,10 @@
-import { computeSnapshot } from "../core/git.js";
+import { computeSnapshot, localRepo } from "../core/git.js";
 import { ANALYSIS_MODES } from "../../shared/schemas/analysis.schema.js";
 import { fileLine, fileTotals, snapshotLabel } from "./format.js";
 import { optionalString, rejectUnknownFields, requireEnum, requireString, textResult, } from "./types.js";
 const FIELDS = ["repo_path", "project", "title", "mode", "base", "head", "request_text", "request_source"];
-/** Calcule et fige le diff du dépôt, puis crée l'analyse. */
-export async function createAnalysis(store, args) {
+/** Calcule et fige le diff du dépôt, lu par `repoFor(repo_path)` (git local par défaut), puis crée l'analyse. */
+export async function createAnalysis(store, args, repoFor = localRepo) {
     rejectUnknownFields(args, FIELDS);
     const repoPath = requireString(args, "repo_path");
     const project = requireString(args, "project");
@@ -17,7 +17,7 @@ export async function createAnalysis(store, args) {
     if (requestSource !== undefined && requestText === undefined) {
         throw new Error(`"request_source" describes the initial request: give "request_text" too.`);
     }
-    const computed = await computeSnapshot({ repoPath, mode, base, head });
+    const computed = await computeSnapshot({ repoPath, mode, base, head }, repoFor(repoPath));
     const analysis = store.create({ project, title, request: requestText === undefined ? null : { text: requestText, source: requestSource ?? null } }, computed);
     const lines = [
         `Created analysis "${analysis.title}" (id: ${analysis.id}) in project "${analysis.project}".`,
@@ -31,6 +31,6 @@ export async function createAnalysis(store, args) {
     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.d.ts

@@ -1,7 +1,8 @@
 import type { AnalysisStore } from "../core/analysis-store.js";
+import { type RepoAccess } from "../core/git.js";
 import { type Args, type MutationResult } from "./types.js";
 /**
- * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse ; la
- * revue repart à l'état `pending` sans décision, sélection ni prompt.
+ * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse, lus par
+ * `repoFor` (git local par défaut) ; la revue repart à l'état `pending` sans décision, sélection ni prompt.
  */
-export declare function refreshAnalysis(store: AnalysisStore, args: Args): Promise<MutationResult>;
+export declare function refreshAnalysis(store: AnalysisStore, args: Args, repoFor?: (repoPath: string) => RepoAccess): Promise<MutationResult>;

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

@@ -1,20 +1,15 @@
-import { computeSnapshot } from "../core/git.js";
-import { snapshotLabel } from "./format.js";
+import { computeSnapshot, localRepo } from "../core/git.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 ; la
- * revue repart à l'état `pending` sans décision, sélection ni prompt.
+ * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse, lus par
+ * `repoFor` (git local par défaut) ; la revue repart à l'état `pending` sans décision, sélection ni prompt.
  */
-export async function refreshAnalysis(store, args) {
+export async function refreshAnalysis(store, args, repoFor = localRepo) {
     rejectUnknownFields(args, ["analysis_id"]);
     const id = requireString(args, "analysis_id");
     const current = store.get(id);
-    const computed = await computeSnapshot({
-        repoPath: current.repoPath,
-        mode: current.mode,
-        base: current.base,
-        head: current.head,
-    });
+    const computed = await computeSnapshot({ repoPath: current.repoPath, mode: current.mode, base: current.base, head: current.head }, repoFor(current.repoPath));
     const { analysis, stats, previousReview } = store.replaceSnapshot(id, "agent", computed);
     const outdated = analysis.findings.filter((finding) => finding.status === "outdated");
     const lines = [
@@ -24,6 +19,8 @@ export async function refreshAnalysis(store, args) {
         `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.`);
@@ -31,9 +28,13 @@ export async function refreshAnalysis(store, args) {
     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;