@imenam/mcp-documentor 1.0.62 → 1.0.63

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

@@ -65,6 +65,8 @@ export interface DocSummary {
     updatedAt: string;
     tags: string[];
     isStale: boolean;
+    /** True when tracked entries have no snapshot and freshness cannot be computed. */
+    isBroken?: boolean;
     folder?: string;
 }
 export interface DocMatch {
@@ -81,11 +83,13 @@ export declare const FreshnessReportSchema: z.ZodObject<{
         stale: "stale";
         no_tracking: "no_tracking";
         unverifiable: "unverifiable";
+        broken: "broken";
     }>;
     modified: z.ZodArray<z.ZodString>;
     missing: z.ZodArray<z.ZodString>;
     unchanged: z.ZodArray<z.ZodString>;
     anchors_lost: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    broken: z.ZodDefault<z.ZodArray<z.ZodString>>;
     total: z.ZodNumber;
 }, z.core.$strip>;
 export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;

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

@@ -36,11 +36,13 @@ export const DocSchema = z.object({
     updatedAt: z.string(),
 });
 export const FreshnessReportSchema = z.object({
-    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable"]),
+    status: z.enum(["up_to_date", "stale", "no_tracking", "unverifiable", "broken"]),
     modified: z.array(z.string()),
     missing: z.array(z.string()),
     unchanged: z.array(z.string()),
     anchors_lost: z.array(z.string()).default([]),
+    /** Entries with neither sections nor contentHash (pre hash-based tracking) — cannot be checked until re-tracked. */
+    broken: z.array(z.string()).default([]),
     total: z.number(),
 });
 export const CreateDocArgsSchema = z.object({

package/dist/src/index.js

@@ -159,15 +159,9 @@ async function handleGetInitialState(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id); // doc.id is now the full path
             if (full && full.tracked_files.length > 0) {
-                // A doc whose freshness cannot be computed (legacy hash-less entries)
-                // needs attention: surface it as stale rather than crashing the view.
-                try {
-                    const report = computeFreshness(full.tracked_files, config.currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, config.currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         const bundles = storageEngine.getBundles();
@@ -204,13 +198,9 @@ async function handleUpdateProject(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                try {
-                    const report = computeFreshness(full.tracked_files, project);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, project);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -250,13 +240,9 @@ async function handleListDocs(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                try {
-                    const report = computeFreshness(full.tracked_files, currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({
@@ -368,15 +354,9 @@ async function handleCreateDocIPC(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                // A doc whose freshness cannot be computed (legacy hash-less entries)
-                // needs attention: surface it as stale rather than crashing the view.
-                try {
-                    const report = computeFreshness(full.tracked_files, config.currentProject);
-                    doc.isStale = report.status === "stale";
-                }
-                catch {
-                    doc.isStale = true;
-                }
+                const report = computeFreshness(full.tracked_files, config.currentProject);
+                doc.isStale = report.status === "stale" || report.status === "broken";
+                doc.isBroken = report.status === "broken";
             }
         }
         broadcastToGUI({

package/dist/src/tools/check-freshness.js

@@ -8,12 +8,13 @@ export function computeFileHash(absolutePath) {
 }
 export function computeFreshness(trackedFiles, project) {
     if (!trackedFiles || trackedFiles.length === 0) {
-        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], total: 0 };
+        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], total: 0 };
     }
     const modified = [];
     const missing = [];
     const unchanged = [];
     const anchors_lost = [];
+    const broken = [];
     for (const tracked of trackedFiles) {
         // A relative path with no code root configured on this machine is not
         // resolvable here — count it as absent so we end up "unverifiable" rather
@@ -61,8 +62,10 @@ export function computeFreshness(trackedFiles, project) {
         }
         else {
             // Hash comparison is the only freshness system. An entry with neither
-            // sections nor contentHash predates it and cannot be checked.
-            throw new Error(`Tracked file "${tracked.path}" has no contentHash and no sections — it predates hash-based tracking. Call refresh_file_snapshot on this doc to snapshot it, or re-declare it via update_doc.`);
+            // sections nor contentHash predates it and cannot be checked — it is
+            // reported as broken (never checked by any other means) so readers can
+            // still expose the doc and its tracked list to the agent for re-tracking.
+            broken.push(tracked.path);
         }
     }
     // When every tracked file is absent, the source code simply isn't present on
@@ -72,15 +75,18 @@ export function computeFreshness(trackedFiles, project) {
     // change signal (likely deletions) and still counts as stale.
     const allMissing = missing.length === trackedFiles.length;
     if (allMissing) {
-        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, total: trackedFiles.length };
+        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, broken, total: trackedFiles.length };
     }
     const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
+    // Broken tracking outranks everything: no freshness verdict is trustworthy
+    // until the broken entries are re-tracked.
     return {
-        status: isStale ? "stale" : "up_to_date",
+        status: broken.length > 0 ? "broken" : isStale ? "stale" : "up_to_date",
         modified,
         missing,
         unchanged,
         anchors_lost,
+        broken,
         total: trackedFiles.length,
     };
 }
@@ -91,11 +97,23 @@ export function formatFreshnessReport(title, report) {
     if (report.status === "unverifiable") {
         return `UNVERIFIABLE: "${title}" — none of the ${report.total} tracked file(s) are present on this machine, so freshness cannot be checked here. This is expected when the documentation is cloned without its source codebase.`;
     }
-    let text = report.status === "stale"
-        ? `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`
-        : `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    let text;
+    if (report.status === "broken") {
+        text = `BROKEN TRACKING: "${title}" — some tracked entries have no content snapshot and cannot be checked.\n`;
+    }
+    else if (report.status === "stale") {
+        text = `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`;
+    }
+    else {
+        text = `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+    }
     const anchorLostCount = report.anchors_lost?.length ?? 0;
-    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    const brokenCount = report.broken?.length ?? 0;
+    text += `\nSummary: ${report.modified.length} modified, ${report.missing.length} missing, ${anchorLostCount} with lost anchors, ${brokenCount} with broken tracking, ${report.unchanged.length} unchanged out of ${report.total} tracked file(s).`;
+    if (brokenCount > 0) {
+        text += `\n\n⚠ Files with broken tracking — no snapshot to compare against:\n${report.broken.map((f) => `  - ${f}`).join("\n")}`;
+        text += `\n  → These entries predate hash-based tracking. Re-read the source files and re-declare them in tracked_files via update_doc, or call refresh_file_snapshot if the doc content is still accurate.`;
+    }
     if (report.modified.length > 0) {
         text += `\n\nModified files (call refresh_file_snapshot to acknowledge):\n${report.modified.map((f) => `  - ${f}`).join("\n")}`;
     }
@@ -125,16 +143,12 @@ async function scanProjectFreshness(storageEngine, project) {
         const doc = await storageEngine.getDoc(summary.id, project);
         if (!doc)
             continue;
-        let report;
-        try {
-            report = computeFreshness(doc.tracked_files, project);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            scan.broken.push(`  - **${doc.title}** [${doc.id}]: ${message}`);
-            continue;
+        const report = computeFreshness(doc.tracked_files, project);
+        if (report.status === "broken") {
+            const files = report.broken.map((f) => `    • no snapshot: ${f}`).join("\n");
+            scan.broken.push(`  - **${doc.title}** [${doc.id}]\n${files}`);
         }
-        if (report.status === "no_tracking") {
+        else if (report.status === "no_tracking") {
             scan.noTracking.push(doc.title);
         }
         else if (report.status === "unverifiable") {

package/dist/src/tools/get-doc-metadata.js

@@ -13,6 +13,8 @@ export async function getDocMetadata(storageEngine, args) {
         const { doc, project } = resolved;
         const report = computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
+            if (report.broken.includes(filePath))
+                return "⚠ broken tracking (no snapshot — re-declare via update_doc or run refresh_file_snapshot)";
             if (report.modified.includes(filePath))
                 return "✗ modified";
             if (report.missing.includes(filePath))

package/dist/src/tools/get-doc.js

@@ -29,8 +29,20 @@ export async function getDoc(storageEngine, args) {
             }).join("\n")
             : "  (none)";
         const freshnessReport = computeFreshness(doc.tracked_files, resolvedProject);
-        const stalenessBanner = freshnessReport.status === "stale"
-            ? [
+        let stalenessBanner = "";
+        if (freshnessReport.status === "broken") {
+            stalenessBanner = [
+                `> [!WARNING]`,
+                `> **Le suivi de fichiers de cette documentation est cassé.**`,
+                `> Les entrées suivantes n'ont aucun snapshot de contenu et ne peuvent pas être vérifiées :`,
+                ...freshnessReport.broken.map((f) => `> - \`${f}\` *(aucun snapshot)*`),
+                `>`,
+                `> La fraîcheur de ce document est invérifiable tant que ces entrées ne sont pas re-suivies. Relisez les fichiers sources et re-déclarez-les via \`update_doc\` (tracked_files), ou appelez \`refresh_file_snapshot\` si le contenu ci-dessous est encore exact.`,
+                ``,
+            ].join("\n");
+        }
+        else if (freshnessReport.status === "stale") {
+            stalenessBanner = [
                 `> [!WARNING]`,
                 `> **Cette documentation est potentiellement obsolète.**`,
                 `> Les fichiers suivants ont été modifiés depuis la dernière mise à jour de ce document :`,
@@ -41,8 +53,8 @@ export async function getDoc(storageEngine, args) {
                 `>`,
                 `> Vérifiez si le contenu ci-dessous est toujours valide. Si nécessaire, utilisez \`git_diff_doc\` pour voir les changements, puis mettez à jour la documentation avec \`patch_doc\` ou \`update_doc\`.`,
                 ``,
-            ].join("\n")
-            : "";
+            ].join("\n");
+        }
         const text = [
             stalenessBanner,
             `# ${doc.title}`,

package/dist/src/tools/git-diff-doc.js

@@ -62,7 +62,9 @@ export async function gitDiffDoc(storageEngine, args) {
             }
             else {
                 const freshness = computeFreshness(doc.tracked_files, project);
-                const changedPaths = new Set([...freshness.modified, ...freshness.missing]);
+                // Broken entries (no snapshot) can't be hash-compared, but the git diff
+                // is still the best signal the agent has to re-assess them — include them.
+                const changedPaths = new Set([...freshness.modified, ...freshness.missing, ...freshness.broken]);
                 filesToDiff = doc.tracked_files.filter((tf) => changedPaths.has(tf.path));
             }
             if (filesToDiff.length === 0) {

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

@@ -21,7 +21,7 @@ function renderProjectDocs(summaries, totalLabel) {
         if (key)
             lines.push(`\n  📁 ${key}`);
         for (const s of groups.get(key)) {
-            const staleTag = s.isStale ? " [STALE]" : "";
+            const staleTag = s.isBroken ? " [BROKEN TRACKING]" : s.isStale ? " [STALE]" : "";
             const tags = s.tags.length > 0 ? ` (${s.tags.join(", ")})` : "";
             const indent = key ? "    " : "  ";
             lines.push(`${indent}- ${s.title} [${s.id}]${tags}${staleTag} — updated ${s.updatedAt}`);
@@ -43,6 +43,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             if (summaries.length === 0) {
@@ -61,6 +62,7 @@ export async function listDocs(storageEngine, args) {
                 if (doc && doc.tracked_files.length > 0) {
                     const report = computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
+                    summary.isBroken = report.status === "broken";
                 }
             }
             grandTotal += summaries.length;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.62";
+export declare const APP_VERSION = "1.0.63";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.62';
+export const APP_VERSION = '1.0.63';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.62",
+  "version": "1.0.63",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",