@imenam/mcp-feature-analyzer 1.0.3 → 1.0.5

package/README.md

@@ -163,6 +163,18 @@ L'**état de revue** est dérivé des fichiers revus et de la soumission (`share
 
 Un `issue` a toujours un emplacement ; un `requirement_gap` peut ne pas en avoir. Une `suggestion` n'est jamais appliquée : la GUI l'affiche (lignes actuelles barrées, lignes proposées) et le prompt la transmet.
 
+### Explications
+
+Une explication décrit ce que fait un bloc de code ajouté ou supprimé, et comment il le fait. Elle aide le relecteur à comprendre le code avant de le juger : ce n'est pas un constat, elle ne demande rien et n'entre pas dans le retour de revue. Les instructions du serveur demandent à l'agent d'en écrire une pour chaque bloc long (une trentaine de lignes ou plus) ou complexe (algorithme, machine à états, concurrence, expression régulière délicate…), et jamais pour du code trivial.
+
+| Outil | Effet |
+|---|---|
+| `add_explanations` | Ajoute un lot d'explications : titre, corps, `path` + `start_line` (+ `end_line`) et `side`. `side: "new"` (par défaut) vise du code ajouté ou conservé, en numéros du côté nouveau ; `side: "old"` vise du code supprimé, en numéros du côté ancien (première colonne de `get_diff`), lignes toutes présentes dans le diff et dont au moins une est supprimée. Les lignes décrites sont copiées du diff figé. Une seule explication invalide et **rien n'est ajouté**. |
+| `update_explanation` | Modifie le titre, le corps ou l'emplacement d'une explication. Un nouvel emplacement est vérifié contre le diff et rend son statut « à jour » à une explication obsolète. |
+| `delete_explanations` | Supprime des explications par identifiant. Un identifiant inconnu fait échouer l'appel sans rien supprimer. |
+
+`refresh_analysis` traite les explications comme les constats : une explication dont les lignes ne correspondent plus au texte copié passe à « obsolète », et redevient à jour si elles correspondent de nouveau.
+
 ### Schémas
 
 | Outil | Effet |
@@ -205,6 +217,7 @@ create_analysis { repo_path: "C:/dev/mon-projet", project: "mon-projet", title:
 get_diff        { analysis_id }                     ← numéros de ligne du côté nouveau
 update_analysis { analysis_id, objective: "…", approach: "…", attention_points: ["…"],
                   summary: ["…", "…"] }             ← vue d'ensemble et changements fonctionnels
+add_explanations { analysis_id, explanations: [...] } ← blocs longs ou complexes, ajoutés ou supprimés
 add_findings    { analysis_id, findings: [...] }    ← y compris les requirement_gap
 set_diagram     { analysis_id, kind: "flow", nodes: [...], links: [...] }
 
@@ -242,14 +255,14 @@ L'ajustement à la fenêtre ne descend jamais sous l'échelle **0,85** : en dess
 
 - **Panneau des fichiers** — progression, fichiers groupés par dossier, état revu, pastilles des constats ouverts par gravité. Un nom trop long est tronqué au milieu (`reminder-sch…uler.ts`), l'extension reste visible et le chemin complet est en infobulle. Chaque pastille est un lien : elle ouvre le fichier sur son premier constat ouvert de cette gravité (`?line=N`) ; son infobulle le dit (« 3 constats mineurs ouverts — aller au premier »).
 - **En-tête du fichier** — chemin, `+`/`−`, statut, fichier précédent et suivant, « Remarque sur le fichier », « Marquer comme revu ».
-- **Diff** — numéros du côté nouveau et repère vertical à la couleur de la gravité le long des lignes visées par un constat. Le correctif proposé s'affiche à l'endroit où il s'applique : bandeau « Correctif proposé par l'agent — remplace les lignes X à Y » avec le numéro du constat et « Masquer le correctif », lignes visées barrées sur fond ambre, lignes proposées juste en dessous sur fond violet (marque « › », sans numéro). Le correctif est affiché d'office pour un constat ouvert ; masqué, ou pour un constat sans correctif, une pastille numérotée marque la première ligne visée. Deux correctifs dont les lignes se recouvrent ne s'affichent pas ensemble. Le fond ambre des lignes visées se distingue du rouge des lignes `−` supprimées par la feature. Une légende suit le diff, limitée aux fonds que le mode affiche : « Ajouté par la feature », « Supprimé par la feature », « Lignes remplacées par le correctif » (Avant / après), « Correctif proposé » ou « Correctif appliqué ». Un clic sur un numéro de ligne ouvre la saisie d'une remarque sur cette ligne. Les exigences manquantes sans emplacement s'affichent en bandeau au-dessus du diff de chaque fichier ; le bandeau « N exigences manquantes » se replie, et reste replié pour la session.
+- **Diff** — numéros du côté nouveau et repère vertical à la couleur de la gravité le long des lignes visées par un constat. Le correctif proposé s'affiche à l'endroit où il s'applique : bandeau « Correctif proposé par l'agent — remplace les lignes X à Y » avec le numéro du constat et « Masquer le correctif », lignes visées barrées sur fond ambre, lignes proposées juste en dessous sur fond violet (marque « › », sans numéro). Le correctif est affiché d'office pour un constat ouvert ; masqué, ou pour un constat sans correctif, une pastille numérotée marque la première ligne visée. Un filet sarcelle longe les lignes décrites par une explication. L'en-tête de chaque bloc du diff porte « Copier une demande d'explication » : le bouton copie un prompt à coller dans la conversation de l'agent, qui situe le bloc (analyse, dépôt et refs, fichier, lignes des deux côtés, code tel que figé) et lui demande de l'expliquer en enregistrant ses explications avec `add_explanations`, ou `update_explanation` si une explication couvre déjà ces lignes. Deux correctifs dont les lignes se recouvrent ne s'affichent pas ensemble. Le fond ambre des lignes visées se distingue du rouge des lignes `−` supprimées par la feature. Une légende suit le diff, limitée aux fonds que le mode affiche : « Ajouté par la feature », « Supprimé par la feature », « Lignes remplacées par le correctif » (Avant / après), « Correctif proposé » ou « Correctif appliqué », « Code décrit par une explication ». Un clic sur un numéro de ligne ouvre la saisie d'une remarque sur cette ligne. Les exigences manquantes sans emplacement s'affichent en bandeau au-dessus du diff de chaque fichier ; le bandeau « N exigences manquantes » se replie, et reste replié pour la session.
 - **Affichage des correctifs** — le sélecteur « Correctifs », au-dessus du diff, propose trois modes, conservés d'un fichier à l'autre pendant la session :
   - « Sans correctif » : le diff seul, sans aucun correctif ; les interrupteurs des cartes sont inactifs.
   - « Avant / après » (par défaut) : le rendu décrit ci-dessus, lignes visées barrées puis lignes proposées.
   - « 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 et explications »** — l'en-tête compte les constats ouverts, et le total quand il diffère (« 4 constats ouverts · 5 au total »). Deux boutons, « Constats » et « Explications », affichent ou masquent chacun leur type, indépendamment l'un de l'autre et pour tous les fichiers de la session ; chacun indique le nombre d'éléments du fichier. Masquer les constats retire aussi leurs repères, pastilles et correctifs du diff et le bandeau des exigences manquantes : on parcourt alors le code avec ses seules explications, avant de rétablir les constats. Masquer les explications retire leurs cartes et leurs filets. 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 explications sont des cartes sarcelle alignées de la même façon sur la première ligne qu'elles décrivent, une ligne supprimée pour du code supprimé ; à hauteur égale, l'explication précède les constats. Chaque carte montre les lignes (côté ancien et mention « Code supprimé » pour du code supprimé), le titre et le texte, replié au-delà de huit lignes avec « Lire la suite ». Une explication obsolète est atténuée et signale que le code décrit a changé. 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.
 
@@ -274,15 +287,16 @@ Le worker ne lit ni n'écrit aucune donnée : chaque requête REST est transmise
 
 ### Persistance
 
-Un fichier JSON par analyse dans `<données>/analyses/<id>.json`, et son diff figé dans `<données>/diffs/<id>.json`. Les écritures sont atomiques (fichier temporaire puis `rename`), sérialisées entre processus par un verrou `.lock`, et le cache mémoire est invalidé dès que la date ou la taille du fichier change. Tout document est validé par zod à la lecture et à l'écriture ; `src/core/migrate.ts` met à niveau les anciens formats à la lecture : une analyse sans projet reçoit le nom du dossier du dépôt (`basename(repoPath)`), une analyse sans vue d'ensemble reçoit `overview: null`.
+Un fichier JSON par analyse dans `<données>/analyses/<id>.json`, et son diff figé dans `<données>/diffs/<id>.json`. Les écritures sont atomiques (fichier temporaire puis `rename`), sérialisées entre processus par un verrou `.lock`, et le cache mémoire est invalidé dès que la date ou la taille du fichier change. Tout document est validé par zod à la lecture et à l'écriture ; `src/core/migrate.ts` met à niveau les anciens formats à la lecture : une analyse sans projet reçoit le nom du dossier du dépôt (`basename(repoPath)`), une analyse sans vue d'ensemble reçoit `overview: null`, une analyse sans explications reçoit une liste vide.
 
 ### Invariants
 
 Toute modification, qu'elle vienne d'un outil ou de la GUI, passe par `AnalysisStore.mutate(id, editor, fn, { baseRevision })`, qui vérifie le schéma et les invariants avant d'écrire et incrémente la révision :
 
 - refs cohérentes avec le mode (`branch` : ref et commit de tête ; `working_tree` : base `HEAD`, sans 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 ouvert vise un fichier de l'analyse dont le contenu est conservé, avec `1 ≤ startLine ≤ endLine ≤` nombre de lignes ; un `issue` a un emplacement ;
+- une explication à jour vise un fichier de l'analyse ; côté nouveau, son contenu est conservé et ses lignes existent ;
 - les liens d'un schéma relient des nœuds existants ; en `layers`, chaque nœud est dans une couche déclarée ;
 - la revue ne sélectionne que des constats et des remarques existants ;
 - les champs issus du diff (dépôt, refs, commits, liste des fichiers hors « revu ») ne changent que par `refresh_analysis`.

package/dist/shared/explanation-request.d.ts

@@ -0,0 +1,9 @@
+import type { Analysis, FileEntry } from "./schemas/analysis.schema.js";
+import type { Hunk } from "./schemas/diff.schema.js";
+/**
+ * Prompt qui demande à l'agent d'expliquer un bloc du diff et d'enregistrer ses
+ * explications dans l'analyse : analyse, dépôt et refs, fichier, plages de lignes
+ * des deux côtés, code du bloc tel que figé, puis la marche à suivre
+ * (add_explanations, ou update_explanation pour une explication existante).
+ */
+export declare function buildExplanationRequestPrompt(analysis: Analysis, file: FileEntry, hunk: Hunk): string;

package/dist/shared/explanation-request.js

@@ -0,0 +1,55 @@
+import { lineRange } from "./text.js";
+const MARKERS = { context: " ", add: "+", del: "-" };
+function refsLabel(analysis) {
+    if (analysis.mode === "branch")
+        return `branch ${analysis.base}...${analysis.head}`;
+    return "working tree changes against HEAD";
+}
+/** Plage `début-fin` d'un côté du bloc, ou null quand ce côté n'a aucune ligne. */
+function sideRange(start, count) {
+    return count === 0 ? null : lineRange(start, start + count - 1);
+}
+/** Lignes du bloc au format de get_diff : `ancien | nouveau`, puis le marqueur et le texte. */
+function hunkCode(hunk) {
+    let width = 1;
+    for (const line of hunk.lines) {
+        width = Math.max(width, String(line.oldNo ?? "").length, String(line.newNo ?? "").length);
+    }
+    const column = (value) => String(value ?? "").padStart(width);
+    return [hunk.header, ...hunk.lines.map((line) => `${column(line.oldNo)} | ${column(line.newNo)} ${MARKERS[line.type]} ${line.text}`)];
+}
+/**
+ * Prompt qui demande à l'agent d'expliquer un bloc du diff et d'enregistrer ses
+ * explications dans l'analyse : analyse, dépôt et refs, fichier, plages de lignes
+ * des deux côtés, code du bloc tel que figé, puis la marche à suivre
+ * (add_explanations, ou update_explanation pour une explication existante).
+ */
+export function buildExplanationRequestPrompt(analysis, file, hunk) {
+    const newRange = sideRange(hunk.newStart, hunk.newLines);
+    const oldRange = sideRange(hunk.oldStart, hunk.oldLines);
+    const where = [
+        `- File: ${file.path}${file.oldPath !== null ? ` (renamed from ${file.oldPath})` : ""}`,
+        newRange === null ? "- New side: no line (the section only removes code)." : `- New side (code after the feature): lines ${newRange}`,
+        oldRange === null ? "- Old side: no line (the section only adds code)." : `- Old side (code before the feature): lines ${oldRange}`,
+    ];
+    return [
+        `Explain a section of code in the feature analysis "${analysis.title}" (analysis_id: "${analysis.id}", project "${analysis.project}").`,
+        `Repository: ${analysis.repoPath} — ${refsLabel(analysis)}.`,
+        "",
+        "Section to explain:",
+        ...where,
+        "",
+        "Code of the section, as frozen in the analysis (columns: old line | new line, then + added, - removed, or a space for context):",
+        "```",
+        ...hunkCode(hunk),
+        "```",
+        "",
+        "What to do:",
+        `1. Read this code and what surrounds it (get_diff with analysis_id "${analysis.id}" and path "${file.path}", and the repository) until you understand what it does and how it works.`,
+        `2. Record your explanations in the feature analyzer with add_explanations (analysis_id "${analysis.id}", path "${file.path}"): one explanation per meaningful block of the section, covering it from its first to its last line. ` +
+            `Use "side": "new" with new-side line numbers for added or kept code, and "side": "old" with old-side line numbers for removed code.`,
+        "3. In each explanation, say what the code 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. Describe, do not judge.",
+        "4. If an explanation of the analysis already covers these lines (see get_analysis), rewrite it with update_explanation instead of adding a duplicate.",
+        "5. Then tell me in a few lines which explanations you recorded.",
+    ].join("\n");
+}

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. */