@imenam/mcp-feature-analyzer 1.0.2 → 1.0.4

package/dist/src/core/git.js

@@ -57,9 +57,7 @@ async function assertRepoRoot(repoPath) {
 }
 /** Résout une ref en sha de commit ; erreur explicite si elle est inconnue. */
 async function resolveCommit(repoPath, ref, role) {
-    if (ref.startsWith("-")) {
-        throw new GitError(`Invalid ${role} ref "${ref}": a ref cannot start with "-".`);
-    }
+    assertRefShape(ref, role);
     try {
         return (await runGit(repoPath, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], "utf-8")).trim();
     }
@@ -67,7 +65,7 @@ async function resolveCommit(repoPath, ref, role) {
         throw new GitError(`Unknown ${role} ref "${ref}" in ${repoPath}. Use a branch name, a tag or a commit sha that exists in this repository.`);
     }
 }
-const DIFF_ARGS = [
+export const DIFF_ARGS = [
     "-c",
     "diff.noprefix=false",
     "-c",
@@ -82,7 +80,7 @@ const DIFF_ARGS = [
     "--dst-prefix=b/",
 ];
 /** Vrai si le contenu contient un octet nul dans ses 8000 premiers octets (même règle que git). */
-function looksBinary(content) {
+export function looksBinary(content) {
     return content.subarray(0, 8000).includes(0);
 }
 /** Hunk unique d'un fichier ajouté, toutes lignes en ajout. */
@@ -108,9 +106,9 @@ function readWorkingFile(repoPath, filePath) {
         return Buffer.from(toPosixPath(fs.readlinkSync(absolute)), "utf-8");
     return fs.readFileSync(absolute);
 }
-/** Texte conservé dans le snapshot, ou null quand le contenu dépasse MAX_SNAPSHOT_FILE_BYTES. */
+/** Texte conservé dans le snapshot, ou null quand le contenu est absent ou dépasse MAX_SNAPSHOT_FILE_BYTES. */
 function snapshotText(content) {
-    if (content.length > MAX_SNAPSHOT_FILE_BYTES)
+    if (content == null || content.length > MAX_SNAPSHOT_FILE_BYTES)
         return null;
     return content.toString("utf-8");
 }
@@ -172,33 +170,49 @@ async function readCommitFiles(repoPath, commit, paths) {
     });
     return contents;
 }
-async function branchSnapshot(repoPath, base, head) {
-    const baseCommit = await resolveCommit(repoPath, base, "base");
-    const headCommit = await resolveCommit(repoPath, head, "head");
-    const output = await runGit(repoPath, [...DIFF_ARGS, `${baseCommit}...${headCommit}`, "--"], "utf-8");
+/** Accès direct au dépôt, sur la machine de ce serveur. */
+export function localRepo(repoPath) {
+    return {
+        assertRepoRoot: () => assertRepoRoot(repoPath),
+        resolveCommit: (ref, role) => resolveCommit(repoPath, ref, role),
+        diff: (range) => runGit(repoPath, [...DIFF_ARGS, ...range, "--"], "utf-8"),
+        readCommitFiles: (commit, paths) => readCommitFiles(repoPath, commit, paths),
+        untrackedFiles: async () => (await runGit(repoPath, ["ls-files", "--others", "--exclude-standard", "-z"], "utf-8"))
+            .split("\0")
+            .filter((entry) => entry !== "")
+            .map(toPosixPath),
+        readWorkingFiles: async (paths) => new Map(paths.map((filePath) => [filePath, readWorkingFile(repoPath, filePath)])),
+    };
+}
+/** Vérifie une ref fournie par l'agent avant de la passer à git. */
+export function assertRefShape(ref, role) {
+    if (ref.startsWith("-")) {
+        throw new GitError(`Invalid ${role} ref "${ref}": a ref cannot start with "-".`);
+    }
+}
+async function branchSnapshot(repo, base, head) {
+    const baseCommit = await repo.resolveCommit(base, "base");
+    const headCommit = await repo.resolveCommit(head, "head");
+    const output = await repo.diff([`${baseCommit}...${headCommit}`]);
     const parsedFiles = parseUnifiedDiff(output);
     const withContent = parsedFiles.filter((parsed) => parsed.status !== "deleted" && !parsed.binary).map((parsed) => parsed.path);
-    const contents = await readCommitFiles(repoPath, headCommit, withContent);
-    const results = parsedFiles.map((parsed) => {
-        const content = contents.get(parsed.path);
-        return toEntry(parsed, content === undefined ? null : snapshotText(content));
-    });
+    const contents = await repo.readCommitFiles(headCommit, withContent);
+    const results = parsedFiles.map((parsed) => toEntry(parsed, snapshotText(contents.get(parsed.path))));
     return { baseCommit, headCommit, results };
 }
-async function workingTreeSnapshot(repoPath) {
-    const baseCommit = await resolveCommit(repoPath, "HEAD", "base");
-    const output = await runGit(repoPath, [...DIFF_ARGS, "HEAD", "--"], "utf-8");
-    const results = [];
-    for (const parsed of parseUnifiedDiff(output)) {
-        const content = parsed.status !== "deleted" && !parsed.binary ? snapshotText(readWorkingFile(repoPath, parsed.path)) : null;
-        results.push(toEntry(parsed, content));
-    }
-    const untracked = (await runGit(repoPath, ["ls-files", "--others", "--exclude-standard", "-z"], "utf-8"))
-        .split("\0")
-        .filter((entry) => entry !== "")
-        .map(toPosixPath);
+async function workingTreeSnapshot(repo) {
+    const baseCommit = await repo.resolveCommit("HEAD", "base");
+    const parsedFiles = parseUnifiedDiff(await repo.diff(["HEAD"]));
+    const withContent = parsedFiles.filter((parsed) => parsed.status !== "deleted" && !parsed.binary).map((parsed) => parsed.path);
+    const contents = await repo.readWorkingFiles(withContent);
+    const results = parsedFiles.map((parsed) => toEntry(parsed, snapshotText(contents.get(parsed.path))));
+    const untracked = await repo.untrackedFiles();
+    const untrackedContents = await repo.readWorkingFiles(untracked);
     for (const filePath of untracked) {
-        const raw = readWorkingFile(repoPath, filePath);
+        const raw = untrackedContents.get(filePath);
+        if (raw == null) {
+            throw new GitError(`The untracked file "${filePath}" is too large to be transferred from the repository's machine. Add it to .gitignore or remove it, then try again.`);
+        }
         const binary = looksBinary(raw);
         const content = binary ? null : snapshotText(raw);
         const lines = binary ? [] : splitLines(raw.toString("utf-8"));
@@ -208,15 +222,15 @@ async function workingTreeSnapshot(repoPath) {
     return { baseCommit, headCommit: null, results };
 }
 /**
- * Calcule le snapshot d'une analyse avec git.
+ * Calcule le snapshot d'une analyse avec git, par `repo` (accès local par défaut).
  * - `branch` : diff `base...head` (head vaut `HEAD` par défaut), contenu lu dans le commit de tête ;
  * - `working_tree` : diff de HEAD vers la copie de travail, index compris, fichiers non suivis
  *   présentés comme ajoutés, contenu lu sur disque.
  * Les fichiers sont triés par chemin ; `reviewed` vaut false partout.
  */
-export async function computeSnapshot(request) {
+export async function computeSnapshot(request, repo = localRepo(request.repoPath)) {
     const { repoPath, mode } = request;
-    await assertRepoRoot(repoPath);
+    await repo.assertRepoRoot();
     let base;
     let head;
     let computed;
@@ -226,7 +240,7 @@ export async function computeSnapshot(request) {
             throw new GitError(`"base" is required in branch mode: give the ref the feature branched from.`);
         base = requestedBase;
         head = request.head?.trim() || DEFAULT_HEAD_REF;
-        computed = await branchSnapshot(repoPath, base, head);
+        computed = await branchSnapshot(repo, base, head);
     }
     else if (mode === "working_tree") {
         if (request.head != null && request.head.trim() !== "") {
@@ -237,7 +251,7 @@ export async function computeSnapshot(request) {
         }
         base = "HEAD";
         head = null;
-        computed = await workingTreeSnapshot(repoPath);
+        computed = await workingTreeSnapshot(repo);
     }
     else {
         throw new GitError(`Unknown mode "${String(mode)}": use "branch" or "working_tree".`);

package/dist/src/core/ids.d.ts

@@ -7,6 +7,7 @@ export declare function analysisId(title: string): string;
 /** Préfixe des identifiants générés, par type d'élément. */
 export declare const ITEM_ID_PREFIXES: {
     readonly finding: "f";
+    readonly explanation: "x";
     readonly note: "n";
     readonly diagram: "d";
     readonly node: "nd";

package/dist/src/core/ids.js

@@ -27,6 +27,7 @@ export function analysisId(title) {
 /** Préfixe des identifiants générés, par type d'élément. */
 export const ITEM_ID_PREFIXES = {
     finding: "f",
+    explanation: "x",
     note: "n",
     diagram: "d",
     node: "nd",

package/dist/src/core/invariants.d.ts

@@ -3,12 +3,14 @@ import type { Analysis } from "../../shared/schemas/analysis.schema.js";
  * Liste les violations des règles de cohérence d'une analyse :
  * - refs cohérentes avec le mode : `branch` a une ref et un commit de tête ; `working_tree`
  *   compare à HEAD, sans ref ni commit de tête ;
- * - identifiants uniques (fichiers, constats, remarques, schémas, nœuds d'un schéma) ;
+ * - identifiants uniques (fichiers, constats, explications, remarques, schémas, nœuds d'un schéma) ;
  * - un constat `issue` a un emplacement, un `requirement_gap` peut ne pas en avoir ;
  * - un emplacement de constat porte un `anchorText` ; sans emplacement, ni `anchorText` ni `suggestion` ;
  * - un constat `open` vise un fichier de l'analyse dont le contenu est disponible, avec
  *   1 ≤ startLine ≤ endLine ≤ nombre de lignes ; un constat `ignored` ou `outdated` garde
  *   l'emplacement qu'il avait, même si le snapshot a changé depuis ;
+ * - une explication `current` vise un fichier de l'analyse ; côté `new`, son contenu est
+ *   disponible et endLine ≤ nombre de lignes ;
  * - les liens d'un schéma relient des nœuds existants ; en `layers`, chaque nœud a une couche
  *   déclarée dans `layers`, sans doublon ;
  * - la revue ne sélectionne que des constats et remarques existants, et son état est cohérent.

package/dist/src/core/invariants.js

@@ -14,12 +14,14 @@ function duplicates(ids) {
  * Liste les violations des règles de cohérence d'une analyse :
  * - refs cohérentes avec le mode : `branch` a une ref et un commit de tête ; `working_tree`
  *   compare à HEAD, sans ref ni commit de tête ;
- * - identifiants uniques (fichiers, constats, remarques, schémas, nœuds d'un schéma) ;
+ * - identifiants uniques (fichiers, constats, explications, remarques, schémas, nœuds d'un schéma) ;
  * - un constat `issue` a un emplacement, un `requirement_gap` peut ne pas en avoir ;
  * - un emplacement de constat porte un `anchorText` ; sans emplacement, ni `anchorText` ni `suggestion` ;
  * - un constat `open` vise un fichier de l'analyse dont le contenu est disponible, avec
  *   1 ≤ startLine ≤ endLine ≤ nombre de lignes ; un constat `ignored` ou `outdated` garde
  *   l'emplacement qu'il avait, même si le snapshot a changé depuis ;
+ * - une explication `current` vise un fichier de l'analyse ; côté `new`, son contenu est
+ *   disponible et endLine ≤ nombre de lignes ;
  * - les liens d'un schéma relient des nœuds existants ; en `layers`, chaque nœud a une couche
  *   déclarée dans `layers`, sans doublon ;
  * - la revue ne sélectionne que des constats et remarques existants, et son état est cohérent.
@@ -36,6 +38,7 @@ export function findInvariantViolations(analysis) {
     for (const [label, ids] of [
         ["file path", analysis.files.map((file) => file.path)],
         ["finding id", analysis.findings.map((finding) => finding.id)],
+        ["explanation id", analysis.explanations.map((explanation) => explanation.id)],
         ["note id", analysis.notes.map((note) => note.id)],
         ["diagram id", analysis.diagrams.map((diagram) => diagram.id)],
     ]) {
@@ -75,6 +78,29 @@ export function findInvariantViolations(analysis) {
                 `which has ${file.lineCount} line(s)`);
         }
     }
+    for (const explanation of analysis.explanations) {
+        const where = `explanation "${explanation.id}"`;
+        const location = explanation.location;
+        if (location.startLine > location.endLine) {
+            problems.push(`${where} has startLine ${location.startLine} after endLine ${location.endLine}`);
+        }
+        if (explanation.status !== "current")
+            continue;
+        const file = files.get(location.path);
+        if (!file) {
+            problems.push(`${where} describes "${location.path}", which is not a changed file of this analysis`);
+            continue;
+        }
+        if (location.side !== "new")
+            continue;
+        if (!file.contentAvailable) {
+            problems.push(`${where} describes new-side lines of "${location.path}", whose content is not available`);
+        }
+        else if (location.endLine > file.lineCount) {
+            problems.push(`${where} describes lines ${location.startLine}-${location.endLine} of "${location.path}", ` +
+                `which has ${file.lineCount} line(s)`);
+        }
+    }
     for (const diagram of analysis.diagrams) {
         const where = `diagram "${diagram.id}"`;
         const nodeIds = new Set(diagram.nodes.map((node) => node.id));

package/dist/src/core/locations.d.ts

@@ -1,5 +1,5 @@
-import type { FileEntry } from "../../shared/schemas/analysis.schema.js";
-import type { DiffSnapshot } from "../../shared/schemas/diff.schema.js";
+import type { ExplanationLocation, ExplanationSide, FileEntry } from "../../shared/schemas/analysis.schema.js";
+import type { DiffSnapshot, FileDiff } from "../../shared/schemas/diff.schema.js";
 export interface LocationRequest {
     path: string;
     startLine: number;
@@ -17,9 +17,27 @@ export interface ResolvedLocation {
  * Vérifie un emplacement (lignes du côté « nouveau ») contre le snapshot et
  * renvoie le texte des lignes visées. Erreur explicite si le fichier n'est pas
  * dans l'analyse, si son contenu n'est pas disponible ou si les lignes sortent
- * du fichier.
+ * du fichier ; `unavailableHint` complète le message d'un contenu indisponible.
  */
-export declare function resolveLocation(snapshot: DiffSnapshot, files: FileEntry[], request: LocationRequest): ResolvedLocation;
+export declare function resolveLocation(snapshot: DiffSnapshot, files: FileEntry[], request: LocationRequest, unavailableHint?: string): ResolvedLocation;
+/**
+ * Texte actuel des lignes décrites par une explication, ou null quand elles ne
+ * sont plus lisibles : côté `new`, dans le contenu conservé du fichier ; côté
+ * `old`, dans les lignes du côté « ancien » que montre le diff.
+ */
+export declare function explanationText(diff: FileDiff | undefined, location: ExplanationLocation): string | null;
+export interface ExplanationLocationRequest extends LocationRequest {
+    side: ExplanationSide;
+}
+/**
+ * Vérifie l'emplacement d'une explication et renvoie le texte des lignes décrites.
+ * - côté `new` : mêmes règles qu'un constat ;
+ * - côté `old` : toutes les lignes doivent figurer dans le diff (numéros de la
+ *   première colonne de get_diff), et au moins une doit être supprimée.
+ */
+export declare function resolveExplanationLocation(snapshot: DiffSnapshot, files: FileEntry[], request: ExplanationLocationRequest): ExplanationLocation & {
+    anchorText: string;
+};
 /**
  * Vérifie l'emplacement d'une remarque : un fichier de l'analyse, et une ligne
  * du côté « nouveau » quand `line` est fournie.

package/dist/src/core/locations.js

@@ -14,13 +14,15 @@ function unavailableReason(file) {
         return "it is binary";
     return "it is larger than the snapshot size limit";
 }
+/** Indication donnée à un constat dont le fichier n'a pas de contenu conservé. */
+const FINDING_UNAVAILABLE_HINT = "Anchor the point on lines of another changed file, or omit the location (allowed for requirement_gap findings).";
 /**
  * Vérifie un emplacement (lignes du côté « nouveau ») contre le snapshot et
  * renvoie le texte des lignes visées. Erreur explicite si le fichier n'est pas
  * dans l'analyse, si son contenu n'est pas disponible ou si les lignes sortent
- * du fichier.
+ * du fichier ; `unavailableHint` complète le message d'un contenu indisponible.
  */
-export function resolveLocation(snapshot, files, request) {
+export function resolveLocation(snapshot, files, request, unavailableHint = FINDING_UNAVAILABLE_HINT) {
     const endLine = request.endLine ?? request.startLine;
     const { path, startLine } = request;
     const file = files.find((entry) => entry.path === path);
@@ -32,8 +34,7 @@ export function resolveLocation(snapshot, files, request) {
     }
     const diff = snapshot.files.find((entry) => entry.path === path);
     if (!file.contentAvailable || !diff || diff.newContent === null) {
-        throw new AnalysisError(`Cannot anchor on lines of "${path}": its content is not available because ${unavailableReason(file)}. ` +
-            `Anchor the point on lines of another changed file, or omit the location (allowed for requirement_gap findings).`);
+        throw new AnalysisError(`Cannot anchor on lines of "${path}": its content is not available because ${unavailableReason(file)}. ${unavailableHint}`);
     }
     const lines = splitLines(diff.newContent);
     if (endLine > lines.length) {
@@ -42,6 +43,89 @@ export function resolveLocation(snapshot, files, request) {
     }
     return { path, startLine, endLine, anchorText: lines.slice(startLine - 1, endLine).join("\n") };
 }
+/** Texte des lignes du côté « ancien » que montre le diff (lignes supprimées et contexte), par numéro. */
+function oldSideLines(diff) {
+    const lines = new Map();
+    for (const hunk of diff.hunks) {
+        for (const line of hunk.lines) {
+            if (line.oldNo !== null)
+                lines.set(line.oldNo, { text: line.text, removed: line.type === "del" });
+        }
+    }
+    return lines;
+}
+/**
+ * Texte actuel des lignes décrites par une explication, ou null quand elles ne
+ * sont plus lisibles : côté `new`, dans le contenu conservé du fichier ; côté
+ * `old`, dans les lignes du côté « ancien » que montre le diff.
+ */
+export function explanationText(diff, location) {
+    if (!diff || location.startLine > location.endLine)
+        return null;
+    if (location.side === "new") {
+        if (diff.newContent === null)
+            return null;
+        const lines = splitLines(diff.newContent);
+        if (location.startLine < 1 || location.endLine > lines.length)
+            return null;
+        return lines.slice(location.startLine - 1, location.endLine).join("\n");
+    }
+    const old = oldSideLines(diff);
+    const texts = [];
+    for (let line = location.startLine; line <= location.endLine; line++) {
+        const entry = old.get(line);
+        if (!entry)
+            return null;
+        texts.push(entry.text);
+    }
+    return texts.join("\n");
+}
+/**
+ * Vérifie l'emplacement d'une explication et renvoie le texte des lignes décrites.
+ * - côté `new` : mêmes règles qu'un constat ;
+ * - côté `old` : toutes les lignes doivent figurer dans le diff (numéros de la
+ *   première colonne de get_diff), et au moins une doit être supprimée.
+ */
+export function resolveExplanationLocation(snapshot, files, request) {
+    if (request.side === "new") {
+        const resolved = resolveLocation(snapshot, files, request, `Explain its removed lines on the old side ("side": "old"), or explain lines of another changed file.`);
+        return { path: resolved.path, side: "new", startLine: resolved.startLine, endLine: resolved.endLine, anchorText: resolved.anchorText };
+    }
+    const endLine = request.endLine ?? request.startLine;
+    const { path, startLine } = request;
+    if (!files.some((entry) => entry.path === path)) {
+        throw new AnalysisError(`File "${path}" is not part of this analysis (${describeFiles(files)}).`);
+    }
+    if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine) {
+        throw new AnalysisError(`Invalid line range ${startLine}-${endLine} for "${path}": lines are 1-based integers and end_line must be >= start_line.`);
+    }
+    const diff = snapshot.files.find((entry) => entry.path === path);
+    const old = diff ? oldSideLines(diff) : new Map();
+    const missing = [];
+    let removed = false;
+    for (let line = startLine; line <= endLine; line++) {
+        const entry = old.get(line);
+        if (!entry)
+            missing.push(line);
+        else if (entry.removed)
+            removed = true;
+    }
+    if (missing.length > 0) {
+        throw new AnalysisError(`Old-side lines ${startLine}-${endLine} of "${path}" are not all in the diff (missing: ${lineList(missing)}). ` +
+            `Old-side numbers are those of the first column of get_diff; an old-side explanation covers removed lines and their context.`);
+    }
+    if (!removed) {
+        throw new AnalysisError(`Old-side lines ${startLine}-${endLine} of "${path}" contain no removed line. ` +
+            `The old side is for removed code: explain kept or added code on the new side ("side": "new").`);
+    }
+    const location = { path, side: "old", startLine, endLine };
+    return { ...location, anchorText: explanationText(diff, location) };
+}
+/** `3, 4, 9` ; au-delà de dix numéros, les dix premiers suivis de `…`. */
+function lineList(lines) {
+    const shown = lines.slice(0, 10).join(", ");
+    return lines.length > 10 ? `${shown}, …` : shown;
+}
 /**
  * Vérifie l'emplacement d'une remarque : un fichier de l'analyse, et une ligne
  * du côté « nouveau » quand `line` est fournie.

package/dist/src/core/migrate.d.ts

@@ -12,6 +12,8 @@ export declare function repoFolderName(repoPath: string): string;
 export declare const addProject: MigrationStep;
 /** Ajoute `overview` à null : l'analyse n'a pas encore de vue d'ensemble. */
 export declare const addOverview: MigrationStep;
+/** Ajoute `explanations` vide : l'analyse n'a pas encore d'explication. */
+export declare const addExplanations: MigrationStep;
 /** Étapes appliquées aux analyses (`analyses/<id>.json`), dans l'ordre. */
 export declare const ANALYSIS_MIGRATIONS: readonly MigrationStep[];
 /** Étapes appliquées aux snapshots de diff (`diffs/<id>.json`), dans l'ordre. */

package/dist/src/core/migrate.js

@@ -24,8 +24,10 @@ export const addProject = (doc) => {
 };
 /** Ajoute `overview` à null : l'analyse n'a pas encore de vue d'ensemble. */
 export const addOverview = (doc) => (doc.overview !== undefined ? null : { ...doc, overview: null });
+/** Ajoute `explanations` vide : l'analyse n'a pas encore d'explication. */
+export const addExplanations = (doc) => (doc.explanations !== undefined ? null : { ...doc, explanations: [] });
 /** Étapes appliquées aux analyses (`analyses/<id>.json`), dans l'ordre. */
-export const ANALYSIS_MIGRATIONS = [addProject, addOverview];
+export const ANALYSIS_MIGRATIONS = [addProject, addOverview, addExplanations];
 /** Étapes appliquées aux snapshots de diff (`diffs/<id>.json`), dans l'ordre. */
 export const SNAPSHOT_MIGRATIONS = [];
 /** Applique `steps` à la suite. Renvoie null si aucune étape n'a modifié le document. */

package/dist/src/core/refresh.d.ts

@@ -14,9 +14,13 @@ export interface RefreshStats {
     findingsOutdated: number;
     /** Constats `outdated` revenus à `open`. */
     findingsRestored: number;
+    /** Explications `current` passées à `outdated`. */
+    explanationsOutdated: number;
+    /** Explications `outdated` revenues à `current`. */
+    explanationsRestored: number;
 }
 export interface RefreshResult {
-    fields: Pick<Analysis, "baseCommit" | "headCommit" | "snapshotAt" | "files" | "findings">;
+    fields: Pick<Analysis, "baseCommit" | "headCommit" | "snapshotAt" | "files" | "findings" | "explanations">;
     stats: RefreshStats;
 }
 /**
@@ -25,6 +29,8 @@ export interface RefreshResult {
  * - un constat `open` dont les lignes ne correspondent plus à `anchorText`, ou dont le
  *   fichier a quitté le diff, passe à `outdated` ;
  * - un constat `outdated` dont les lignes correspondent de nouveau revient à `open` ;
- * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas.
+ * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas ;
+ * - une explication dont les lignes ne correspondent plus à `anchorText` passe à
+ *   `outdated`, et revient à `current` quand elles correspondent de nouveau.
  */
 export declare function applyRefresh(analysis: Analysis, oldSnapshot: DiffSnapshot, next: ComputedSnapshot): RefreshResult;

package/dist/src/core/refresh.js

@@ -1,5 +1,6 @@
 import { splitLines } from "../../shared/text.js";
 import { AnalysisError } from "./errors.js";
+import { explanationText } from "./locations.js";
 function hunksEqual(a, b) {
     if (a.length !== b.length)
         return false;
@@ -48,7 +49,9 @@ function currentText(finding, diffs) {
  * - un constat `open` dont les lignes ne correspondent plus à `anchorText`, ou dont le
  *   fichier a quitté le diff, passe à `outdated` ;
  * - un constat `outdated` dont les lignes correspondent de nouveau revient à `open` ;
- * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas.
+ * - un constat `ignored` reste `ignored`, un constat sans emplacement ne change pas ;
+ * - une explication dont les lignes ne correspondent plus à `anchorText` passe à
+ *   `outdated`, et revient à `current` quand elles correspondent de nouveau.
  */
 export function applyRefresh(analysis, oldSnapshot, next) {
     if (next.repoPath !== analysis.repoPath || next.mode !== analysis.mode || next.base !== analysis.base || next.head !== analysis.head) {
@@ -65,6 +68,8 @@ export function applyRefresh(analysis, oldSnapshot, next) {
         reviewedReset: 0,
         findingsOutdated: 0,
         findingsRestored: 0,
+        explanationsOutdated: 0,
+        explanationsRestored: 0,
     };
     const files = next.files.map((entry) => {
         const previous = oldEntries.get(entry.path);
@@ -100,6 +105,18 @@ export function applyRefresh(analysis, oldSnapshot, next) {
         }
         return finding;
     });
+    const explanations = analysis.explanations.map((explanation) => {
+        const matches = explanationText(newDiffs.get(explanation.location.path), explanation.location) === explanation.anchorText;
+        if (explanation.status === "current" && !matches) {
+            stats.explanationsOutdated++;
+            return { ...explanation, status: "outdated" };
+        }
+        if (explanation.status === "outdated" && matches) {
+            stats.explanationsRestored++;
+            return { ...explanation, status: "current" };
+        }
+        return explanation;
+    });
     return {
         fields: {
             baseCommit: next.baseCommit,
@@ -107,6 +124,7 @@ export function applyRefresh(analysis, oldSnapshot, next) {
             snapshotAt: next.snapshotAt,
             files,
             findings,
+            explanations,
         },
         stats,
     };

package/dist/src/core/review-actions.d.ts

@@ -1,5 +1,5 @@
 import type { Analysis } from "../../shared/schemas/analysis.schema.js";
-import type { AddNoteBody, DeleteNoteBody, SetFileReviewedBody, SetFindingStatusBody, SubmitReviewBody } from "../../shared/schemas/api.schema.js";
+import type { AddNoteBody, DeleteNoteBody, SetFileReviewedBody, SetFindingStatusBody, SubmitReviewBody, UpdateNoteBody } from "../../shared/schemas/api.schema.js";
 import type { AnalysisStore } from "./analysis-store.js";
 /**
  * Modifications faites par le relecteur depuis la GUI. Chacune passe par
@@ -15,6 +15,11 @@ export declare function setFileReviewed(store: AnalysisStore, analysisId: string
 export declare function setFindingStatus(store: AnalysisStore, analysisId: string, findingId: string, body: SetFindingStatusBody): Analysis;
 /** Ajoute une remarque du relecteur sur une ligne du côté « nouveau » ou sur un fichier entier. */
 export declare function addNote(store: AnalysisStore, analysisId: string, body: AddNoteBody): Analysis;
+/**
+ * Remplace le texte d'une remarque. Quand elle fait partie d'une revue soumise,
+ * le prompt enregistré est recalculé avec le nouveau texte.
+ */
+export declare function updateNote(store: AnalysisStore, analysisId: string, noteId: string, body: UpdateNoteBody): Analysis;
 /**
  * Supprime une remarque. Quand elle fait partie d'une revue soumise, elle est
  * retirée de la sélection et le prompt enregistré est recalculé sans elle.

package/dist/src/core/review-actions.js

@@ -47,6 +47,26 @@ export function addNote(store, analysisId, body) {
         });
     }, { baseRevision: body.baseRevision });
 }
+/**
+ * Remplace le texte d'une remarque. Quand elle fait partie d'une revue soumise,
+ * le prompt enregistré est recalculé avec le nouveau texte.
+ */
+export function updateNote(store, analysisId, noteId, body) {
+    return store.mutate(analysisId, "user", (draft) => {
+        const note = draft.notes.find((entry) => entry.id === noteId);
+        if (!note)
+            throw new NotFoundError(`Note "${noteId}" not found in analysis "${analysisId}".`);
+        note.text = body.text;
+        const review = draft.review;
+        if (review.state === "submitted" && review.selectedNoteIds.includes(noteId)) {
+            review.prompt = buildAgentPrompt(draft, {
+                findingIds: review.selectedFindingIds,
+                noteIds: review.selectedNoteIds,
+                decision: review.decision,
+            });
+        }
+    }, { baseRevision: body.baseRevision });
+}
 /**
  * Supprime une remarque. Quand elle fait partie d'une revue soumise, elle est
  * retirée de la sélection et le prompt enregistré est recalculé sans elle.

package/dist/src/core/role.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Rôle du serveur, fixé par la variable MCP_FEATURE_ANALYZER_ROLE.
+ *
+ * - `standalone` (défaut) : le serveur tourne sur la machine qui porte les dépôts et y
+ *   exécute git lui-même.
+ * - `remote` : le serveur tourne derrière mcp-http-gateway, sur une autre machine ; git
+ *   et la lecture des fichiers s'exécutent sur la machine de l'agent, par le relais agent
+ *   (`mcp-http-gateway --mcp`, route listée dans GATEWAY_EXEC_ROUTES).
+ */
+export type Role = "standalone" | "remote";
+export declare function resolveRole(): Role;

package/dist/src/core/role.js

@@ -0,0 +1,9 @@
+const ROLES = ["standalone", "remote"];
+export function resolveRole() {
+    const raw = process.env.MCP_FEATURE_ANALYZER_ROLE?.trim();
+    if (!raw)
+        return "standalone";
+    if (ROLES.includes(raw))
+        return raw;
+    throw new Error(`MCP_FEATURE_ANALYZER_ROLE="${raw}" is invalid (expected: ${ROLES.join(" | ")}).`);
+}

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)