@imenam/mcp-feature-analyzer 1.0.0

package/dist/src/tools/inputs.js

@@ -0,0 +1,40 @@
+import { ITEM_ID_PATTERN } from "../../shared/schemas/analysis.schema.js";
+import { has, nullableString, optionalPositiveInt } from "./types.js";
+/**
+ * Lit `path`, `start_line` et `end_line`. `path` et `start_line` vont ensemble ;
+ * `end_line` vaut `start_line` quand il est omis. `path: null` retire l'emplacement.
+ */
+export function readLocation(args, prefix = "") {
+    const path = nullableString(args, "path", prefix);
+    const startLine = optionalPositiveInt(args, "start_line", prefix);
+    const endLine = optionalPositiveInt(args, "end_line", prefix);
+    if (path === null) {
+        if (startLine !== undefined || endLine !== undefined) {
+            throw new Error(`"${prefix}path" is null (location removed), so "start_line" and "end_line" cannot be set.`);
+        }
+        return null;
+    }
+    if (path === undefined) {
+        if (startLine !== undefined || endLine !== undefined) {
+            throw new Error(`"${prefix}start_line" and "${prefix}end_line" need "${prefix}path": give the file they refer to.`);
+        }
+        return undefined;
+    }
+    if (startLine === undefined) {
+        throw new Error(`"${prefix}start_line" is required with "${prefix}path": give the first new-side line (see get_diff).`);
+    }
+    if (endLine !== undefined && endLine < startLine) {
+        throw new Error(`"${prefix}end_line" (${endLine}) must be >= "${prefix}start_line" (${startLine}).`);
+    }
+    return { path, startLine, endLine };
+}
+/** Lit un identifiant d'élément facultatif fourni par l'agent. */
+export function readItemId(args, field, prefix = "") {
+    if (!has(args, field))
+        return undefined;
+    const value = args[field];
+    if (typeof value !== "string" || !ITEM_ID_PATTERN.test(value)) {
+        throw new Error(`"${prefix}${field}" must contain only letters, digits, '_' or '-' (1 to 64 characters).`);
+    }
+    return value;
+}

package/dist/src/tools/list-analyses.d.ts

@@ -0,0 +1,8 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type ToolResult } from "./types.js";
+/**
+ * Liste les analyses regroupées par projet (projet le plus récemment modifié en
+ * premier, puis analyses de la plus récente à la plus ancienne), éventuellement
+ * limitées à un projet, et les fichiers illisibles.
+ */
+export declare function listAnalyses(store: AnalysisStore, args: Args): ToolResult;

package/dist/src/tools/list-analyses.js

@@ -0,0 +1,71 @@
+import { REVIEW_PROGRESS_STATES } from "../../shared/schemas/analysis.schema.js";
+import { progressLabel, progressStateLabel, refsLabel, severityCountsLabel } from "./format.js";
+import { optionalString, rejectUnknownFields, textResult } from "./types.js";
+/** Analyses regroupées par projet, les projets triés par leur analyse la plus récente. */
+function groupByProject(analyses) {
+    const groups = new Map();
+    for (const summary of analyses) {
+        const group = groups.get(summary.project);
+        if (group)
+            group.push(summary);
+        else
+            groups.set(summary.project, [summary]);
+    }
+    return groups;
+}
+/** `2 analysis(es): 1 in progress, 1 submitted`. */
+function projectCounts(analyses) {
+    const counts = REVIEW_PROGRESS_STATES.map((state) => [state, analyses.filter((summary) => summary.progress.state === state).length])
+        .filter(([, count]) => count > 0)
+        .map(([state, count]) => `${count} ${progressStateLabel(state)}`);
+    return `${analyses.length} analysis(es): ${counts.join(", ")}`;
+}
+function analysisLines(summary) {
+    const feedback = summary.progress.state === "submitted" ? " — read it with get_review_feedback" : "";
+    return [
+        `- ${summary.id} — "${summary.title}"`,
+        `  ${refsLabel(summary)} | files reviewed ${summary.reviewedCount}/${summary.fileCount} | ` +
+            `open findings: ${severityCountsLabel(summary.openFindings)} | diagrams: ${summary.diagramCount}`,
+        `  review: ${progressLabel(summary.progress)}${feedback} | updated ${summary.updatedAt}`,
+    ];
+}
+/**
+ * Liste les analyses regroupées par projet (projet le plus récemment modifié en
+ * premier, puis analyses de la plus récente à la plus ancienne), éventuellement
+ * limitées à un projet, et les fichiers illisibles.
+ */
+export function listAnalyses(store, args) {
+    rejectUnknownFields(args, ["project"]);
+    const project = optionalString(args, "project");
+    const { analyses, unreadable } = store.list();
+    const groups = groupByProject(analyses);
+    const lines = [];
+    if (project !== undefined && !groups.has(project)) {
+        const known = [...groups.keys()];
+        throw new Error(known.length === 0
+            ? `Unknown project "${project}": there are no analyses yet. Create one with create_analysis.`
+            : `Unknown project "${project}". Existing projects: ${known.map((name) => `"${name}"`).join(", ")}. ` +
+                `Call list_analyses without project to see them all, or create_analysis to start a new project.`);
+    }
+    if (analyses.length === 0) {
+        lines.push("No analyses yet. Create one with create_analysis once the feature is developed: it freezes the diff of a branch or of the working tree for human review.");
+    }
+    else {
+        const shown = project === undefined ? [...groups] : [[project, groups.get(project)]];
+        const total = shown.reduce((sum, [, list]) => sum + list.length, 0);
+        lines.push(project === undefined
+            ? `${total} analysis(es) in ${groups.size} project(s), most recently updated first:`
+            : `${total} analysis(es) in project "${project}", most recently updated first:`);
+        for (const [name, list] of shown) {
+            lines.push("", `## Project "${name}" (${projectCounts(list)})`);
+            for (const summary of list)
+                lines.push(...analysisLines(summary));
+        }
+        lines.push("", "To continue the review of a feature, reuse its analysis: update_analysis to rewrite the overview and summary, " +
+            "refresh_analysis after changing the code. Create a new analysis only for another feature or another diff.");
+    }
+    if (unreadable.length > 0) {
+        lines.push("", `${unreadable.length} analysis file(s) could not be read. Fix the file or remove it with delete_analysis:`, ...unreadable.map((entry) => `- ${entry.id}: ${entry.error}`));
+    }
+    return textResult(lines.join("\n"));
+}

package/dist/src/tools/refresh-analysis.d.ts

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

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

@@ -0,0 +1,39 @@
+import { computeSnapshot } from "../core/git.js";
+import { snapshotLabel } from "./format.js";
+import { rejectUnknownFields, requireString, textResult } from "./types.js";
+/**
+ * Recalcule le snapshot avec le dépôt, le mode et les refs de l'analyse ; la
+ * revue repart à l'état `pending` sans décision, sélection ni prompt.
+ */
+export async function refreshAnalysis(store, args) {
+    rejectUnknownFields(args, ["analysis_id"]);
+    const id = requireString(args, "analysis_id");
+    const current = store.get(id);
+    const computed = await computeSnapshot({
+        repoPath: current.repoPath,
+        mode: current.mode,
+        base: current.base,
+        head: current.head,
+    });
+    const { analysis, stats, previousReview } = store.replaceSnapshot(id, "agent", computed);
+    const outdated = analysis.findings.filter((finding) => finding.status === "outdated");
+    const lines = [
+        `Refreshed analysis "${analysis.title}" (${analysis.id}).`,
+        `Diff: ${snapshotLabel(analysis)}`,
+        `Files: ${stats.fileCount} (${stats.filesAdded} new in the diff, ${stats.filesRemoved} no longer in it).`,
+        `Reviewed files: ${stats.reviewedKept} kept (diff unchanged), ${stats.reviewedReset} reset to unreviewed (diff changed).`,
+        `Findings: ${stats.findingsOutdated} became outdated (their lines changed or left the diff), ` +
+            `${stats.findingsRestored} back to open (their lines match again); ${outdated.length} outdated in total.`,
+    ];
+    if (previousReview.state === "submitted") {
+        lines.push(`Review: the previous feedback (decision ${previousReview.decision}, submitted at ${previousReview.submittedAt}) was discarded; the review is pending again.`);
+    }
+    else {
+        lines.push("Review: pending; the previous feedback, decision and selection in progress were discarded.");
+    }
+    lines.push("", "Next steps:", "- Re-read the changed files with get_diff.", "- For each outdated finding: re-anchor it with update_finding (a new location reopens it), or remove it with delete_findings if it is solved.", "- Ask the user to review the analysis again in the GUI.");
+    if (outdated.length > 0) {
+        lines.push("", "Outdated findings:", ...outdated.map((finding) => `  ${finding.id} [${finding.severity}] ${finding.title}`));
+    }
+    return { result: textResult(lines.join("\n")), analysisId: analysis.id };
+}

package/dist/src/tools/set-diagram.d.ts

@@ -0,0 +1,16 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type NodeShape, type NodeStatus } from "../../shared/schemas/analysis.schema.js";
+import { type Args, type MutationResult } from "./types.js";
+export declare const NODE_INPUT_FIELDS: readonly ["id", "label", "shape", "status", "layer", "detail", "path", "line"];
+export declare const LINK_INPUT_FIELDS: readonly ["from", "to", "label"];
+/** Forme d'un nœud quand l'agent n'en donne pas. */
+export declare const DEFAULT_NODE_SHAPE: NodeShape;
+/** Statut d'un nœud quand l'agent n'en donne pas. */
+export declare const DEFAULT_NODE_STATUS: NodeStatus;
+/**
+ * Crée ou remplace entièrement un schéma. Nœuds, couches et liens sont validés
+ * ensemble, une carte mentale doit former un arbre ; toutes les erreurs sont
+ * renvoyées d'un coup et rien n'est écrit. Le résultat rend compte des
+ * croisements du tracé, sans refuser l'écriture.
+ */
+export declare function setDiagram(store: AnalysisStore, args: Args): MutationResult;

package/dist/src/tools/set-diagram.js

@@ -0,0 +1,207 @@
+import { AnalysisError } from "../core/errors.js";
+import { itemId } from "../core/ids.js";
+import { DIAGRAM_KINDS, NODE_SHAPES, NODE_STATUSES, } from "../../shared/schemas/analysis.schema.js";
+import { layoutDiagram } from "../../shared/diagram-layout.js";
+import { diagramQuality } from "../../shared/diagram-quality.js";
+import { mindmapProblems } from "../../shared/mindmap-tree.js";
+import { readItemId } from "./inputs.js";
+import { has, nullableString, optionalEnum, optionalPositiveInt, optionalString, rejectUnknownFields, requireArray, requireEnum, requireObject, requireString, requireStringArray, textResult, } from "./types.js";
+export const NODE_INPUT_FIELDS = ["id", "label", "shape", "status", "layer", "detail", "path", "line"];
+export const LINK_INPUT_FIELDS = ["from", "to", "label"];
+/** Forme d'un nœud quand l'agent n'en donne pas. */
+export const DEFAULT_NODE_SHAPE = "box";
+/** Statut d'un nœud quand l'agent n'en donne pas. */
+export const DEFAULT_NODE_STATUS = "existing";
+/**
+ * Vérifie l'emplacement d'un nœud : un fichier modifié de l'analyse et, quand
+ * `line` est fournie, une ligne du côté « nouveau » de ce fichier.
+ */
+function assertNodeLocation(files, location) {
+    const file = files.find((entry) => entry.path === location.path);
+    if (!file) {
+        throw new Error(`"${location.path}" is not a changed file of this analysis, so the GUI cannot open it. ` +
+            `Omit path for code outside the diff and name the file in detail instead.`);
+    }
+    if (location.line === null)
+        return;
+    if (!file.contentAvailable) {
+        throw new Error(`"${location.path}" has no new-side content (deleted, binary or too large): omit line and keep path only.`);
+    }
+    if (location.line > file.lineCount) {
+        throw new Error(`line ${location.line} is out of range for "${location.path}", which has ${file.lineCount} line(s) on the new side (see get_diff).`);
+    }
+}
+/** Nombre de nœuds au-delà duquel un schéma devient difficile à lire. */
+const MAX_READABLE_NODES = 12;
+/** Description anglaise d'un problème d'arborescence d'une carte mentale. */
+function mindmapProblemText(problem) {
+    const list = (ids) => ids.map((id) => `"${id}"`).join(", ");
+    switch (problem.kind) {
+        case "self_loop":
+            return `node "${problem.node}" links to itself.`;
+        case "no_root":
+            return "every node has an incoming link, so there is no root: the central subject must have none.";
+        case "several_roots":
+            return `${problem.roots.length} nodes have no incoming link (${list(problem.roots)}); keep one root and link the others below it.`;
+        case "several_parents":
+            return `node "${problem.node}" has ${problem.parents.length} parents (${list(problem.parents)}); keep a single link into it.`;
+        case "cycle":
+            return `the links form a cycle ${problem.nodes.join(" -> ")}.`;
+        case "unreachable":
+            return `node(s) ${list(problem.nodes)} cannot be reached from the root "${problem.root}".`;
+    }
+}
+function linkLabel(ref) {
+    return `links[${ref.index}] ${ref.from} -> ${ref.to}`;
+}
+/** Compte rendu du contrôle de tracé et conseils pour supprimer les croisements. */
+function qualityLines(quality, kind, nodeCount) {
+    const lines = [];
+    if (quality.crossings.length === 0 && quality.nodeOverlaps.length === 0) {
+        lines.push("Layout check: No crossing.");
+    }
+    else {
+        lines.push(`Layout check: ${quality.crossings.length} link crossing(s), ${quality.nodeOverlaps.length} link(s) through a node. ` +
+            `The diagram is saved, but the reviewer expects none; fix it and send it again:`, ...quality.crossings.map((crossing) => `- ${linkLabel(crossing.a)} crosses ${linkLabel(crossing.b)}`), ...quality.nodeOverlaps.map((overlap) => `- ${linkLabel(overlap.link)} passes through node "${overlap.node}"`), "How to fix:", "- Reorder the nodes: the declaration order is the initial order of each rank or column, so declare them in reading order, " +
+            "with the nodes that link to each other next to each other.", "- Split the diagram: one subject per diagram, 5 to 12 nodes each.");
+        if (kind === "flow") {
+            lines.push("- Drop shortcut links that skip steps and loops back to earlier steps, or show dependencies as a layers diagram instead.");
+        }
+        else if (kind === "layers") {
+            lines.push("- Order the layers so links run between neighbouring columns, move a node to the layer it belongs to, " +
+                "and avoid links between nodes of the same column that are not adjacent.");
+        }
+    }
+    if (nodeCount > MAX_READABLE_NODES) {
+        lines.push(`Note: ${nodeCount} nodes; keep a diagram between 5 and ${MAX_READABLE_NODES} nodes and split a bigger picture into several diagrams.`);
+    }
+    return lines;
+}
+/**
+ * Crée ou remplace entièrement un schéma. Nœuds, couches et liens sont validés
+ * ensemble, une carte mentale doit former un arbre ; toutes les erreurs sont
+ * renvoyées d'un coup et rien n'est écrit. Le résultat rend compte des
+ * croisements du tracé, sans refuser l'écriture.
+ */
+export function setDiagram(store, args) {
+    rejectUnknownFields(args, ["analysis_id", "diagram_id", "title", "kind", "layers", "nodes", "links"]);
+    const id = requireString(args, "analysis_id");
+    const requestedId = readItemId(args, "diagram_id");
+    const title = requireString(args, "title");
+    const kind = requireEnum(args, "kind", DIAGRAM_KINDS);
+    const nodeItems = requireArray(args, "nodes", 1);
+    const linkItems = has(args, "links") ? requireArray(args, "links") : [];
+    let layers = [];
+    if (kind === "layers") {
+        if (!has(args, "layers")) {
+            throw new Error(`"layers" is required when kind is layers: list the column names from left to right.`);
+        }
+        layers = requireStringArray(args, "layers", 1);
+        const repeated = layers.filter((layer, index) => layers.indexOf(layer) !== index);
+        if (repeated.length > 0)
+            throw new Error(`"layers" lists ${[...new Set(repeated)].join(", ")} more than once.`);
+    }
+    else if (has(args, "layers")) {
+        throw new Error(`"layers" is only used when kind is layers (kind is ${kind}): remove it.`);
+    }
+    const analysis = store.get(id);
+    const errors = [];
+    const nodes = [];
+    const nodeIds = new Set();
+    nodeItems.forEach((raw, index) => {
+        const where = `nodes[${index}]`;
+        try {
+            const item = requireObject(raw, where);
+            rejectUnknownFields(item, NODE_INPUT_FIELDS, `${where}.`);
+            const nodeId = readItemId(item, "id", `${where}.`);
+            if (nodeId === undefined)
+                throw new Error(`"${where}.id" is required: links refer to nodes by id.`);
+            if (nodeIds.has(nodeId))
+                throw new Error(`node id "${nodeId}" appears twice.`);
+            nodeIds.add(nodeId);
+            const label = requireString(item, "label", `${where}.`);
+            const shape = optionalEnum(item, "shape", NODE_SHAPES, `${where}.`) ?? DEFAULT_NODE_SHAPE;
+            const status = optionalEnum(item, "status", NODE_STATUSES, `${where}.`) ?? DEFAULT_NODE_STATUS;
+            const detail = nullableString(item, "detail", `${where}.`) ?? null;
+            const layer = optionalString(item, "layer", `${where}.`) ?? null;
+            if (kind === "layers") {
+                if (layer === null)
+                    throw new Error(`"${where}.layer" is required when kind is layers: use one of ${layers.join(", ")}.`);
+                if (!layers.includes(layer)) {
+                    throw new Error(`"${where}.layer" is "${layer}", which is not declared in layers (${layers.join(", ")}).`);
+                }
+            }
+            else if (layer !== null) {
+                throw new Error(`"${where}.layer" is only used when kind is layers (kind is ${kind}): remove it.`);
+            }
+            const path = optionalString(item, "path", `${where}.`);
+            const line = optionalPositiveInt(item, "line", `${where}.`);
+            if (path === undefined && line !== undefined) {
+                throw new Error(`"${where}.line" needs "${where}.path": give the file it refers to.`);
+            }
+            const location = path === undefined ? null : { path, line: line ?? null };
+            if (location)
+                assertNodeLocation(analysis.files, location);
+            nodes.push({ id: nodeId, label, shape, status, layer, detail, location });
+        }
+        catch (err) {
+            errors.push(`- ${where}: ${err.message}`);
+        }
+    });
+    const links = [];
+    linkItems.forEach((raw, index) => {
+        const where = `links[${index}]`;
+        try {
+            const item = requireObject(raw, where);
+            rejectUnknownFields(item, LINK_INPUT_FIELDS, `${where}.`);
+            const from = requireString(item, "from", `${where}.`);
+            const to = requireString(item, "to", `${where}.`);
+            const label = nullableString(item, "label", `${where}.`) ?? null;
+            const unknown = [from, to].filter((end) => !nodeIds.has(end));
+            if (unknown.length > 0) {
+                throw new Error(`links ${from} -> ${to}, but node(s) ${[...new Set(unknown)].join(", ")} are not in "nodes".`);
+            }
+            links.push({ from, to, label });
+        }
+        catch (err) {
+            errors.push(`- ${where}: ${err.message}`);
+        }
+    });
+    const treeProblems = kind === "mindmap" ? mindmapProblems({ nodes, links }) : [];
+    for (const problem of treeProblems)
+        errors.push(`- mindmap: ${mindmapProblemText(problem)}`);
+    if (errors.length > 0) {
+        const tree = treeProblems.length > 0
+            ? "\nA mindmap is a tree: one root (the central subject), exactly one incoming link for every other node, no cycle. " +
+                "Use a flow or layers diagram for a graph."
+            : "";
+        throw new AnalysisError(`The diagram was not saved: ${errors.length} problem(s). Fix them and send the whole diagram again.\n${errors.join("\n")}${tree}`);
+    }
+    const draft = { id: requestedId ?? "draft", title, kind, layers, nodes, links, updatedAt: new Date().toISOString() };
+    let quality;
+    try {
+        quality = diagramQuality(draft, layoutDiagram(draft));
+    }
+    catch (err) {
+        throw new AnalysisError(`The diagram was not saved: it cannot be laid out (${err.message}).`);
+    }
+    let replaced = false;
+    let diagramId = "";
+    const updated = store.mutate(id, "agent", (draft) => {
+        diagramId = requestedId ?? itemId("diagram", new Set(draft.diagrams.map((diagram) => diagram.id)));
+        const diagram = { id: diagramId, title, kind, layers, nodes, links, updatedAt: new Date().toISOString() };
+        const index = draft.diagrams.findIndex((entry) => entry.id === diagramId);
+        replaced = index !== -1;
+        if (replaced)
+            draft.diagrams[index] = diagram;
+        else
+            draft.diagrams.push(diagram);
+    });
+    const lines = [
+        `${replaced ? "Replaced" : "Created"} diagram ${diagramId} "${title}" (${kind}, ${nodes.length} node(s), ${links.length} link(s)) ` +
+            `in "${updated.title}" (${updated.id}).`,
+        ...qualityLines(quality, kind, nodes.length),
+        `To change it, call set_diagram again with diagram_id "${diagramId}" and the complete diagram.`,
+    ];
+    return { result: textResult(lines.join("\n")), analysisId: updated.id };
+}

package/dist/src/tools/types.d.ts

@@ -0,0 +1,52 @@
+/** Forme de réponse attendue par le SDK MCP pour un appel d'outil. */
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/** Résultat d'un outil qui modifie une analyse : le texte et l'analyse concernée, à notifier. */
+export interface MutationResult {
+    result: ToolResult;
+    analysisId: string;
+}
+/** Arguments d'un outil ou d'un élément de tableau. */
+export type Args = Record<string, unknown> | undefined;
+export declare function textResult(text: string): ToolResult;
+export declare function errorResult(text: string): ToolResult;
+/** Vrai si le champ est présent (ni absent ni `undefined`). */
+export declare function has(args: Args, field: string): boolean;
+/** Lit un argument texte obligatoire, rogné ; lève une erreur s'il est absent ou vide. */
+export declare function requireString(args: Args, field: string, prefix?: string): string;
+/** Lit un argument texte facultatif, rogné ; `undefined` s'il est absent, erreur s'il est vide ou d'un autre type. */
+export declare function optionalString(args: Args, field: string, prefix?: string): string | undefined;
+/**
+ * Lit un argument texte facultatif qui accepte `null` pour effacer la valeur :
+ * `undefined` s'il est absent, `null` s'il vaut null, le texte rogné sinon.
+ */
+export declare function nullableString(args: Args, field: string, prefix?: string): string | null | undefined;
+/** Lit un texte obligatoire non blanc, conservé tel quel (indentation et fins de ligne comprises). */
+export declare function requireText(args: Args, field: string, prefix?: string): string;
+/**
+ * Lit un texte facultatif conservé tel quel, `null` pour effacer : `undefined`
+ * s'il est absent. `allowEmpty` accepte la chaîne vide.
+ */
+export declare function nullableText(args: Args, field: string, prefix?: string, allowEmpty?: boolean): string | null | undefined;
+/** Lit une valeur parmi `values` ; erreur explicite listant les valeurs admises. */
+export declare function requireEnum<T extends string>(args: Args, field: string, values: readonly T[], prefix?: string): T;
+/** Lit une valeur facultative parmi `values` ; `undefined` si elle est absente. */
+export declare function optionalEnum<T extends string>(args: Args, field: string, values: readonly T[], prefix?: string): T | undefined;
+/** Lit un entier strictement positif obligatoire. */
+export declare function requirePositiveInt(args: Args, field: string, prefix?: string): number;
+/** Lit un entier strictement positif facultatif ; `undefined` s'il est absent. */
+export declare function optionalPositiveInt(args: Args, field: string, prefix?: string): number | undefined;
+/** Lit un tableau obligatoire, d'au moins `minItems` éléments. */
+export declare function requireArray(args: Args, field: string, minItems?: number, prefix?: string): unknown[];
+/** Vérifie qu'un élément de tableau est un objet et le renvoie. */
+export declare function requireObject(value: unknown, where: string): Record<string, unknown>;
+/** Lit un tableau de textes non vides, rognés. */
+export declare function requireStringArray(args: Args, field: string, minItems?: number, prefix?: string): string[];
+/** Lève une erreur si `args` contient des champs hors de `allowed` : une faute de frappe ne passe pas inaperçue. */
+export declare function rejectUnknownFields(args: Args, allowed: readonly string[], prefix?: string): void;

package/dist/src/tools/types.js

@@ -0,0 +1,133 @@
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function errorResult(text) {
+    return { content: [{ type: "text", text: `Error: ${text}` }], isError: true };
+}
+/** Nom d'un champ dans les messages d'erreur : `prefix` situe un élément de tableau, par ex. `findings[2].`. */
+function label(field, prefix) {
+    return `"${prefix}${field}"`;
+}
+/** Vrai si le champ est présent (ni absent ni `undefined`). */
+export function has(args, field) {
+    return args !== undefined && args[field] !== undefined;
+}
+/** Lit un argument texte obligatoire, rogné ; lève une erreur s'il est absent ou vide. */
+export function requireString(args, field, prefix = "") {
+    const value = args?.[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${label(field, prefix)} is required and must be a non-empty string.`);
+    }
+    return value.trim();
+}
+/** Lit un argument texte facultatif, rogné ; `undefined` s'il est absent, erreur s'il est vide ou d'un autre type. */
+export function optionalString(args, field, prefix = "") {
+    if (!has(args, field))
+        return undefined;
+    return requireString(args, field, prefix);
+}
+/**
+ * Lit un argument texte facultatif qui accepte `null` pour effacer la valeur :
+ * `undefined` s'il est absent, `null` s'il vaut null, le texte rogné sinon.
+ */
+export function nullableString(args, field, prefix = "") {
+    if (!has(args, field))
+        return undefined;
+    if (args[field] === null)
+        return null;
+    const value = args[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${label(field, prefix)} must be a non-empty string, or null to clear it.`);
+    }
+    return value.trim();
+}
+/** Lit un texte obligatoire non blanc, conservé tel quel (indentation et fins de ligne comprises). */
+export function requireText(args, field, prefix = "") {
+    const value = args?.[field];
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${label(field, prefix)} is required and must be a non-empty string.`);
+    }
+    return value;
+}
+/**
+ * Lit un texte facultatif conservé tel quel, `null` pour effacer : `undefined`
+ * s'il est absent. `allowEmpty` accepte la chaîne vide.
+ */
+export function nullableText(args, field, prefix = "", allowEmpty = false) {
+    if (!has(args, field))
+        return undefined;
+    const value = args[field];
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || (!allowEmpty && value.trim() === "")) {
+        const expected = allowEmpty ? "a string" : "a non-empty string";
+        throw new Error(`${label(field, prefix)} must be ${expected}, or null to clear it.`);
+    }
+    return value;
+}
+/** Lit une valeur parmi `values` ; erreur explicite listant les valeurs admises. */
+export function requireEnum(args, field, values, prefix = "") {
+    const value = args?.[field];
+    if (typeof value !== "string" || !values.includes(value)) {
+        const got = value === undefined ? "nothing" : JSON.stringify(value);
+        throw new Error(`${label(field, prefix)} must be one of ${values.join(", ")} (got ${got}).`);
+    }
+    return value;
+}
+/** Lit une valeur facultative parmi `values` ; `undefined` si elle est absente. */
+export function optionalEnum(args, field, values, prefix = "") {
+    if (!has(args, field))
+        return undefined;
+    return requireEnum(args, field, values, prefix);
+}
+/** Lit un entier strictement positif obligatoire. */
+export function requirePositiveInt(args, field, prefix = "") {
+    const value = args?.[field];
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+        throw new Error(`${label(field, prefix)} is required and must be an integer >= 1 (got ${JSON.stringify(value) ?? "nothing"}).`);
+    }
+    return value;
+}
+/** Lit un entier strictement positif facultatif ; `undefined` s'il est absent. */
+export function optionalPositiveInt(args, field, prefix = "") {
+    if (!has(args, field))
+        return undefined;
+    return requirePositiveInt(args, field, prefix);
+}
+/** Lit un tableau obligatoire, d'au moins `minItems` éléments. */
+export function requireArray(args, field, minItems = 0, prefix = "") {
+    const value = args?.[field];
+    if (!Array.isArray(value)) {
+        throw new Error(`${label(field, prefix)} is required and must be an array.`);
+    }
+    if (value.length < minItems) {
+        throw new Error(`${label(field, prefix)} must contain at least ${minItems} item(s).`);
+    }
+    return value;
+}
+/** Vérifie qu'un élément de tableau est un objet et le renvoie. */
+export function requireObject(value, where) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`"${where}" must be an object.`);
+    }
+    return value;
+}
+/** Lit un tableau de textes non vides, rognés. */
+export function requireStringArray(args, field, minItems = 0, prefix = "") {
+    return requireArray(args, field, minItems, prefix).map((item, index) => {
+        if (typeof item !== "string" || item.trim() === "") {
+            throw new Error(`${label(`${field}[${index}]`, prefix)} must be a non-empty string.`);
+        }
+        return item.trim();
+    });
+}
+/** Lève une erreur si `args` contient des champs hors de `allowed` : une faute de frappe ne passe pas inaperçue. */
+export function rejectUnknownFields(args, allowed, prefix = "") {
+    if (!args)
+        return;
+    const unknown = Object.keys(args).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0) {
+        const where = prefix === "" ? "" : ` in ${prefix.replace(/\.$/, "")}`;
+        throw new Error(`Unknown field(s)${where}: ${unknown.join(", ")}. Accepted fields: ${allowed.join(", ")}.`);
+    }
+}

package/dist/src/tools/update-analysis.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisStore } from "../core/analysis-store.js";
+import { type Args, type MutationResult } from "./types.js";
+/** Met à jour le titre, le projet, la vue d'ensemble, le résumé et la demande initiale d'une analyse. */
+export declare function updateAnalysis(store: AnalysisStore, args: Args): MutationResult;