@imenam/mcp-documentor 1.0.61 → 1.0.62

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

@@ -47,7 +47,7 @@ export const CreateDocArgsSchema = z.object({
     title: z.string().describe("Title of the documentation entry"),
     content: z.string().optional().describe("Documentation content in markdown"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("Files to track for staleness detection. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT); paths under the root are stored relative to it so the docs stay portable across machines. Tracked files must exist."),
     tags: z.array(z.string()).optional().describe("Tags for categorization"),
     folder: z.string().optional().describe("Folder path for organization, e.g. 'frontend/components'"),
     related_docs: z.array(z.string()).optional().describe("IDs of related documentation entries"),
@@ -59,7 +59,7 @@ export const UpdateDocArgsSchema = z.object({
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
     content_file: z.string().optional().describe("Absolute path to a text file whose content will be used instead of the content parameter. Use this to reuse a previously persisted draft."),
-    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths; when MCP_DOCUMENTOR_CODE_ROOT is configured they are stored relative to it so the docs stay portable across machines."),
+    tracked_files: z.array(TrackedFileInputSchema).optional().describe("New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Each entry is either a plain path string (whole-file tracking) or an object { path, lines: [{ start, end }, ...] } for granular section tracking. Lines are 1-indexed and inclusive. Provide absolute paths, or paths relative to the project's configured code root (MCP_DOCUMENTOR_CODE_ROOT)."),
     tags: z.array(z.string()).optional().describe("New tags (replaces existing)"),
     related_docs: z.array(z.string()).optional().describe("Paths of related documentation entries (replaces existing)"),
 });

package/dist/src/core/code-ref-resolver.d.ts

@@ -5,10 +5,31 @@ export interface CodeRefResult {
 }
 export declare function resolveCodeRefs(content: string): CodeRefResult;
 export declare function snapshotTrackedFiles(inputs: TrackedFileInput[], project: string): TrackedFile[];
+export interface ResnapshotResult {
+    tracked: TrackedFile[];
+    /** Files already tracked whose stored snapshot was carried over untouched. */
+    preserved: string[];
+    /** Files that were not tracked before; their snapshot is an initialisation, not a refresh. */
+    added: string[];
+    /** Files whose tracking scope changed, leaving no prior snapshot to carry over. */
+    reset: string[];
+}
+/**
+ * Rebuilds a tracked-file list from `inputs`, keeping the stored snapshot of every file that
+ * was already tracked with the same scope.
+ *
+ * Re-declaring `tracked_files` states which files a doc depends on — it says nothing about whether
+ * the doc still describes them correctly. Only `refresh_file_snapshot` may acknowledge that, so a
+ * doc that was stale before this call is still stale after it. Files that were not tracked before
+ * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
+ */
+export declare function resnapshotPreserving(existing: TrackedFile[], inputs: TrackedFileInput[], project: string): ResnapshotResult;
 /**
- * Merges snapshotted tracked files into an existing list.
- * - If a file is not yet tracked: appended.
- * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
- * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ * Merges snapshotted tracked files into an existing list, without ever refreshing what is
+ * already tracked — acknowledging staleness is `refresh_file_snapshot`'s job alone.
+ * - If a file is not yet tracked: appended with a snapshot of its current content.
+ * - If a file is already tracked by section and the addition covers a region not yet tracked:
+ *   that region is appended; existing sections keep their stored hash.
+ * - Otherwise the existing entry is left untouched.
  */
 export declare function mergeTrackedFiles(existing: TrackedFile[], additions: TrackedFileInput[], project: string): TrackedFile[];

package/dist/src/core/code-ref-resolver.js

@@ -2,7 +2,7 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { snapshotSection } from "./section-tracker.js";
-import { toStoredPath } from "./path-resolver.js";
+import { toAbsolutePath, toStoredPath } from "./path-resolver.js";
 const EXT_TO_LANG = {
     ts: "typescript",
     tsx: "tsx",
@@ -53,11 +53,17 @@ export function snapshotTrackedFiles(inputs, project) {
     const byPath = new Map();
     for (const input of inputs) {
         const fp = typeof input === "string" ? input : input.path;
-        const absolutePath = path.resolve(process.cwd(), fp);
-        const storedPath = toStoredPath(fp, project);
-        const mtime = fs.existsSync(absolutePath)
-            ? fs.statSync(absolutePath).mtime.toISOString()
-            : new Date().toISOString();
+        // A relative input path means "relative to the project's code root" — the same
+        // convention used everywhere a stored path is read back. Never the server's cwd.
+        const absolutePath = toAbsolutePath(fp, project);
+        if (!absolutePath) {
+            throw new Error(`Cannot track "${fp}": the path is relative but no code root is configured for project "${project}". Provide an absolute path or set MCP_DOCUMENTOR_CODE_ROOT.`);
+        }
+        if (!fs.existsSync(absolutePath)) {
+            throw new Error(`Cannot track "${fp}": file not found at ${absolutePath}. Tracking snapshots the file content, so the file must exist.`);
+        }
+        const storedPath = toStoredPath(absolutePath, project);
+        const mtime = fs.statSync(absolutePath).mtime.toISOString();
         const isWhole = typeof input === "string" || input.lines.length === 0;
         const existing = byPath.get(storedPath);
         if (isWhole) {
@@ -79,24 +85,87 @@ export function snapshotTrackedFiles(inputs, project) {
     }
     const tracked = [];
     for (const [storedPath, { absolutePath, mtime, lineRanges, wholeFile }] of byPath) {
-        if (!wholeFile && lineRanges.length > 0 && fs.existsSync(absolutePath)) {
-            const sections = lineRanges
-                .filter(({ start, end }) => start <= end)
-                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+        const validRanges = lineRanges.filter(({ start, end }) => start <= end);
+        if (!wholeFile && validRanges.length > 0) {
+            const sections = dedupeSections(validRanges.map(({ start, end }) => snapshotSection(absolutePath, start, end)));
             tracked.push({ path: storedPath, lastModifiedAt: mtime, sections });
         }
         else {
-            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
-            tracked.push({ path: storedPath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
+            // Whole-file tracking — also the landing spot when every provided range was
+            // invalid, so an entry never ends up with neither sections nor contentHash.
+            tracked.push({ path: storedPath, lastModifiedAt: mtime, contentHash: computeFileHash(absolutePath) });
         }
     }
     return tracked;
 }
+const sameLines = (a, b) => a.length === b.length && a.every((line, i) => line === b[i]);
+/** Two sections describe the same region when they were anchored on the same top/bottom lines. */
+function sameRegion(a, b) {
+    return sameLines(a.anchors.top, b.anchors.top) && sameLines(a.anchors.bottom, b.anchors.bottom);
+}
+function dedupeSections(sections) {
+    const unique = [];
+    for (const section of sections) {
+        if (!unique.some((kept) => sameRegion(kept, section)))
+            unique.push(section);
+    }
+    return unique;
+}
+/**
+ * Carries a previously stored snapshot over to a freshly snapshotted entry for the same file.
+ *
+ * Returns `undefined` when nothing can be carried over — the file was tracked whole and is now
+ * tracked by section (or the reverse), so no prior hash describes the newly tracked region.
+ */
+function carryOverSnapshot(previous, fresh) {
+    if (!fresh.sections && !previous.sections)
+        return previous;
+    if (!fresh.sections || !previous.sections)
+        return undefined;
+    const sections = fresh.sections.map((section) => previous.sections.find((prev) => sameRegion(prev, section)) ?? section);
+    const carriedAny = sections.some((section, i) => section !== fresh.sections[i]);
+    if (!carriedAny)
+        return undefined;
+    return { ...previous, sections, lastModifiedAt: previous.lastModifiedAt };
+}
 /**
- * Merges snapshotted tracked files into an existing list.
- * - If a file is not yet tracked: appended.
- * - If a file is already tracked with sections and the new entry also has sections: sections are merged.
- * - Otherwise (whole-file tracking involved): the existing entry is replaced.
+ * Rebuilds a tracked-file list from `inputs`, keeping the stored snapshot of every file that
+ * was already tracked with the same scope.
+ *
+ * Re-declaring `tracked_files` states which files a doc depends on — it says nothing about whether
+ * the doc still describes them correctly. Only `refresh_file_snapshot` may acknowledge that, so a
+ * doc that was stale before this call is still stale after it. Files that were not tracked before
+ * necessarily carry a snapshot of their current content: there is no earlier state to preserve.
+ */
+export function resnapshotPreserving(existing, inputs, project) {
+    const fresh = snapshotTrackedFiles(inputs, project);
+    const byPath = new Map(existing.map((tf) => [tf.path, tf]));
+    const preserved = [];
+    const added = [];
+    const reset = [];
+    const tracked = fresh.map((entry) => {
+        const previous = byPath.get(entry.path);
+        if (!previous) {
+            added.push(entry.path);
+            return entry;
+        }
+        const carried = carryOverSnapshot(previous, entry);
+        if (!carried) {
+            reset.push(entry.path);
+            return entry;
+        }
+        preserved.push(entry.path);
+        return carried;
+    });
+    return { tracked, preserved, added, reset };
+}
+/**
+ * Merges snapshotted tracked files into an existing list, without ever refreshing what is
+ * already tracked — acknowledging staleness is `refresh_file_snapshot`'s job alone.
+ * - If a file is not yet tracked: appended with a snapshot of its current content.
+ * - If a file is already tracked by section and the addition covers a region not yet tracked:
+ *   that region is appended; existing sections keep their stored hash.
+ * - Otherwise the existing entry is left untouched.
  */
 export function mergeTrackedFiles(existing, additions, project) {
     if (additions.length === 0)
@@ -107,16 +176,14 @@ export function mergeTrackedFiles(existing, additions, project) {
         const idx = result.findIndex(tf => tf.path === newTf.path);
         if (idx < 0) {
             result.push(newTf);
+            continue;
         }
-        else if (newTf.sections && result[idx].sections) {
-            result[idx] = {
-                ...result[idx],
-                sections: [...result[idx].sections, ...newTf.sections],
-                lastModifiedAt: newTf.lastModifiedAt,
-            };
-        }
-        else {
-            result[idx] = newTf;
+        const current = result[idx];
+        if (!newTf.sections || !current.sections)
+            continue;
+        const novel = newTf.sections.filter((section) => !current.sections.some((kept) => sameRegion(kept, section)));
+        if (novel.length > 0) {
+            result[idx] = { ...current, sections: [...current.sections, ...novel] };
         }
     }
     return result;

package/dist/src/index.js

@@ -159,8 +159,15 @@ 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) {
-                const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale";
+                // 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 bundles = storageEngine.getBundles();
@@ -197,8 +204,13 @@ async function handleUpdateProject(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, project);
-                doc.isStale = report.status === "stale";
+                try {
+                    const report = computeFreshness(full.tracked_files, project);
+                    doc.isStale = report.status === "stale";
+                }
+                catch {
+                    doc.isStale = true;
+                }
             }
         }
         broadcastToGUI({
@@ -238,8 +250,13 @@ async function handleListDocs(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, currentProject);
-                doc.isStale = report.status === "stale";
+                try {
+                    const report = computeFreshness(full.tracked_files, currentProject);
+                    doc.isStale = report.status === "stale";
+                }
+                catch {
+                    doc.isStale = true;
+                }
             }
         }
         broadcastToGUI({
@@ -351,8 +368,15 @@ async function handleCreateDocIPC(msg) {
         for (const doc of docs) {
             const full = await storageEngine.getDoc(doc.id);
             if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale";
+                // 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;
+                }
             }
         }
         broadcastToGUI({
@@ -684,7 +708,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                 },
                             ],
                         },
-                        description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                        description: "Files to track for staleness detection. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change). Paths are absolute, or relative to the project's code root. Tracked files must exist.",
                     },
                     tags: {
                         type: "array",
@@ -764,7 +788,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                                 },
                             ],
                         },
-                        description: "New list of tracked files (replaces existing). Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change).",
+                        description: "New list of tracked files (replaces existing). Files already tracked with the same scope keep their stored snapshot, so this never changes staleness — only refresh_file_snapshot acknowledges file changes. Use a plain path string for whole-file tracking, or { path, lines: [{ start, end }] } to track specific sections only (reduces false positives when unrelated parts of the file change). Paths are absolute, or relative to the project's code root.",
                     },
                     tags: {
                         type: "array",

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

@@ -60,15 +60,9 @@ export function computeFreshness(trackedFiles, project) {
             }
         }
         else {
-            const currentMtime = fs.statSync(absolutePath).mtime.getTime();
-            const storedMtime = new Date(tracked.lastModifiedAt).getTime();
-            const STALENESS_TOLERANCE_MS = 2000;
-            if (currentMtime > storedMtime + STALENESS_TOLERANCE_MS) {
-                modified.push(tracked.path);
-            }
-            else {
-                unchanged.push(tracked.path);
-            }
+            // 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.`);
         }
     }
     // When every tracked file is absent, the source code simply isn't present on
@@ -124,6 +118,62 @@ function renderUntrackedList(titles, heading) {
     const suffix = remaining > 0 ? `\n  … and ${remaining} more` : "";
     return `\n\n${heading}\n${shown.join("\n")}${suffix}`;
 }
+async function scanProjectFreshness(storageEngine, project) {
+    const summaries = await storageEngine.listDocs(project);
+    const scan = { docCount: summaries.length, stale: [], noTracking: [], broken: [], upToDate: 0, unverifiable: 0 };
+    for (const summary of summaries) {
+        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;
+        }
+        if (report.status === "no_tracking") {
+            scan.noTracking.push(doc.title);
+        }
+        else if (report.status === "unverifiable") {
+            scan.unverifiable++;
+        }
+        else if (report.status === "stale") {
+            const details = [
+                ...report.modified.map((f) => `    • modified: ${f}`),
+                ...report.missing.map((f) => `    • missing: ${f}`),
+                ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
+            ].join("\n");
+            scan.stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
+        }
+        else {
+            scan.upToDate++;
+        }
+    }
+    return scan;
+}
+function renderScanSummary(scan) {
+    let text = `${scan.docCount} doc(s) scanned: **${scan.stale.length} stale**, ${scan.upToDate} up to date, ${scan.unverifiable} unverifiable (source absent), ${scan.noTracking.length} not tracking any file`;
+    if (scan.broken.length > 0)
+        text += `, **${scan.broken.length} with broken tracking**`;
+    return text + ".";
+}
+function renderScanSections(scan, headingLevel) {
+    let text = "";
+    if (scan.broken.length > 0) {
+        text += `\n\n${headingLevel} Docs with broken tracking — fix required\n\n${scan.broken.join("\n")}`;
+        text += `\n  → These docs could not be checked. Re-read the source files and re-declare tracked_files via update_doc, then call refresh_file_snapshot if the doc content is still accurate.`;
+    }
+    if (scan.stale.length > 0) {
+        text += `\n\n${headingLevel} Stale docs\n\n${scan.stale.join("\n\n")}`;
+    }
+    if (scan.noTracking.length > 0) {
+        text += renderUntrackedList(scan.noTracking, `${headingLevel} Docs not tracking any file (no staleness detection)`);
+    }
+    return text;
+}
 export async function checkFreshness(storageEngine, args) {
     try {
         const validated = CheckFreshnessArgsSchema.parse(args);
@@ -137,45 +187,11 @@ export async function checkFreshness(storageEngine, args) {
             return { content: [{ type: "text", text: formatFreshnessReport(doc.title, report) }] };
         }
         if (validated.project) {
-            const summaries = await storageEngine.listDocs(validated.project);
-            if (summaries.length === 0) {
+            const scan = await scanProjectFreshness(storageEngine, validated.project);
+            if (scan.docCount === 0) {
                 return { content: [{ type: "text", text: `No documentation entries found in project "${validated.project}".` }] };
             }
-            const stale = [];
-            const noTracking = [];
-            let upToDate = 0;
-            let unverifiable = 0;
-            for (const summary of summaries) {
-                const doc = await storageEngine.getDoc(summary.id, validated.project);
-                if (!doc)
-                    continue;
-                const report = computeFreshness(doc.tracked_files, validated.project);
-                if (report.status === "no_tracking") {
-                    noTracking.push(doc.title);
-                }
-                else if (report.status === "unverifiable") {
-                    unverifiable++;
-                }
-                else if (report.status === "stale") {
-                    const details = [
-                        ...report.modified.map((f) => `    • modified: ${f}`),
-                        ...report.missing.map((f) => `    • missing: ${f}`),
-                        ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
-                    ].join("\n");
-                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
-                }
-                else {
-                    upToDate++;
-                }
-            }
-            let text = `# Freshness report — project "${validated.project}"\n\n`;
-            text += `${summaries.length} doc(s) scanned: **${stale.length} stale**, ${upToDate} up to date, ${unverifiable} unverifiable (source absent), ${noTracking.length} not tracking any file.\n`;
-            if (stale.length > 0) {
-                text += `\n## Stale docs\n\n${stale.join("\n\n")}`;
-            }
-            if (noTracking.length > 0) {
-                text += renderUntrackedList(noTracking, "## Docs not tracking any file (no staleness detection)");
-            }
+            const text = `# Freshness report — project "${validated.project}"\n\n${renderScanSummary(scan)}${renderScanSections(scan, "##")}`;
             return { content: [{ type: "text", text }] };
         }
         // No id, no project → scan all projects
@@ -184,49 +200,16 @@ export async function checkFreshness(storageEngine, args) {
         const projectBlocks = [];
         let totalDocs = 0;
         let totalStale = 0;
+        let totalBroken = 0;
         for (const proj of allProjects) {
-            const summaries = await storageEngine.listDocs(proj);
-            const stale = [];
-            const noTracking = [];
-            let upToDate = 0;
-            let unverifiable = 0;
-            for (const summary of summaries) {
-                const doc = await storageEngine.getDoc(summary.id, proj);
-                if (!doc)
-                    continue;
-                const report = computeFreshness(doc.tracked_files, proj);
-                if (report.status === "no_tracking") {
-                    noTracking.push(doc.title);
-                }
-                else if (report.status === "unverifiable") {
-                    unverifiable++;
-                }
-                else if (report.status === "stale") {
-                    const details = [
-                        ...report.modified.map((f) => `    • modified: ${f}`),
-                        ...report.missing.map((f) => `    • missing: ${f}`),
-                        ...(report.anchors_lost ?? []).map((f) => `    • ⚠ anchors lost (needs update_doc): ${f}`),
-                    ].join("\n");
-                    stale.push(`  - **${doc.title}** [${doc.id}]\n${details}`);
-                }
-                else {
-                    upToDate++;
-                }
-            }
-            totalDocs += summaries.length;
-            totalStale += stale.length;
-            let block = `## ${proj}\n\n`;
-            block += `${summaries.length} doc(s): **${stale.length} stale**, ${upToDate} up to date, ${unverifiable} unverifiable (source absent), ${noTracking.length} not tracking any file.`;
-            if (stale.length > 0) {
-                block += `\n\n### Stale docs\n\n${stale.join("\n\n")}`;
-            }
-            if (noTracking.length > 0) {
-                block += renderUntrackedList(noTracking, "### Docs not tracking any file");
-            }
-            projectBlocks.push(block);
+            const scan = await scanProjectFreshness(storageEngine, proj);
+            totalDocs += scan.docCount;
+            totalStale += scan.stale.length;
+            totalBroken += scan.broken.length;
+            projectBlocks.push(`## ${proj}\n\n${renderScanSummary(scan)}${renderScanSections(scan, "###")}`);
         }
         let text = `# Freshness report — all projects (${allProjects.length})\n\n`;
-        text += `Total: ${totalDocs} doc(s) across all projects, **${totalStale} stale**.\n\n`;
+        text += `Total: ${totalDocs} doc(s) across all projects, **${totalStale} stale**${totalBroken > 0 ? `, **${totalBroken} with broken tracking**` : ""}.\n\n`;
         text += projectBlocks.join("\n\n---\n\n");
         return { content: [{ type: "text", text }] };
     }

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

@@ -1,7 +1,7 @@
 import fs from "fs";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { persistDraft } from "../core/draft-store.js";
-import { resolveCodeRefs, snapshotTrackedFiles, mergeTrackedFiles } from "../core/code-ref-resolver.js";
+import { resolveCodeRefs, resnapshotPreserving, mergeTrackedFiles } from "../core/code-ref-resolver.js";
 export async function updateDoc(storageEngine, embeddingEngine, args) {
     try {
         const validated = UpdateDocArgsSchema.parse(args);
@@ -24,11 +24,16 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             doc.content = content;
             additionalTrackedFiles = refs;
         }
+        // Re-declaring tracked_files must never acknowledge staleness — that is
+        // refresh_file_snapshot's job alone. Snapshots of files already tracked with
+        // the same scope are carried over as-is; only genuinely new entries get one.
+        let trackedResult;
         if (validated.tracked_files !== undefined) {
-            doc.tracked_files = snapshotTrackedFiles([
+            trackedResult = resnapshotPreserving(doc.tracked_files, [
                 ...validated.tracked_files,
                 ...additionalTrackedFiles,
             ], resolvedProject);
+            doc.tracked_files = trackedResult.tracked;
         }
         else {
             doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
@@ -57,8 +62,16 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
             changes.push("content");
         if (validated.content_file !== undefined)
             changes.push("content (from file)");
-        if (validated.tracked_files !== undefined)
-            changes.push(`tracked_files (${doc.tracked_files.length} files)`);
+        if (trackedResult !== undefined) {
+            const parts = [`${doc.tracked_files.length} files`];
+            if (trackedResult.preserved.length > 0)
+                parts.push(`${trackedResult.preserved.length} kept their existing snapshot`);
+            if (trackedResult.added.length > 0)
+                parts.push(`${trackedResult.added.length} newly tracked`);
+            if (trackedResult.reset.length > 0)
+                parts.push(`${trackedResult.reset.length} re-snapshotted (tracking scope changed): ${trackedResult.reset.join(", ")}`);
+            changes.push(`tracked_files (${parts.join("; ")}). Staleness is unaffected — use refresh_file_snapshot to acknowledge file changes.`);
+        }
         if (validated.tags !== undefined)
             changes.push(`tags (${doc.tags.join(", ") || "none"})`);
         if (validated.related_docs !== undefined)

package/dist/src/version.d.ts

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

package/dist/src/version.js

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

package/package.json

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