@imenam/mcp-feature-analyzer 1.0.3 → 1.0.4

package/README.md

@@ -249,7 +249,7 @@ L'ajustement à la fenêtre ne descend jamais sous l'échelle **0,85** : en dess
   - « Code corrigé » : le code tel qu'il se lirait avec les correctifs appliqués. Les lignes visées disparaissent ; les lignes proposées prennent leur place, sur fond violet avec la marque « › » et sans numéro, sous un bandeau « Correctif N appliqué — remplace les lignes X à Y ». Un lien `?line=N` vers une ligne retirée met ce bandeau en évidence ; les remarques ne se posent que sur les lignes du diff, pas sur les lignes proposées.
 
   Dans les deux derniers modes, l'interrupteur de chaque carte (« Afficher le correctif dans le code » ou « Appliquer le correctif dans le code ») choisit les correctifs dessinés.
-- **Colonne « Constats de ce fichier »** — l'en-tête compte les constats ouverts, et le total quand il diffère (« 4 ouverts · 5 au total »). Dessous, un index compact des constats (numéro à la couleur de la gravité et première ligne, ignorés et obsolètes atténués) : un clic fait défiler jusqu'aux lignes et à la carte, mises en évidence comme avec `?line`. Tant que des cartes de constat sont sous la partie visible, une indication collée en bas de la colonne les compte (« 3 constats plus bas ↓ ») ; un clic amène la suivante. Les constats, numérotés dans l'ordre de leur première ligne, sont des cartes alignées sur leur ligne et reliées au diff ; des cartes voisines s'empilent sans se chevaucher et défilent avec le diff. Chaque carte montre numéro, gravité, lignes, titre, explication, l'interrupteur « Afficher le correctif dans le code » (constat avec correctif) et les boutons « Copier le prompt », « Ignorer » / « Rouvrir », « Remarque ». Les constats ignorés ou obsolètes restent visibles, atténués. Les remarques de ligne sont des cartes alignées de la même façon, datées au format court (date complète en infobulle) ; les remarques sur le fichier entier et ce qui vise des lignes hors du diff affiché sont en tête de colonne. Sous 1200 px de large, la colonne passe sous le diff et ses cartes s'empilent.
+- **Colonne « Constats de ce fichier »** — l'en-tête compte les constats ouverts, et le total quand il diffère (« 4 ouverts · 5 au total »). Dessous, un index compact des constats (numéro à la couleur de la gravité et première ligne, ignorés et obsolètes atténués) : un clic fait défiler jusqu'aux lignes et à la carte, mises en évidence comme avec `?line`. Tant que des cartes de constat sont sous la partie visible, une indication collée en bas de la colonne les compte (« 3 constats plus bas ↓ ») ; un clic amène la suivante. Les constats, numérotés dans l'ordre de leur première ligne, sont des cartes alignées sur leur ligne et reliées au diff ; des cartes voisines s'empilent sans se chevaucher et défilent avec le diff. Chaque carte montre numéro, gravité, lignes, titre, explication, l'interrupteur « Afficher le correctif dans le code » (constat avec correctif) et les boutons « Copier le prompt », « Ignorer » / « Rouvrir », « Remarque ». Les constats ignorés ou obsolètes restent visibles, atténués. Les remarques de ligne sont des cartes alignées de la même façon, datées au format court (date complète en infobulle), avec « Modifier », qui rouvre le texte sur place dans la même saisie que la création, et « Supprimer » ; modifier une remarque retenue dans une revue déjà soumise recalcule le prompt enregistré ; les remarques sur le fichier entier et ce qui vise des lignes hors du diff affiché sont en tête de colonne. Sous 1200 px de large, la colonne passe sous le diff et ses cartes s'empilent.
 
 Un fichier binaire, supprimé ou de plus de 1 Mo n'a pas de contenu conservé : on ne peut pas y ancrer de constat ni de remarque de ligne, seulement une remarque sur le fichier entier.
 

package/dist/shared/schemas/analysis.schema.d.ts

@@ -4,6 +4,8 @@ export declare const FILE_STATUSES: readonly ["added", "modified", "deleted", "r
 export declare const SEVERITIES: readonly ["critical", "major", "minor", "trivial"];
 export declare const FINDING_KINDS: readonly ["issue", "requirement_gap"];
 export declare const FINDING_STATUSES: readonly ["open", "ignored", "outdated"];
+export declare const EXPLANATION_SIDES: readonly ["new", "old"];
+export declare const EXPLANATION_STATUSES: readonly ["current", "outdated"];
 export declare const DIAGRAM_KINDS: readonly ["flow", "layers", "mindmap"];
 export declare const NODE_SHAPES: readonly ["box", "pill", "decision"];
 export declare const NODE_STATUSES: readonly ["new", "modified", "impacted", "existing", "finding", "missing"];
@@ -66,6 +68,41 @@ export declare const FindingSchema: z.ZodObject<{
     }>;
     createdAt: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Plage de lignes décrite par une explication, bornes incluses : côté `new` (numéros
+ * du côté « nouveau », code ajouté ou conservé) ou côté `old` (numéros du côté
+ * « ancien », code supprimé).
+ */
+export declare const ExplanationLocationSchema: z.ZodObject<{
+    path: z.ZodString;
+    side: z.ZodEnum<{
+        new: "new";
+        old: "old";
+    }>;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strip>;
+/** Description, par l'agent, de ce que fait un bloc de code et de la façon dont il le fait. */
+export declare const ExplanationSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    location: z.ZodObject<{
+        path: z.ZodString;
+        side: z.ZodEnum<{
+            new: "new";
+            old: "old";
+        }>;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+    }, z.core.$strip>;
+    anchorText: z.ZodString;
+    status: z.ZodEnum<{
+        current: "current";
+        outdated: "outdated";
+    }>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
 /** Emplacement d'une remarque : une ligne du côté « nouveau », ou le fichier entier (`line` null). */
 export declare const NoteLocationSchema: z.ZodObject<{
     path: z.ZodString;
@@ -247,6 +284,26 @@ export declare const AnalysisSchema: z.ZodObject<{
         }>;
         createdAt: z.ZodString;
     }, z.core.$strip>>;
+    explanations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodString;
+        location: z.ZodObject<{
+            path: z.ZodString;
+            side: z.ZodEnum<{
+                new: "new";
+                old: "old";
+            }>;
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+        }, z.core.$strip>;
+        anchorText: z.ZodString;
+        status: z.ZodEnum<{
+            current: "current";
+            outdated: "outdated";
+        }>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
     notes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         location: z.ZodNullable<z.ZodObject<{
@@ -323,6 +380,8 @@ export type FileStatus = (typeof FILE_STATUSES)[number];
 export type Severity = (typeof SEVERITIES)[number];
 export type FindingKind = (typeof FINDING_KINDS)[number];
 export type FindingStatus = (typeof FINDING_STATUSES)[number];
+export type ExplanationSide = (typeof EXPLANATION_SIDES)[number];
+export type ExplanationStatus = (typeof EXPLANATION_STATUSES)[number];
 export type DiagramKind = (typeof DIAGRAM_KINDS)[number];
 export type NodeShape = (typeof NODE_SHAPES)[number];
 export type NodeStatus = (typeof NODE_STATUSES)[number];
@@ -332,6 +391,8 @@ export type Editor = (typeof EDITORS)[number];
 export type FileEntry = z.infer<typeof FileEntrySchema>;
 export type FindingLocation = z.infer<typeof FindingLocationSchema>;
 export type Finding = z.infer<typeof FindingSchema>;
+export type ExplanationLocation = z.infer<typeof ExplanationLocationSchema>;
+export type Explanation = z.infer<typeof ExplanationSchema>;
 export type NoteLocation = z.infer<typeof NoteLocationSchema>;
 export type Note = z.infer<typeof NoteSchema>;
 export type DiagramNodeLocation = z.infer<typeof DiagramNodeLocationSchema>;

package/dist/shared/schemas/analysis.schema.js

@@ -4,6 +4,8 @@ export const FILE_STATUSES = ["added", "modified", "deleted", "renamed"];
 export const SEVERITIES = ["critical", "major", "minor", "trivial"];
 export const FINDING_KINDS = ["issue", "requirement_gap"];
 export const FINDING_STATUSES = ["open", "ignored", "outdated"];
+export const EXPLANATION_SIDES = ["new", "old"];
+export const EXPLANATION_STATUSES = ["current", "outdated"];
 export const DIAGRAM_KINDS = ["flow", "layers", "mindmap"];
 export const NODE_SHAPES = ["box", "pill", "decision"];
 export const NODE_STATUSES = ["new", "modified", "impacted", "existing", "finding", "missing"];
@@ -55,6 +57,29 @@ export const FindingSchema = z.object({
     status: z.enum(FINDING_STATUSES),
     createdAt: IsoDateSchema,
 });
+/**
+ * Plage de lignes décrite par une explication, bornes incluses : côté `new` (numéros
+ * du côté « nouveau », code ajouté ou conservé) ou côté `old` (numéros du côté
+ * « ancien », code supprimé).
+ */
+export const ExplanationLocationSchema = z.object({
+    path: z.string().min(1),
+    side: z.enum(EXPLANATION_SIDES),
+    startLine: LineSchema,
+    endLine: LineSchema,
+});
+/** Description, par l'agent, de ce que fait un bloc de code et de la façon dont il le fait. */
+export const ExplanationSchema = z.object({
+    id: ItemIdSchema,
+    title: z.string().min(1),
+    body: z.string().min(1),
+    location: ExplanationLocationSchema,
+    /** Texte exact des lignes décrites au moment où l'explication a été ancrée. */
+    anchorText: z.string(),
+    /** `outdated` quand les lignes décrites ont changé depuis, au recalcul du snapshot. */
+    status: z.enum(EXPLANATION_STATUSES),
+    createdAt: IsoDateSchema,
+});
 /** Emplacement d'une remarque : une ligne du côté « nouveau », ou le fichier entier (`line` null). */
 export const NoteLocationSchema = z.object({
     path: z.string().min(1),
@@ -140,6 +165,7 @@ export const AnalysisSchema = z.object({
     summary: z.array(z.string().min(1)),
     files: z.array(FileEntrySchema),
     findings: z.array(FindingSchema),
+    explanations: z.array(ExplanationSchema),
     notes: z.array(NoteSchema),
     diagrams: z.array(DiagramSchema),
     review: ReviewSchema,

package/dist/shared/schemas/api.schema.d.ts

@@ -19,6 +19,10 @@ export declare const AddNoteBodySchema: z.ZodObject<{
     text: z.ZodString;
     baseRevision: z.ZodNumber;
 }, z.core.$strict>;
+export declare const UpdateNoteBodySchema: z.ZodObject<{
+    text: z.ZodString;
+    baseRevision: z.ZodNumber;
+}, z.core.$strict>;
 export declare const DeleteNoteBodySchema: z.ZodObject<{
     baseRevision: z.ZodNumber;
 }, z.core.$strict>;
@@ -35,6 +39,7 @@ export declare const SubmitReviewBodySchema: z.ZodObject<{
 export type SetFileReviewedBody = z.infer<typeof SetFileReviewedBodySchema>;
 export type SetFindingStatusBody = z.infer<typeof SetFindingStatusBodySchema>;
 export type AddNoteBody = z.infer<typeof AddNoteBodySchema>;
+export type UpdateNoteBody = z.infer<typeof UpdateNoteBodySchema>;
 export type DeleteNoteBody = z.infer<typeof DeleteNoteBodySchema>;
 export type SubmitReviewBody = z.infer<typeof SubmitReviewBodySchema>;
 /** Données IPC des requêtes de la GUI qui visent une analyse. */
@@ -70,6 +75,14 @@ export declare const AddNoteRequestSchema: z.ZodObject<{
         baseRevision: z.ZodNumber;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const UpdateNoteRequestSchema: z.ZodObject<{
+    analysisId: z.ZodString;
+    noteId: z.ZodString;
+    body: z.ZodObject<{
+        text: z.ZodString;
+        baseRevision: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const DeleteNoteRequestSchema: z.ZodObject<{
     analysisId: z.ZodString;
     noteId: z.ZodString;

package/dist/shared/schemas/api.schema.js

@@ -22,6 +22,10 @@ export const AddNoteBodySchema = z.strictObject({
     text: z.string().trim().min(1, "the note text is empty"),
     baseRevision: BaseRevisionSchema,
 });
+export const UpdateNoteBodySchema = z.strictObject({
+    text: z.string().trim().min(1, "the note text is empty"),
+    baseRevision: BaseRevisionSchema,
+});
 export const DeleteNoteBodySchema = z.strictObject({
     baseRevision: BaseRevisionSchema,
 });
@@ -39,6 +43,10 @@ export const SetFindingStatusRequestSchema = AnalysisRequestSchema.extend({
     body: SetFindingStatusBodySchema,
 });
 export const AddNoteRequestSchema = AnalysisRequestSchema.extend({ body: AddNoteBodySchema });
+export const UpdateNoteRequestSchema = AnalysisRequestSchema.extend({
+    noteId: z.string().min(1),
+    body: UpdateNoteBodySchema,
+});
 export const DeleteNoteRequestSchema = AnalysisRequestSchema.extend({
     noteId: z.string().min(1),
     body: DeleteNoteBodySchema,

package/dist/shared/schemas/ipc.schema.d.ts

@@ -25,5 +25,5 @@ export type IPCMessage = z.infer<typeof IPCMessageSchema>;
 export declare const PUSHED_EVENT_TYPES: readonly ["INITIAL_STATE", "ANALYSES_UPDATED", "ANALYSIS_UPDATED"];
 export type PushedEventType = (typeof PUSHED_EVENT_TYPES)[number];
 /** Requêtes du GUI worker au maître ; chacune reçoit une réponse de même `correlationId`. */
-export declare const GUI_REQUEST_TYPES: readonly ["GET_CONFIG", "LIST_ANALYSES", "GET_ANALYSIS", "GET_DIFF", "SET_FILE_REVIEWED", "SET_FINDING_STATUS", "ADD_NOTE", "DELETE_NOTE", "SUBMIT_REVIEW"];
+export declare const GUI_REQUEST_TYPES: readonly ["GET_CONFIG", "LIST_ANALYSES", "GET_ANALYSIS", "GET_DIFF", "SET_FILE_REVIEWED", "SET_FINDING_STATUS", "ADD_NOTE", "UPDATE_NOTE", "DELETE_NOTE", "SUBMIT_REVIEW"];
 export type GuiRequestType = (typeof GUI_REQUEST_TYPES)[number];

package/dist/shared/schemas/ipc.schema.js

@@ -25,6 +25,7 @@ export const GUI_REQUEST_TYPES = [
     "SET_FILE_REVIEWED",
     "SET_FINDING_STATUS",
     "ADD_NOTE",
+    "UPDATE_NOTE",
     "DELETE_NOTE",
     "SUBMIT_REVIEW",
 ];

package/dist/src/core/analysis-store.js

@@ -269,6 +269,7 @@ export class AnalysisStore {
             summary: input.summary ?? [],
             files: snapshot.files.map((file) => ({ ...file, reviewed: false })),
             findings: [],
+            explanations: [],
             notes: [],
             diagrams: [],
             review: pendingReview(),

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.