@imenam/mcp-feature-analyzer 1.0.0

package/dist/src/core/errors.js

@@ -0,0 +1,28 @@
+/** Erreur métier dont le message s'adresse directement à l'agent ou à la GUI. */
+export class AnalysisError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AnalysisError";
+    }
+}
+/** Analyse, constat ou remarque introuvable. */
+export class NotFoundError extends AnalysisError {
+    constructor(message) {
+        super(message);
+        this.name = "NotFoundError";
+    }
+}
+/** Modification basée sur une révision qui n'est plus la révision enregistrée. */
+export class RevisionConflictError extends AnalysisError {
+    constructor(message) {
+        super(message);
+        this.name = "RevisionConflictError";
+    }
+}
+/** Échec d'accès au dépôt git : chemin invalide, dépôt absent, ref inconnue, commande en erreur. */
+export class GitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitError";
+    }
+}

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

@@ -0,0 +1,35 @@
+import type { AnalysisMode, FileEntry } from "../../shared/schemas/analysis.schema.js";
+import { type FileDiff } from "../../shared/schemas/diff.schema.js";
+/** Ref de tête utilisée en mode `branch` quand aucune n'est fournie. */
+export declare const DEFAULT_HEAD_REF = "HEAD";
+export interface SnapshotRequest {
+    /** Chemin absolu de la racine du dépôt git. */
+    repoPath: string;
+    mode: AnalysisMode;
+    /** Ref de base, requise en mode `branch` ; absente ou "HEAD" en mode `working_tree`. */
+    base?: string | null;
+    /** Ref de tête en mode `branch`, `HEAD` par défaut ; interdite en mode `working_tree`. */
+    head?: string | null;
+}
+/** Snapshot calculé : refs effectives, métadonnées des fichiers et diff figé. */
+export interface ComputedSnapshot {
+    repoPath: string;
+    mode: AnalysisMode;
+    /** Ref de base effective ; "HEAD" en mode `working_tree`. */
+    base: string;
+    /** Ref de tête effective en mode `branch` ; null en mode `working_tree`. */
+    head: string | null;
+    baseCommit: string;
+    headCommit: string | null;
+    snapshotAt: string;
+    files: FileEntry[];
+    diff: FileDiff[];
+}
+/**
+ * Calcule le snapshot d'une analyse avec git.
+ * - `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 declare function computeSnapshot(request: SnapshotRequest): Promise<ComputedSnapshot>;

package/dist/src/core/git.js

@@ -0,0 +1,257 @@
+import { execFile } from "child_process";
+import fs from "fs";
+import path from "path";
+import { MAX_SNAPSHOT_FILE_BYTES } from "../../shared/schemas/diff.schema.js";
+import { splitLines } from "../../shared/text.js";
+import { parseUnifiedDiff, toPosixPath } from "./diff-parser.js";
+import { GitError } from "./errors.js";
+/** Plafond de la sortie d'une commande git. */
+const GIT_MAX_BUFFER = 512 * 1024 * 1024;
+/** Ref de tête utilisée en mode `branch` quand aucune n'est fournie. */
+export const DEFAULT_HEAD_REF = "HEAD";
+function runGit(cwd, args, encoding, input) {
+    const fullArgs = ["-c", "core.quotepath=false", ...args];
+    return new Promise((resolve, reject) => {
+        const child = execFile("git", fullArgs, { cwd, maxBuffer: GIT_MAX_BUFFER, encoding: encoding === "buffer" ? "buffer" : "utf8", windowsHide: true }, (error, stdout, stderr) => {
+            if (error) {
+                const code = error.code;
+                if (code === "ENOENT") {
+                    reject(new GitError("The git executable was not found on PATH. Install git and restart the MCP server."));
+                    return;
+                }
+                const detail = String(stderr).trim() || error.message;
+                reject(new GitError(`git ${args.join(" ")} failed in ${cwd}: ${detail}`));
+                return;
+            }
+            resolve(stdout);
+        });
+        child.stdin?.end(input ?? "");
+    });
+}
+/** Chemin réel et normalisé, comparable entre deux écritures du même répertoire. */
+function canonical(value) {
+    const real = path.resolve(fs.realpathSync.native(value));
+    return process.platform === "win32" ? real.toLowerCase() : real;
+}
+/** Vérifie que `repoPath` est un chemin absolu vers la racine d'un dépôt git. */
+async function assertRepoRoot(repoPath) {
+    if (!path.isAbsolute(repoPath)) {
+        throw new GitError(`repo_path must be an absolute path, got "${repoPath}".`);
+    }
+    if (!fs.existsSync(repoPath) || !fs.statSync(repoPath).isDirectory()) {
+        throw new GitError(`repo_path "${repoPath}" does not exist or is not a directory.`);
+    }
+    let topLevel;
+    try {
+        topLevel = (await runGit(repoPath, ["rev-parse", "--show-toplevel"], "utf-8")).trim();
+    }
+    catch (err) {
+        if (err instanceof GitError && /not a git repository/i.test(err.message)) {
+            throw new GitError(`repo_path "${repoPath}" is not inside a git repository.`);
+        }
+        throw err;
+    }
+    if (canonical(topLevel) !== canonical(repoPath)) {
+        throw new GitError(`repo_path "${repoPath}" is not the root of its git repository. Use the repository root: ${path.resolve(topLevel)}`);
+    }
+}
+/** 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 "-".`);
+    }
+    try {
+        return (await runGit(repoPath, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], "utf-8")).trim();
+    }
+    catch {
+        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 = [
+    "-c",
+    "diff.noprefix=false",
+    "-c",
+    "diff.mnemonicPrefix=false",
+    "diff",
+    "--no-color",
+    "--no-ext-diff",
+    "--no-textconv",
+    "--no-relative",
+    "--find-renames",
+    "--src-prefix=a/",
+    "--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) {
+    return content.subarray(0, 8000).includes(0);
+}
+/** Hunk unique d'un fichier ajouté, toutes lignes en ajout. */
+function additionHunk(lines) {
+    if (lines.length === 0)
+        return [];
+    return [
+        {
+            header: `@@ -0,0 +1,${lines.length} @@`,
+            oldStart: 0,
+            oldLines: 0,
+            newStart: 1,
+            newLines: lines.length,
+            lines: lines.map((text, index) => ({ type: "add", oldNo: null, newNo: index + 1, text })),
+        },
+    ];
+}
+/** Contenu d'un fichier de la copie de travail ; un lien symbolique donne sa cible, comme dans git. */
+function readWorkingFile(repoPath, filePath) {
+    const absolute = path.join(repoPath, ...filePath.split("/"));
+    const stat = fs.lstatSync(absolute);
+    if (stat.isSymbolicLink())
+        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. */
+function snapshotText(content) {
+    if (content.length > MAX_SNAPSHOT_FILE_BYTES)
+        return null;
+    return content.toString("utf-8");
+}
+function toEntry(parsed, newContent) {
+    return {
+        entry: {
+            path: parsed.path,
+            oldPath: parsed.oldPath,
+            status: parsed.status,
+            additions: parsed.additions,
+            deletions: parsed.deletions,
+            binary: parsed.binary,
+            contentAvailable: newContent !== null,
+            lineCount: newContent === null ? 0 : splitLines(newContent).length,
+            reviewed: false,
+        },
+        diff: { path: parsed.path, hunks: parsed.hunks, newContent },
+    };
+}
+/**
+ * Contenu des fichiers `paths` dans le commit `commit`, en deux commandes git
+ * quel que soit leur nombre : `ls-tree` donne l'objet de chaque chemin, puis
+ * `cat-file --batch` lit tous les objets d'un coup.
+ */
+async function readCommitFiles(repoPath, commit, paths) {
+    const contents = new Map();
+    if (paths.length === 0)
+        return contents;
+    const blobs = new Map();
+    for (const entry of (await runGit(repoPath, ["ls-tree", "-r", "-z", "--full-tree", commit], "utf-8")).split("\0")) {
+        if (entry === "")
+            continue;
+        const tab = entry.indexOf("\t");
+        const [, type, sha] = entry.slice(0, tab).split(" ");
+        if (type === "blob")
+            blobs.set(entry.slice(tab + 1), sha);
+    }
+    const shas = paths.map((filePath) => {
+        const sha = blobs.get(filePath);
+        if (sha === undefined) {
+            throw new GitError(`"${filePath}" is in the diff but is not a file of commit ${commit} (submodule or unreadable entry).`);
+        }
+        return sha;
+    });
+    const output = await runGit(repoPath, ["cat-file", "--batch"], "buffer", shas.join("\n") + "\n");
+    let offset = 0;
+    paths.forEach((filePath, index) => {
+        const headerEnd = output.indexOf(0x0a, offset);
+        if (headerEnd === -1)
+            throw new GitError(`git cat-file --batch ended before the content of "${filePath}".`);
+        const header = output.subarray(offset, headerEnd).toString("utf-8");
+        const [sha, type, size] = header.split(" ");
+        if (sha !== shas[index] || type !== "blob" || size === undefined) {
+            throw new GitError(`Unexpected git cat-file --batch header "${header}" for "${filePath}".`);
+        }
+        const start = headerEnd + 1;
+        contents.set(filePath, output.subarray(start, start + Number(size)));
+        offset = start + Number(size) + 1;
+    });
+    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");
+    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));
+    });
+    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);
+    for (const filePath of untracked) {
+        const raw = readWorkingFile(repoPath, filePath);
+        const binary = looksBinary(raw);
+        const content = binary ? null : snapshotText(raw);
+        const lines = binary ? [] : splitLines(raw.toString("utf-8"));
+        const hunks = additionHunk(lines);
+        results.push(toEntry({ path: filePath, oldPath: null, status: "added", binary, hunks, additions: lines.length, deletions: 0 }, content));
+    }
+    return { baseCommit, headCommit: null, results };
+}
+/**
+ * Calcule le snapshot d'une analyse avec git.
+ * - `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) {
+    const { repoPath, mode } = request;
+    await assertRepoRoot(repoPath);
+    let base;
+    let head;
+    let computed;
+    if (mode === "branch") {
+        const requestedBase = request.base?.trim();
+        if (!requestedBase)
+            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);
+    }
+    else if (mode === "working_tree") {
+        if (request.head != null && request.head.trim() !== "") {
+            throw new GitError(`"head" is not accepted in working_tree mode: the working tree is compared against HEAD.`);
+        }
+        if (request.base != null && request.base.trim() !== "" && request.base.trim() !== "HEAD") {
+            throw new GitError(`"base" is not accepted in working_tree mode: the working tree is always compared against HEAD.`);
+        }
+        base = "HEAD";
+        head = null;
+        computed = await workingTreeSnapshot(repoPath);
+    }
+    else {
+        throw new GitError(`Unknown mode "${String(mode)}": use "branch" or "working_tree".`);
+    }
+    computed.results.sort((a, b) => (a.entry.path < b.entry.path ? -1 : a.entry.path > b.entry.path ? 1 : 0));
+    return {
+        repoPath,
+        mode,
+        base,
+        head,
+        baseCommit: computed.baseCommit,
+        headCommit: computed.headCommit,
+        snapshotAt: new Date().toISOString(),
+        files: computed.results.map((result) => result.entry),
+        diff: computed.results.map((result) => result.diff),
+    };
+}

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

@@ -0,0 +1,16 @@
+/** Suite aléatoire de caractères [a-z0-9]. */
+export declare function randomToken(length: number): string;
+/** "Refonte de l'Écran" -> "refonte-de-l-ecran" ; "analysis" quand rien ne reste. */
+export declare function slugify(value: string): string;
+/** Identifiant d'analyse : slug du titre suivi d'un identifiant court, par ex. "oauth-refresh-k3x9q2". */
+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 note: "n";
+    readonly diagram: "d";
+    readonly node: "nd";
+};
+export type ItemKind = keyof typeof ITEM_ID_PREFIXES;
+/** Identifiant court d'élément, par ex. "f_a1b2c3", absent de `taken`. */
+export declare function itemId(kind: ItemKind, taken: ReadonlySet<string>): string;

package/dist/src/core/ids.js

@@ -0,0 +1,41 @@
+import crypto from "crypto";
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+/** Suite aléatoire de caractères [a-z0-9]. */
+export function randomToken(length) {
+    const bytes = crypto.randomBytes(length);
+    let out = "";
+    for (const byte of bytes)
+        out += ALPHABET[byte % ALPHABET.length];
+    return out;
+}
+/** "Refonte de l'Écran" -> "refonte-de-l-ecran" ; "analysis" quand rien ne reste. */
+export function slugify(value) {
+    const slug = value
+        .normalize("NFD")
+        .replace(/\p{Diacritic}/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48)
+        .replace(/-+$/g, "");
+    return slug || "analysis";
+}
+/** Identifiant d'analyse : slug du titre suivi d'un identifiant court, par ex. "oauth-refresh-k3x9q2". */
+export function analysisId(title) {
+    return `${slugify(title)}-${randomToken(6)}`;
+}
+/** Préfixe des identifiants générés, par type d'élément. */
+export const ITEM_ID_PREFIXES = {
+    finding: "f",
+    note: "n",
+    diagram: "d",
+    node: "nd",
+};
+/** Identifiant court d'élément, par ex. "f_a1b2c3", absent de `taken`. */
+export function itemId(kind, taken) {
+    for (;;) {
+        const candidate = `${ITEM_ID_PREFIXES[kind]}_${randomToken(6)}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}

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

@@ -0,0 +1,24 @@
+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) ;
+ * - 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 ;
+ * - 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.
+ */
+export declare function findInvariantViolations(analysis: Analysis): string[];
+/** Lève une AnalysisError listant toutes les violations, s'il y en a. */
+export declare function assertInvariants(analysis: Analysis): void;
+/**
+ * Vérifie qu'une modification ne touche pas aux champs fixés par le snapshot
+ * (identité, dépôt, refs, commits, liste et métadonnées des fichiers hors
+ * `reviewed`). Seul le recalcul du snapshot les change.
+ */
+export declare function assertSnapshotFieldsUnchanged(before: Analysis, after: Analysis): void;

package/dist/src/core/invariants.js

@@ -0,0 +1,157 @@
+import { AnalysisError } from "./errors.js";
+/** Identifiants présents plusieurs fois dans `ids`. */
+function duplicates(ids) {
+    const seen = new Set();
+    const repeated = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            repeated.add(id);
+        seen.add(id);
+    }
+    return [...repeated];
+}
+/**
+ * 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) ;
+ * - 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 ;
+ * - 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.
+ */
+export function findInvariantViolations(analysis) {
+    const problems = [];
+    const files = new Map(analysis.files.map((file) => [file.path, file]));
+    if (analysis.mode === "branch" && (analysis.head === null || analysis.headCommit === null)) {
+        problems.push("a branch analysis needs a head ref and a head commit");
+    }
+    if (analysis.mode === "working_tree" && (analysis.base !== "HEAD" || analysis.head !== null || analysis.headCommit !== null)) {
+        problems.push('a working_tree analysis has base "HEAD" and no head ref nor head commit');
+    }
+    for (const [label, ids] of [
+        ["file path", analysis.files.map((file) => file.path)],
+        ["finding id", analysis.findings.map((finding) => finding.id)],
+        ["note id", analysis.notes.map((note) => note.id)],
+        ["diagram id", analysis.diagrams.map((diagram) => diagram.id)],
+    ]) {
+        for (const id of duplicates(ids))
+            problems.push(`duplicate ${label} "${id}"`);
+    }
+    for (const finding of analysis.findings) {
+        const where = `finding "${finding.id}"`;
+        const location = finding.location;
+        if (location === null) {
+            if (finding.kind === "issue") {
+                problems.push(`${where} is an issue and needs a location (only requirement_gap findings may have none)`);
+            }
+            if (finding.anchorText !== null)
+                problems.push(`${where} has anchorText but no location`);
+            if (finding.suggestion !== null)
+                problems.push(`${where} has a suggestion but no location to replace`);
+            continue;
+        }
+        if (finding.anchorText === null)
+            problems.push(`${where} has a location but no anchorText`);
+        if (location.startLine > location.endLine) {
+            problems.push(`${where} has startLine ${location.startLine} after endLine ${location.endLine}`);
+        }
+        if (finding.status !== "open")
+            continue;
+        const file = files.get(location.path);
+        if (!file) {
+            problems.push(`${where} targets "${location.path}", which is not a changed file of this analysis`);
+            continue;
+        }
+        if (!file.contentAvailable) {
+            problems.push(`${where} targets lines of "${location.path}", whose content is not available`);
+        }
+        else if (location.endLine > file.lineCount) {
+            problems.push(`${where} targets 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));
+        for (const id of duplicates(diagram.nodes.map((node) => node.id)))
+            problems.push(`${where} has duplicate node id "${id}"`);
+        for (const link of diagram.links) {
+            for (const end of [link.from, link.to]) {
+                if (!nodeIds.has(end))
+                    problems.push(`${where} has a link ${link.from} -> ${link.to} to unknown node "${end}"`);
+            }
+        }
+        if (diagram.kind === "layers") {
+            for (const layer of duplicates(diagram.layers))
+                problems.push(`${where} declares layer "${layer}" twice`);
+            const layers = new Set(diagram.layers);
+            for (const node of diagram.nodes) {
+                if (node.layer === null)
+                    problems.push(`${where} node "${node.id}" needs a layer (kind is layers)`);
+                else if (!layers.has(node.layer)) {
+                    problems.push(`${where} node "${node.id}" uses layer "${node.layer}", which is not in layers [${diagram.layers.join(", ")}]`);
+                }
+            }
+        }
+    }
+    const findingIds = new Set(analysis.findings.map((finding) => finding.id));
+    const noteIds = new Set(analysis.notes.map((note) => note.id));
+    const review = analysis.review;
+    for (const id of review.selectedFindingIds) {
+        if (!findingIds.has(id))
+            problems.push(`review selects unknown finding "${id}"`);
+    }
+    for (const id of review.selectedNoteIds) {
+        if (!noteIds.has(id))
+            problems.push(`review selects unknown note "${id}"`);
+    }
+    if (review.state === "submitted" && (review.decision === null || review.submittedAt === null)) {
+        problems.push("a submitted review needs a decision and a submittedAt date");
+    }
+    if (review.state === "pending" && review.submittedAt !== null) {
+        problems.push("a pending review cannot have a submittedAt date");
+    }
+    return problems;
+}
+/** Lève une AnalysisError listant toutes les violations, s'il y en a. */
+export function assertInvariants(analysis) {
+    const problems = findInvariantViolations(analysis);
+    if (problems.length > 0) {
+        throw new AnalysisError(`Analysis "${analysis.id}" would become inconsistent: ${problems.join("; ")}.`);
+    }
+}
+/** Champ d'un fichier modifiable hors recalcul du snapshot. */
+const MUTABLE_FILE_FIELDS = new Set(["reviewed"]);
+/**
+ * Vérifie qu'une modification ne touche pas aux champs fixés par le snapshot
+ * (identité, dépôt, refs, commits, liste et métadonnées des fichiers hors
+ * `reviewed`). Seul le recalcul du snapshot les change.
+ */
+export function assertSnapshotFieldsUnchanged(before, after) {
+    const changed = [];
+    for (const field of ["id", "repoPath", "mode", "base", "head", "baseCommit", "headCommit", "snapshotAt", "createdAt"]) {
+        if (before[field] !== after[field])
+            changed.push(field);
+    }
+    if (before.files.length !== after.files.length) {
+        changed.push("files");
+    }
+    else {
+        before.files.forEach((file, index) => {
+            const next = after.files[index];
+            for (const key of Object.keys(file)) {
+                if (!MUTABLE_FILE_FIELDS.has(key) && file[key] !== next[key])
+                    changed.push(`files[${index}].${key}`);
+            }
+        });
+    }
+    if (changed.length > 0) {
+        throw new AnalysisError(`Cannot change ${changed.join(", ")} of analysis "${before.id}": these fields come from the diff snapshot. ` +
+            `Use refresh_analysis to recompute the snapshot.`);
+    }
+}

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

@@ -0,0 +1,30 @@
+import type { FileEntry } from "../../shared/schemas/analysis.schema.js";
+import type { DiffSnapshot } from "../../shared/schemas/diff.schema.js";
+export interface LocationRequest {
+    path: string;
+    startLine: number;
+    /** Dernière ligne incluse ; vaut `startLine` quand elle est omise. */
+    endLine?: number | null;
+}
+export interface ResolvedLocation {
+    path: string;
+    startLine: number;
+    endLine: number;
+    /** Texte exact des lignes visées, jointes par `\n`. */
+    anchorText: string;
+}
+/**
+ * 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.
+ */
+export declare function resolveLocation(snapshot: DiffSnapshot, files: FileEntry[], request: LocationRequest): ResolvedLocation;
+/**
+ * Vérifie l'emplacement d'une remarque : un fichier de l'analyse, et une ligne
+ * du côté « nouveau » quand `line` est fournie.
+ */
+export declare function assertNoteLocation(files: FileEntry[], location: {
+    path: string;
+    line: number | null;
+}): void;

package/dist/src/core/locations.js

@@ -0,0 +1,66 @@
+import { splitLines } from "../../shared/text.js";
+import { AnalysisError } from "./errors.js";
+/** Liste lisible des chemins d'une analyse, pour les messages d'erreur. */
+function describeFiles(files) {
+    if (files.length === 0)
+        return "the analysis has no changed files";
+    return `changed files: ${files.map((file) => file.path).join(", ")}`;
+}
+/** Raison pour laquelle le contenu d'un fichier n'est pas conservé dans le snapshot. */
+function unavailableReason(file) {
+    if (file.status === "deleted")
+        return "it is deleted";
+    if (file.binary)
+        return "it is binary";
+    return "it is larger than the snapshot size limit";
+}
+/**
+ * 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.
+ */
+export function resolveLocation(snapshot, files, request) {
+    const endLine = request.endLine ?? request.startLine;
+    const { path, startLine } = request;
+    const file = files.find((entry) => entry.path === path);
+    if (!file) {
+        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);
+    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).`);
+    }
+    const lines = splitLines(diff.newContent);
+    if (endLine > lines.length) {
+        throw new AnalysisError(`Lines ${startLine}-${endLine} are out of range for "${path}", which has ${lines.length} line(s) on the new side. ` +
+            `Use get_diff to read the new-side line numbers.`);
+    }
+    return { path, startLine, endLine, anchorText: lines.slice(startLine - 1, endLine).join("\n") };
+}
+/**
+ * Vérifie l'emplacement d'une remarque : un fichier de l'analyse, et une ligne
+ * du côté « nouveau » quand `line` est fournie.
+ */
+export function assertNoteLocation(files, location) {
+    const file = files.find((entry) => entry.path === location.path);
+    if (!file) {
+        throw new AnalysisError(`File "${location.path}" is not part of this analysis (${describeFiles(files)}).`);
+    }
+    if (location.line === null)
+        return;
+    if (!Number.isInteger(location.line) || location.line < 1) {
+        throw new AnalysisError(`Invalid line ${location.line} for "${location.path}": lines are 1-based integers.`);
+    }
+    if (!file.contentAvailable) {
+        throw new AnalysisError(`Cannot attach a note to a line of "${location.path}": its content is not available because ${unavailableReason(file)}. ` +
+            `Attach the note to the whole file instead.`);
+    }
+    if (location.line > file.lineCount) {
+        throw new AnalysisError(`Line ${location.line} is out of range for "${location.path}", which has ${file.lineCount} line(s) on the new side.`);
+    }
+}

package/dist/src/core/log-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Répertoire des logs : MCP_LOG_DIR s'il est renseigné, sinon <dataDir>/logs.
+ * Lu depuis process.env au démarrage, avant le chargement du .env du package :
+ * la variable vient donc de la déclaration du serveur dans le client MCP.
+ */
+export declare function resolveLogDir(rootDir: string): string;