@imenam/mcp-documentor 1.0.33 → 1.0.35

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

@@ -1,10 +1,37 @@
 import { z } from "zod";
+export declare const TrackedSectionSchema: z.ZodObject<{
+    anchors: z.ZodObject<{
+        top: z.ZodArray<z.ZodString>;
+        bottom: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    sectionHash: z.ZodString;
+}, z.core.$strip>;
+export type TrackedSection = z.infer<typeof TrackedSectionSchema>;
 export declare const TrackedFileSchema: z.ZodObject<{
     path: z.ZodString;
     lastModifiedAt: z.ZodString;
     contentHash: z.ZodOptional<z.ZodString>;
+    sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        anchors: z.ZodObject<{
+            top: z.ZodArray<z.ZodString>;
+            bottom: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        sectionHash: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type TrackedFile = z.infer<typeof TrackedFileSchema>;
+export declare const TrackedFileInputLineSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, z.core.$strip>;
+export declare const TrackedFileInputSchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    path: z.ZodString;
+    lines: z.ZodArray<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>]>;
+export type TrackedFileInput = z.infer<typeof TrackedFileInputSchema>;
 export declare const DocSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -13,6 +40,13 @@ export declare const DocSchema: z.ZodObject<{
         path: z.ZodString;
         lastModifiedAt: z.ZodString;
         contentHash: z.ZodOptional<z.ZodString>;
+        sections: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            anchors: z.ZodObject<{
+                top: z.ZodArray<z.ZodString>;
+                bottom: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>;
+            sectionHash: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
@@ -53,7 +87,13 @@ export type FreshnessReport = z.infer<typeof FreshnessReportSchema>;
 export declare const CreateDocArgsSchema: z.ZodObject<{
     title: z.ZodString;
     content: z.ZodString;
-    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        lines: z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     folder: z.ZodOptional<z.ZodString>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -62,7 +102,13 @@ export declare const UpdateDocArgsSchema: z.ZodObject<{
     path: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
     content: z.ZodOptional<z.ZodString>;
-    tracked_files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tracked_files: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        path: z.ZodString;
+        lines: z.ZodArray<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     related_docs: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;

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

@@ -1,9 +1,28 @@
 import { z } from "zod";
+export const TrackedSectionSchema = z.object({
+    anchors: z.object({
+        top: z.array(z.string()),
+        bottom: z.array(z.string()),
+    }),
+    sectionHash: z.string(),
+});
 export const TrackedFileSchema = z.object({
     path: z.string(),
     lastModifiedAt: z.string(),
     contentHash: z.string().optional(),
-});
+    sections: z.array(TrackedSectionSchema).optional(),
+});
+export const TrackedFileInputLineSchema = z.object({
+    start: z.number().int().positive(),
+    end: z.number().int().positive(),
+});
+export const TrackedFileInputSchema = z.union([
+    z.string(),
+    z.object({
+        path: z.string(),
+        lines: z.array(TrackedFileInputLineSchema).min(1),
+    }),
+]);
 export const DocSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -25,7 +44,7 @@ export const FreshnessReportSchema = z.object({
 export const CreateDocArgsSchema = z.object({
     title: z.string().describe("Title of the documentation entry"),
     content: z.string().describe("Documentation content in markdown"),
-    tracked_files: z.array(z.string()).optional().describe("File paths to track for staleness detection"),
+    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."),
     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"),
@@ -34,7 +53,7 @@ export const UpdateDocArgsSchema = z.object({
     path: z.string().describe("Path of the documentation entry to update, e.g. 'backend/auth/authentication' or 'authentication' for root docs"),
     title: z.string().optional().describe("Title of the documentation entry"),
     content: z.string().optional().describe("New content (replaces existing)"),
-    tracked_files: z.array(z.string()).optional().describe("New list of file paths (replaces existing)"),
+    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."),
     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/section-tracker.d.ts

@@ -0,0 +1,40 @@
+import type { TrackedSection } from "../../shared/schemas/doc.schema.js";
+/**
+ * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * Extracts top/bottom anchor lines and computes a hash of the section content.
+ * The `lines` input is intentionally not persisted — only anchors and sectionHash are stored.
+ */
+export declare function snapshotSection(absolutePath: string, start: number, end: number): TrackedSection;
+type FindResult = {
+    found: false;
+} | {
+    found: true;
+    currentHash: string;
+    lines: {
+        start: number;
+        end: number;
+    };
+};
+/**
+ * Locates a tracked section in the current file content using its stored anchors,
+ * then hashes the found content for comparison with the stored sectionHash.
+ * Also returns the current 1-indexed line range where the section was found,
+ * so callers can display it without storing it.
+ *
+ * Returns { found: false } if the anchors cannot be located — which is treated as stale,
+ * since the surrounding context has changed enough to invalidate the documentation.
+ */
+export declare function findAndHashSection(absolutePath: string, section: TrackedSection): FindResult;
+type RelocateResult = {
+    found: false;
+} | {
+    found: true;
+    refreshed: TrackedSection;
+};
+/**
+ * Locates a section by its current anchors, then refreshes its sectionHash to match
+ * the current file content. Used by refresh_file_snapshot to acknowledge changes.
+ * Anchors are kept as-is (they were found successfully); only sectionHash is updated.
+ */
+export declare function relocateAndRefreshSection(absolutePath: string, section: TrackedSection): RelocateResult;
+export {};

package/dist/src/core/section-tracker.js

@@ -0,0 +1,99 @@
+import crypto from "crypto";
+import fs from "fs";
+const ANCHOR_SIZE = 3;
+/**
+ * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * Extracts top/bottom anchor lines and computes a hash of the section content.
+ * The `lines` input is intentionally not persisted — only anchors and sectionHash are stored.
+ */
+export function snapshotSection(absolutePath, start, end) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const allLines = fileContent.split("\n");
+    const startIdx = Math.max(0, start - 1);
+    const endIdx = Math.min(allLines.length - 1, end - 1);
+    const sectionLines = allLines.slice(startIdx, endIdx + 1);
+    let top;
+    let bottom;
+    if (sectionLines.length < ANCHOR_SIZE * 2) {
+        // Short section: all lines become the top anchor; bottom is empty (section = top anchor)
+        top = [...sectionLines];
+        bottom = [];
+    }
+    else {
+        top = sectionLines.slice(0, ANCHOR_SIZE);
+        bottom = sectionLines.slice(sectionLines.length - ANCHOR_SIZE);
+    }
+    const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+    return { anchors: { top, bottom }, sectionHash };
+}
+/**
+ * Locates a tracked section in the current file content using its stored anchors,
+ * then hashes the found content for comparison with the stored sectionHash.
+ * Also returns the current 1-indexed line range where the section was found,
+ * so callers can display it without storing it.
+ *
+ * Returns { found: false } if the anchors cannot be located — which is treated as stale,
+ * since the surrounding context has changed enough to invalidate the documentation.
+ */
+export function findAndHashSection(absolutePath, section) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const fileLines = fileContent.split("\n");
+    const { top, bottom } = section.anchors;
+    if (bottom.length === 0) {
+        // Short-section path: the top anchor IS the full section content
+        for (let i = 0; i <= fileLines.length - top.length; i++) {
+            if (top.every((line, j) => fileLines[i + j] === line)) {
+                const sectionLines = fileLines.slice(i, i + top.length);
+                const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+                return { found: true, currentHash, lines: { start: i + 1, end: i + top.length } };
+            }
+        }
+        return { found: false };
+    }
+    // Normal path: locate top anchor, then search for bottom anchor below it
+    for (let i = 0; i <= fileLines.length - top.length; i++) {
+        if (!top.every((line, j) => fileLines[i + j] === line))
+            continue;
+        const searchStart = i + top.length;
+        for (let k = searchStart; k <= fileLines.length - bottom.length; k++) {
+            if (!bottom.every((line, j) => fileLines[k + j] === line))
+                continue;
+            const sectionLines = fileLines.slice(i, k + bottom.length);
+            const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+            return { found: true, currentHash, lines: { start: i + 1, end: k + bottom.length } };
+        }
+    }
+    return { found: false };
+}
+/**
+ * Locates a section by its current anchors, then refreshes its sectionHash to match
+ * the current file content. Used by refresh_file_snapshot to acknowledge changes.
+ * Anchors are kept as-is (they were found successfully); only sectionHash is updated.
+ */
+export function relocateAndRefreshSection(absolutePath, section) {
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const fileLines = fileContent.split("\n");
+    const { top, bottom } = section.anchors;
+    if (bottom.length === 0) {
+        for (let i = 0; i <= fileLines.length - top.length; i++) {
+            if (top.every((line, j) => fileLines[i + j] === line)) {
+                const sectionHash = crypto.createHash("sha256").update(fileLines.slice(i, i + top.length).join("\n")).digest("hex");
+                return { found: true, refreshed: { anchors: section.anchors, sectionHash } };
+            }
+        }
+        return { found: false };
+    }
+    for (let i = 0; i <= fileLines.length - top.length; i++) {
+        if (!top.every((line, j) => fileLines[i + j] === line))
+            continue;
+        const searchStart = i + top.length;
+        for (let k = searchStart; k <= fileLines.length - bottom.length; k++) {
+            if (!bottom.every((line, j) => fileLines[k + j] === line))
+                continue;
+            const sectionLines = fileLines.slice(i, k + bottom.length);
+            const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
+            return { found: true, refreshed: { anchors: section.anchors, sectionHash } };
+        }
+    }
+    return { found: false };
+}

package/dist/src/index.js

@@ -33,6 +33,7 @@ import { HistoryStore } from "./core/history-store.js";
 import { listDocVersions } from "./tools/list-doc-versions.js";
 import { getDocVersion } from "./tools/get-doc-version.js";
 import { restoreDocVersion } from "./tools/restore-doc-version.js";
+import { reindexEmbeddings } from "./tools/reindex-embeddings.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function findProjectRoot(startDir) {
@@ -449,8 +450,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         content: { type: "string", description: "Documentation content in markdown. To link to another document inline, use the syntax [text](doc://target-doc-id) — the viewer will navigate to that document on click. To link to a heading within the same document, use [text](#heading-slug). Use check_links to validate both types. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
                         tracked_files: {
                             type: "array",
-                            items: { type: "string" },
-                            description: "File paths to track for staleness detection",
+                            items: {
+                                oneOf: [
+                                    { type: "string", description: "Plain file path for whole-file tracking" },
+                                    {
+                                        type: "object",
+                                        properties: {
+                                            path: { type: "string", description: "File path to track" },
+                                            lines: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
+                                                    },
+                                                    required: ["start", "end"],
+                                                },
+                                                minItems: 1,
+                                                description: "One or more line ranges to track within the file",
+                                            },
+                                        },
+                                        required: ["path", "lines"],
+                                        description: "Granular section tracking: only the specified line ranges are monitored",
+                                    },
+                                ],
+                            },
+                            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).",
                         },
                         tags: {
                             type: "array",
@@ -503,8 +529,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                         content: { type: "string", description: "New content (replaces existing). Supports [text](doc://target-doc-path) to link inline to other documents, and [text](#heading-slug) to link to headings within this document. For code blocks, always specify a language identifier for syntax highlighting, e.g. ```typescript, ```python, ```bash, ```json, ```yaml, ```sql." },
                         tracked_files: {
                             type: "array",
-                            items: { type: "string" },
-                            description: "New list of file paths (replaces existing)",
+                            items: {
+                                oneOf: [
+                                    { type: "string", description: "Plain file path for whole-file tracking" },
+                                    {
+                                        type: "object",
+                                        properties: {
+                                            path: { type: "string", description: "File path to track" },
+                                            lines: {
+                                                type: "array",
+                                                items: {
+                                                    type: "object",
+                                                    properties: {
+                                                        start: { type: "integer", minimum: 1, description: "First line of the section (1-indexed, inclusive)" },
+                                                        end: { type: "integer", minimum: 1, description: "Last line of the section (1-indexed, inclusive)" },
+                                                    },
+                                                    required: ["start", "end"],
+                                                },
+                                                minItems: 1,
+                                                description: "One or more line ranges to track within the file",
+                                            },
+                                        },
+                                        required: ["path", "lines"],
+                                        description: "Granular section tracking: only the specified line ranges are monitored",
+                                    },
+                                ],
+                            },
+                            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).",
                         },
                         tags: {
                             type: "array",
@@ -709,6 +760,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ["path", "version"],
                 },
             },
+            {
+                name: "reindex_embeddings",
+                description: "Generate missing embeddings for all documentation entries in a project (or all projects). Useful when importing existing documentation that was created outside the MCP. Use force: true to regenerate embeddings for all docs, including those already indexed.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project: { type: "string", description: "Project to reindex (processes all projects if omitted)" },
+                        force: { type: "boolean", description: "If true, regenerates embeddings for all docs even if they are already indexed (default: false)" },
+                    },
+                    required: [],
+                },
+            },
         ],
     };
 });
@@ -754,6 +817,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await getDocVersion(historyStore, storageEngine, args);
             case "restore_doc_version":
                 return await restoreDocVersion(historyStore, storageEngine, embeddingEngine, args);
+            case "reindex_embeddings":
+                return await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, args);
             default:
                 throw new Error(`Tool not found: ${name}`);
         }

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

@@ -2,6 +2,7 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { CheckFreshnessArgsSchema } from "../../shared/schemas/doc.schema.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export function computeFileHash(absolutePath) {
     return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
 }
@@ -18,7 +19,23 @@ export function computeFreshness(trackedFiles) {
             missing.push(tracked.path);
             continue;
         }
-        if (tracked.contentHash) {
+        if (tracked.sections && tracked.sections.length > 0) {
+            let sectionStale = false;
+            for (const section of tracked.sections) {
+                const result = findAndHashSection(absolutePath, section);
+                if (!result.found || result.currentHash !== section.sectionHash) {
+                    sectionStale = true;
+                    break;
+                }
+            }
+            if (sectionStale) {
+                modified.push(tracked.path);
+            }
+            else {
+                unchanged.push(tracked.path);
+            }
+        }
+        else if (tracked.contentHash) {
             const currentHash = computeFileHash(absolutePath);
             if (currentHash !== tracked.contentHash) {
                 modified.push(tracked.path);

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

@@ -2,6 +2,7 @@ import fs from "fs";
 import path from "path";
 import { CreateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
+import { snapshotSection } from "../core/section-tracker.js";
 function slugify(title) {
     return title
         .normalize("NFD")
@@ -10,17 +11,24 @@ function slugify(title) {
         .replace(/[^a-z0-9]+/g, "-")
         .replace(/^-|-$/g, "");
 }
-function snapshotTrackedFiles(filePaths) {
+function snapshotTrackedFiles(inputs) {
     const tracked = [];
-    for (const fp of filePaths) {
+    for (const input of inputs) {
+        const fp = typeof input === "string" ? input : input.path;
         const absolutePath = path.resolve(process.cwd(), fp);
-        let mtime = new Date().toISOString();
-        let contentHash;
-        if (fs.existsSync(absolutePath)) {
-            mtime = fs.statSync(absolutePath).mtime.toISOString();
-            contentHash = computeFileHash(absolutePath);
+        const mtime = fs.existsSync(absolutePath)
+            ? fs.statSync(absolutePath).mtime.toISOString()
+            : new Date().toISOString();
+        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
+            const sections = input.lines
+                .filter(({ start, end }) => start <= end)
+                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+        }
+        else {
+            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
-        tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
     }
     return tracked;
 }

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

@@ -1,5 +1,6 @@
 import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export async function getDocMetadata(storageEngine, args) {
     try {
         const validated = GetDocMetadataArgsSchema.parse(args);
@@ -24,9 +25,20 @@ export async function getDocMetadata(storageEngine, args) {
         text += `**Freshness:** ${report.status}\n`;
         if (doc.tracked_files.length > 0) {
             text += `\nTracked files (${doc.tracked_files.length} total):\n`;
-            text += doc.tracked_files
-                .map((f) => `  ${fileStatusIcon(f.path)} — ${f.path}\n  Snapshot: ${f.lastModifiedAt}`)
-                .join("\n");
+            text += doc.tracked_files.map((f) => {
+                let entry = `  ${fileStatusIcon(f.path)} — ${f.path}\n  Snapshot: ${f.lastModifiedAt}`;
+                if (f.sections && f.sections.length > 0) {
+                    const sectionLines = f.sections.map((section, idx) => {
+                        const result = findAndHashSection(f.path, section);
+                        const location = result.found
+                            ? `lines ${result.lines.start}–${result.lines.end}`
+                            : "section introuvable (ancres modifiées)";
+                        return `    - Section ${idx + 1}: ${location}`;
+                    });
+                    entry += `\n  Sections (position actuelle):\n${sectionLines.join("\n")}`;
+                }
+                return entry;
+            }).join("\n");
         }
         else {
             text += "\nNo tracked files.";

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

@@ -1,5 +1,6 @@
 import { GetDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
+import { findAndHashSection } from "../core/section-tracker.js";
 export async function getDoc(storageEngine, args) {
     try {
         const validated = GetDocArgsSchema.parse(args);
@@ -9,7 +10,19 @@ export async function getDoc(storageEngine, args) {
         }
         const { doc, project: resolvedProject } = resolved;
         const trackedFilesText = doc.tracked_files.length > 0
-            ? doc.tracked_files.map((f) => `  - ${f.path} (snapshot: ${f.lastModifiedAt})`).join("\n")
+            ? doc.tracked_files.map((f) => {
+                if (f.sections && f.sections.length > 0) {
+                    const sectionLines = f.sections.map((section, idx) => {
+                        const result = findAndHashSection(f.path, section);
+                        const location = result.found
+                            ? `lines ${result.lines.start}–${result.lines.end}`
+                            : "section introuvable";
+                        return `    - Section ${idx + 1}: ${location}`;
+                    });
+                    return `  - ${f.path} (snapshot: ${f.lastModifiedAt})\n${sectionLines.join("\n")}`;
+                }
+                return `  - ${f.path} (snapshot: ${f.lastModifiedAt})`;
+            }).join("\n")
             : "  (none)";
         const freshnessReport = computeFreshness(doc.tracked_files);
         const stalenessBanner = freshnessReport.status === "stale"

package/dist/src/tools/refresh-file-snapshot.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { RefreshFileSnapshotArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
+import { relocateAndRefreshSection } from "../core/section-tracker.js";
 export async function refreshFileSnapshot(storageEngine, historyStore, args) {
     try {
         const validated = RefreshFileSnapshotArgsSchema.parse(args);
@@ -25,7 +26,16 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
                     continue;
                 }
                 tracked.lastModifiedAt = fs.statSync(tracked.path).mtime.toISOString();
-                tracked.contentHash = computeFileHash(tracked.path);
+                if (tracked.sections && tracked.sections.length > 0) {
+                    const refreshedSections = tracked.sections.map((section) => {
+                        const result = relocateAndRefreshSection(tracked.path, section);
+                        return result.found ? result.refreshed : section;
+                    });
+                    tracked.sections = refreshedSections;
+                }
+                else {
+                    tracked.contentHash = computeFileHash(tracked.path);
+                }
                 refreshed.push(tracked.path);
             }
             await storageEngine.saveDoc(doc, resolvedProject);

package/dist/src/tools/reindex-embeddings.d.ts

@@ -0,0 +1,16 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { EmbeddingEngine } from "../core/embedding-engine.js";
+import type { EmbeddingStore } from "../core/embedding-store.js";
+export declare function reindexEmbeddings(storageEngine: StorageEngine, embeddingEngine: EmbeddingEngine, embeddingStore: EmbeddingStore, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/reindex-embeddings.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+const ReindexEmbeddingsArgsSchema = z.object({
+    project: z.string().optional(),
+    force: z.boolean().optional().default(false),
+});
+export async function reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, args) {
+    try {
+        if (!embeddingEngine.isConfigured()) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: "OpenAI API key is not configured. Set MCP_DOCUMENTOR_OPENAI_API_KEY in your .env file to enable embedding generation.",
+                    },
+                ],
+            };
+        }
+        const validated = ReindexEmbeddingsArgsSchema.parse(args);
+        const config = storageEngine.getConfig();
+        const projectsToProcess = validated.project
+            ? [validated.project]
+            : config.projects;
+        const summary = [];
+        for (const project of projectsToProcess) {
+            const docs = await storageEngine.listDocs(project);
+            if (docs.length === 0) {
+                summary.push({ project, indexed: 0, skipped: 0, failed: 0 });
+                continue;
+            }
+            const existingEmbeddings = embeddingStore.loadAll(project);
+            let indexed = 0;
+            let skipped = 0;
+            let failed = 0;
+            for (const docSummary of docs) {
+                const alreadyIndexed = existingEmbeddings.has(docSummary.id);
+                if (alreadyIndexed && !validated.force) {
+                    skipped++;
+                    continue;
+                }
+                const doc = await storageEngine.getDoc(docSummary.id, project);
+                if (!doc) {
+                    failed++;
+                    continue;
+                }
+                const embedding = await embeddingEngine.generateEmbedding(doc.content);
+                if (embedding) {
+                    await embeddingEngine.saveEmbedding(doc.id, embedding, project);
+                    indexed++;
+                }
+                else {
+                    failed++;
+                }
+            }
+            summary.push({ project, indexed, skipped, failed });
+        }
+        const lines = summary.map((s) => `• [${s.project}] ${s.indexed} indexed, ${s.skipped} skipped (already indexed), ${s.failed} failed`);
+        const totalIndexed = summary.reduce((acc, s) => acc + s.indexed, 0);
+        const totalSkipped = summary.reduce((acc, s) => acc + s.skipped, 0);
+        const totalFailed = summary.reduce((acc, s) => acc + s.failed, 0);
+        const resultText = [
+            `Reindex complete across ${summary.length} project(s):`,
+            ...lines,
+            "",
+            `Total: ${totalIndexed} indexed, ${totalSkipped} skipped, ${totalFailed} failed.`,
+            totalSkipped > 0 && !validated.force
+                ? "Tip: use force: true to regenerate all embeddings including existing ones."
+                : "",
+        ]
+            .filter((l) => l !== "")
+            .join("\n");
+        return {
+            content: [{ type: "text", text: resultText }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Error during reindex: ${message}` }],
+        };
+    }
+}

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

@@ -2,17 +2,25 @@ import fs from "fs";
 import path from "path";
 import { UpdateDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFileHash } from "./check-freshness.js";
-function snapshotTrackedFiles(filePaths) {
+import { snapshotSection } from "../core/section-tracker.js";
+function snapshotTrackedFiles(inputs) {
     const tracked = [];
-    for (const fp of filePaths) {
+    for (const input of inputs) {
+        const fp = typeof input === "string" ? input : input.path;
         const absolutePath = path.resolve(process.cwd(), fp);
-        let mtime = new Date().toISOString();
-        let contentHash;
-        if (fs.existsSync(absolutePath)) {
-            mtime = fs.statSync(absolutePath).mtime.toISOString();
-            contentHash = computeFileHash(absolutePath);
+        const mtime = fs.existsSync(absolutePath)
+            ? fs.statSync(absolutePath).mtime.toISOString()
+            : new Date().toISOString();
+        if (typeof input !== "string" && input.lines.length > 0 && fs.existsSync(absolutePath)) {
+            const sections = input.lines
+                .filter(({ start, end }) => start <= end)
+                .map(({ start, end }) => snapshotSection(absolutePath, start, end));
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, sections });
+        }
+        else {
+            const contentHash = fs.existsSync(absolutePath) ? computeFileHash(absolutePath) : undefined;
+            tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
         }
-        tracked.push({ path: absolutePath, lastModifiedAt: mtime, ...(contentHash !== undefined && { contentHash }) });
     }
     return tracked;
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.33";
+export declare const APP_VERSION = "1.0.35";

package/dist/src/version.js

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

package/package.json

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