@imenam/mcp-documentor 1.0.90 → 1.0.91

package/README.md

@@ -127,7 +127,7 @@ that work on a whole project (`list_docs`, `get_doc_tree`, `check_freshness` wit
 | `search_docs` | Semantic search over docs (natural language; requires OpenAI) |
 | `check_freshness` | Staleness for one doc (`project` required) or a full project scan |
 | `refresh_file_snapshot` | Mark tracked files as up-to-date without editing the doc (`project` required) |
-| `git_diff_doc` | Diff of changed tracked files between their snapshot content and the current one (`project` required) |
+| `git_diff_doc` | Diff of changed tracked files between their snapshot content and the current one (`project` required). Files whose tracked sections can no longer be located (anchors lost) are included and diffed whole, with a warning |
 | `check_links` | Validate `related_docs`, `doc://` links, and `#heading` anchors (`project` required) |
 | `list_projects` | List all documentation projects |
 | `upload_image` | Upload an image from a local file path to a project's assets (`project` required); returns the markdown link to insert |

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

@@ -18,6 +18,8 @@ export async function getDocMetadata(storageEngine, args) {
                 return "✗ modified";
             if (report.missing.includes(filePath))
                 return "✗ missing";
+            if (report.anchors_lost.includes(filePath))
+                return "⚠ anchors lost (re-declare the sections via update_doc)";
             return "✓ up to date";
         };
         let text = `**Path:** ${doc.id}\n`;

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

@@ -163,15 +163,16 @@ export async function gitDiffDoc(storageEngine, args) {
                 docSections.push(`## ${doc.title}\n\n[INFO] No tracked files.`);
                 continue;
             }
+            const freshness = await computeFreshness(doc.tracked_files, project);
+            const anchorsLost = new Set(freshness.anchors_lost);
             let filesToDiff;
             if (wanted) {
                 filesToDiff = doc.tracked_files.filter((tf) => wanted.has(tf.path));
             }
             else {
-                const freshness = await computeFreshness(doc.tracked_files, project);
-                // 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]);
+                // Broken entries (no snapshot) and files whose sections can no longer be located can't be
+                // hash-compared, but the whole-file diff is the best signal the agent has to re-assess them.
+                const changedPaths = new Set([...freshness.modified, ...freshness.missing, ...freshness.broken, ...anchorsLost]);
                 filesToDiff = doc.tracked_files.filter((tf) => changedPaths.has(tf.path));
             }
             if (filesToDiff.length === 0) {
@@ -194,7 +195,11 @@ export async function gitDiffDoc(storageEngine, args) {
             const diffs = await mapWithConcurrency(fresh, FILE_CONCURRENCY, (tf) => diffTrackedFile(tf, project, source));
             const fileSections = fresh.map((tf, i) => {
                 const base = tf.sourceRevision ? `\nSnapshot commit: ${short(tf.sourceRevision)}` : "";
-                return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}${base}\n\n${diffs[i]}`;
+                const anchorsNote = anchorsLost.has(tf.path)
+                    ? `  [WARN] Anchors lost: the tracked section(s) can no longer be located, so the whole file is diffed.\n` +
+                        `  → Re-declare the sections in tracked_files via update_doc.\n\n`
+                    : "";
+                return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}${base}\n\n${anchorsNote}${diffs[i]}`;
             });
             docSections.push(`## ${doc.title} [${docPath}]\n\nCode source: ${source.label}\n\n${fileSections.join("\n\n---\n\n")}`);
         }

package/package.json

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