obsidian-mcp-pro 2.0.0 → 3.0.0

package/build/tools/links.js

@@ -1,11 +1,16 @@
+import path from "path";
 import { z } from "zod";
-import { listNotes, getNoteStats } from "../lib/vault.js";
+import { listNotes, getNoteStats, getVaultRootRealPath } from "../lib/vault.js";
 import { readAllCached } from "../lib/index-cache.js";
-import { extractWikilinks, resolveWikilink, extractAliases } from "../lib/markdown.js";
-import { sanitizeError } from "../lib/errors.js";
+import { extractWikilinks, extractAliases } from "../lib/markdown.js";
+import { escapeControlChars, sanitizeError } from "../lib/errors.js";
 import { log } from "../lib/logger.js";
 const GRAPH_CACHE_TTL_MS = 30_000;
 const GRAPH_CACHE_MAX_ENTRIES = 32;
+const GRAPH_FINGERPRINT_CONCURRENCY = 64;
+function displayLinkValue(value) {
+    return escapeControlChars(value);
+}
 const graphCache = new Map();
 // Map iteration order = insertion order; delete+set to refresh recency.
 function setGraphCache(key, entry) {
@@ -19,26 +24,122 @@ function setGraphCache(key, entry) {
         graphCache.delete(oldest);
     }
 }
-async function fingerprintVault(vaultPath, notes) {
+function fingerprintFromMtimes(notes, mtimes) {
     // Accumulate a 32-bit FNV-1a hash over "<sortedPath>|<mtimeMs>;" per note.
     // Catches add+delete churn and mtime-restoring edits that count+max-mtime
     // alone would miss.
     const sorted = [...notes].sort();
     let hash = 0x811c9dc5;
-    const CONCURRENCY = 16;
-    for (let i = 0; i < sorted.length; i += CONCURRENCY) {
-        const slice = sorted.slice(i, i + CONCURRENCY);
-        const stats = await Promise.all(slice.map((n) => getNoteStats(vaultPath, n).catch(() => null)));
+    for (const note of sorted) {
+        const mtime = mtimes.get(note) ?? 0;
+        const entry = `${note}|${mtime};`;
+        for (let k = 0; k < entry.length; k++) {
+            hash ^= entry.charCodeAt(k);
+            hash = Math.imul(hash, 0x01000193);
+        }
+    }
+    return `${sorted.length}:${(hash >>> 0).toString(16)}`;
+}
+async function fingerprintVault(vaultPath, notes) {
+    const mtimes = new Map();
+    const sorted = [...notes].sort();
+    const realVaultRoot = await getVaultRootRealPath(vaultPath);
+    for (let i = 0; i < sorted.length; i += GRAPH_FINGERPRINT_CONCURRENCY) {
+        const slice = sorted.slice(i, i + GRAPH_FINGERPRINT_CONCURRENCY);
+        const stats = await Promise.all(slice.map((n) => getNoteStats(vaultPath, n, { realVaultRoot }).catch(() => null)));
         for (let j = 0; j < slice.length; j++) {
             const mtime = stats[j]?.modified?.getTime() ?? 0;
-            const entry = `${slice[j]}|${mtime};`;
-            for (let k = 0; k < entry.length; k++) {
-                hash ^= entry.charCodeAt(k);
-                hash = Math.imul(hash, 0x01000193);
+            mtimes.set(slice[j], mtime);
+        }
+    }
+    return fingerprintFromMtimes(sorted, mtimes);
+}
+function buildSourceLookup(notes) {
+    const lookup = new Map();
+    for (const notePath of notes) {
+        const normalized = notePath.replace(/\.md$/i, "").toLowerCase();
+        const exactKey = `exact:${normalized}`;
+        if (!lookup.has(exactKey))
+            lookup.set(exactKey, notePath);
+        const basename = normalized.split("/").pop() ?? normalized;
+        if (!lookup.has(`base:${basename}`)) {
+            lookup.set(`base:${basename}`, notePath);
+        }
+    }
+    return lookup;
+}
+function sharedPathDepth(a, b) {
+    const as = a.toLowerCase().split("/");
+    const bs = b.toLowerCase().split("/");
+    let i = 0;
+    const max = Math.min(as.length, bs.length);
+    while (i < max && as[i] === bs[i])
+        i++;
+    return i;
+}
+function buildNotePathIndex(notes) {
+    const exact = new Map();
+    const basename = new Map();
+    for (const notePath of notes) {
+        const normalized = notePath.replace(/\.md$/i, "").toLowerCase();
+        if (!exact.has(normalized))
+            exact.set(normalized, notePath);
+        const noteBasename = path
+            .basename(notePath, path.extname(notePath))
+            .toLowerCase();
+        const matches = basename.get(noteBasename);
+        if (matches) {
+            matches.push(notePath);
+        }
+        else {
+            basename.set(noteBasename, [notePath]);
+        }
+    }
+    return { exact, basename };
+}
+function resolveWikilinkWithIndex(link, currentNotePath, allNotePaths, index, aliasMap) {
+    const cleanLink = link.split("#")[0].split("^")[0].trim();
+    if (!cleanLink)
+        return null;
+    const normalizedLink = cleanLink.replace(/\.md$/i, "");
+    const normalizedLinkLower = normalizedLink.toLowerCase();
+    const exact = index.exact.get(normalizedLinkLower);
+    if (exact)
+        return exact;
+    if (normalizedLink.includes("/")) {
+        const suffixCandidates = [];
+        for (const notePath of allNotePaths) {
+            const withoutExt = notePath.replace(/\.md$/i, "").toLowerCase();
+            if (withoutExt.endsWith(normalizedLinkLower)) {
+                const prefix = withoutExt.slice(0, withoutExt.length - normalizedLinkLower.length);
+                if (prefix === "" || prefix.endsWith("/"))
+                    suffixCandidates.push(notePath);
             }
         }
+        if (suffixCandidates.length === 1)
+            return suffixCandidates[0];
+        if (suffixCandidates.length > 1) {
+            return nearestNotePath(currentNotePath, suffixCandidates);
+        }
     }
-    return `${sorted.length}:${(hash >>> 0).toString(16)}`;
+    const linkBasename = path.basename(normalizedLink).toLowerCase();
+    const basenameCandidates = index.basename.get(linkBasename) ?? [];
+    if (basenameCandidates.length === 1)
+        return basenameCandidates[0];
+    if (basenameCandidates.length > 1) {
+        return nearestNotePath(currentNotePath, basenameCandidates);
+    }
+    return aliasMap.get(normalizedLinkLower) ?? null;
+}
+function nearestNotePath(currentNotePath, candidates) {
+    const sourceDir = path.dirname(currentNotePath).replace(/\\/g, "/");
+    return [...candidates].sort((a, b) => {
+        const da = sharedPathDepth(sourceDir, path.dirname(a).replace(/\\/g, "/"));
+        const db = sharedPathDepth(sourceDir, path.dirname(b).replace(/\\/g, "/"));
+        if (da !== db)
+            return db - da;
+        return a.length - b.length;
+    })[0];
 }
 async function buildLinkGraph(vaultPath, folder) {
     const cacheKey = `${vaultPath}::${folder ?? ""}`;
@@ -56,6 +157,8 @@ async function buildLinkGraph(vaultPath, folder) {
     const backlinks = new Map();
     const rawLinks = new Map();
     const noteLines = new Map();
+    const brokenLinks = new Map();
+    const outlinkDetails = new Map();
     // Initialize sets for all notes
     for (const notePath of allNotes) {
         outlinks.set(notePath, new Set());
@@ -63,7 +166,7 @@ async function buildLinkGraph(vaultPath, folder) {
     }
     // Read notes via the shared mtime cache so repeated graph builds (and
     // overlapping search_notes / get_tags scans) skip re-reads.
-    const { contents: noteContents } = await readAllCached(vaultPath, allNotes, (note, err) => {
+    const { contents: noteContents, mtimes } = await readAllCached(vaultPath, allNotes, (note, err) => {
         log.warn("link graph: note read failed", { note, err });
     });
     // Build alias map first so any note can link to any other by alias
@@ -81,16 +184,18 @@ async function buildLinkGraph(vaultPath, folder) {
                 continue;
             const prior = aliasMap.get(key);
             if (prior && prior !== notePath) {
-                log.warn("Duplicate alias", { alias, a: prior, b: notePath });
+                log.warn("Duplicate alias", { alias, notes: [prior, notePath] });
             }
             aliasMap.set(key, notePath);
         }
     }
+    const pathIndex = buildNotePathIndex(allNotes);
     for (const notePath of allNotes) {
         const content = noteContents.get(notePath);
         if (content === undefined)
             continue;
-        noteLines.set(notePath, content.split("\n"));
+        const lines = content.split("\n");
+        noteLines.set(notePath, lines);
         const links = extractWikilinks(content);
         // Fill in source for each link
         for (const link of links) {
@@ -98,12 +203,19 @@ async function buildLinkGraph(vaultPath, folder) {
         }
         rawLinks.set(notePath, links);
         const outSet = outlinks.get(notePath) ?? new Set();
+        const details = [];
         for (const link of links) {
             // Strip heading/block refs for resolution (e.g., "note#heading" -> "note")
             const targetBase = link.target.split("#")[0].trim();
             if (!targetBase)
                 continue;
-            const resolved = resolveWikilink(targetBase, notePath, allNotes, { aliasMap });
+            const resolved = resolveWikilinkWithIndex(targetBase, notePath, allNotes, pathIndex, aliasMap);
+            details.push({
+                target: link.target,
+                resolvedPath: resolved,
+                isValid: resolved !== null,
+                isEmbed: link.isEmbed,
+            });
             if (resolved) {
                 outSet.add(resolved);
                 // Ensure backlinks set exists for target
@@ -112,8 +224,21 @@ async function buildLinkGraph(vaultPath, folder) {
                 }
                 backlinks.get(resolved).add(notePath);
             }
+            else {
+                const lineInfo = findLineWithLink(lines, link.target);
+                const broken = {
+                    sourcePath: notePath,
+                    targetLink: link.target,
+                    line: lineInfo.line,
+                };
+                if (!brokenLinks.has(notePath)) {
+                    brokenLinks.set(notePath, []);
+                }
+                brokenLinks.get(notePath).push(broken);
+            }
         }
         outlinks.set(notePath, outSet);
+        outlinkDetails.set(notePath, details);
     }
     const data = {
         allNotes,
@@ -122,8 +247,12 @@ async function buildLinkGraph(vaultPath, folder) {
         rawLinks,
         noteLines,
         aliasMap,
+        brokenLinks,
+        sourceLookup: buildSourceLookup(allNotes),
+        pathIndex,
+        outlinkDetails,
     };
-    const fingerprint = await fingerprintVault(vaultPath, allNotes);
+    const fingerprint = fingerprintFromMtimes(allNotes, mtimes);
     setGraphCache(cacheKey, { data, fingerprint, cachedAt: Date.now() });
     return data;
 }
@@ -212,7 +341,7 @@ export function registerLinkTools(server, vaultPath) {
                 }
             }
             if (!resolvedTarget) {
-                return errorResult(`No note found matching path: ${targetPath}`);
+                return errorResult(`No note found matching path: ${displayLinkValue(targetPath)}`);
             }
             const backlinkSources = graph.backlinks.get(resolvedTarget);
             if (!backlinkSources || backlinkSources.size === 0) {
@@ -220,7 +349,7 @@ export function registerLinkTools(server, vaultPath) {
                     content: [
                         {
                             type: "text",
-                            text: `No backlinks found for: ${resolvedTarget}`,
+                            text: `No backlinks found for: ${displayLinkValue(resolvedTarget)}`,
                         },
                     ],
                 };
@@ -237,9 +366,7 @@ export function registerLinkTools(server, vaultPath) {
                     // resolve here exactly as they did during graph build. Without
                     // it, the source slipped into the backlink set during build but
                     // produced an empty line/context in this display pass.
-                    const resolved = resolveWikilink(base, sourcePath, graph.allNotes, {
-                        aliasMap: graph.aliasMap,
-                    });
+                    const resolved = resolveWikilinkWithIndex(base, sourcePath, graph.allNotes, graph.pathIndex, graph.aliasMap);
                     return resolved === resolvedTarget;
                 });
                 if (relevantLinks.length > 0) {
@@ -266,12 +393,12 @@ export function registerLinkTools(server, vaultPath) {
                 return true;
             });
             const output = [
-                `Backlinks to: ${resolvedTarget}`,
+                `Backlinks to: ${displayLinkValue(resolvedTarget)}`,
                 `Found: ${deduped.length} backlink(s)\n`,
                 ...deduped.map((r) => {
                     const lineStr = r.line > 0 ? `:${r.line}` : "";
-                    const contextStr = r.context ? `  → ${r.context}` : "";
-                    return `- ${r.source}${lineStr}${contextStr}`;
+                    const contextStr = r.context ? `  → ${displayLinkValue(r.context)}` : "";
+                    return `- ${displayLinkValue(r.source)}${lineStr}${contextStr}`;
                 }),
             ].join("\n");
             return { content: [{ type: "text", text: output }] };
@@ -309,47 +436,19 @@ export function registerLinkTools(server, vaultPath) {
             // get_backlinks does).
             const targetNormalized = notePath.replace(/\.md$/i, "").toLowerCase();
             const targetBasename = targetNormalized.split("/").pop() ?? targetNormalized;
-            let resolvedSource = null;
-            for (const p of graph.allNotes) {
-                if (p.replace(/\.md$/i, "").toLowerCase() === targetNormalized) {
-                    resolvedSource = p;
-                    break;
-                }
-            }
+            const resolvedSource = graph.sourceLookup.get(`exact:${targetNormalized}`) ??
+                graph.sourceLookup.get(`base:${targetBasename}`) ??
+                null;
             if (!resolvedSource) {
-                for (const p of graph.allNotes) {
-                    const base = p.replace(/\.md$/i, "").split("/").pop()?.toLowerCase();
-                    if (base === targetBasename) {
-                        resolvedSource = p;
-                        break;
-                    }
-                }
-            }
-            if (!resolvedSource) {
-                return errorResult(`No note found matching path: ${notePath}`);
-            }
-            const links = graph.rawLinks.get(resolvedSource) ?? [];
-            const results = [];
-            for (const link of links) {
-                const targetBase = link.target.split("#")[0].trim();
-                if (!targetBase)
-                    continue;
-                const resolved = resolveWikilink(targetBase, resolvedSource, graph.allNotes, {
-                    aliasMap: graph.aliasMap,
-                });
-                results.push({
-                    target: link.target,
-                    resolvedPath: resolved,
-                    isValid: resolved !== null,
-                    isEmbed: link.isEmbed,
-                });
+                return errorResult(`No note found matching path: ${displayLinkValue(notePath)}`);
             }
+            const results = graph.outlinkDetails.get(resolvedSource) ?? [];
             if (results.length === 0) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `No outgoing links found in: ${resolvedSource}`,
+                            text: `No outgoing links found in: ${displayLinkValue(resolvedSource)}`,
                         },
                     ],
                 };
@@ -357,21 +456,21 @@ export function registerLinkTools(server, vaultPath) {
             const valid = results.filter((r) => r.isValid);
             const broken = results.filter((r) => !r.isValid);
             const lines = [
-                `Outgoing links from: ${resolvedSource}`,
+                `Outgoing links from: ${displayLinkValue(resolvedSource)}`,
                 `Total: ${results.length} (${valid.length} valid, ${broken.length} broken)\n`,
             ];
             if (valid.length > 0) {
                 lines.push("Valid links:");
                 for (const r of valid) {
                     const embedPrefix = r.isEmbed ? "📎 " : "";
-                    lines.push(`  ${embedPrefix}[[${r.target}]] → ${r.resolvedPath}`);
+                    lines.push(`  ${embedPrefix}[[${displayLinkValue(r.target)}]] → ${displayLinkValue(r.resolvedPath ?? "")}`);
                 }
             }
             if (broken.length > 0) {
                 lines.push("\nBroken links:");
                 for (const r of broken) {
                     const embedPrefix = r.isEmbed ? "📎 " : "";
-                    lines.push(`  ${embedPrefix}[[${r.target}]] → (not found)`);
+                    lines.push(`  ${embedPrefix}[[${displayLinkValue(r.target)}]] → (not found)`);
                 }
             }
             return { content: [{ type: "text", text: lines.join("\n") }] };
@@ -436,14 +535,14 @@ export function registerLinkTools(server, vaultPath) {
             ];
             lines.push(`Fully isolated (no links in or out): ${fullyIsolated.length}`);
             for (const note of cappedIsolated) {
-                lines.push(`  - ${note.path}`);
+                lines.push(`  - ${displayLinkValue(note.path)}`);
             }
             if (cappedIsolated.length < fullyIsolated.length) {
                 lines.push(`  ... and ${fullyIsolated.length - cappedIsolated.length} more`);
             }
             lines.push(`\nNo backlinks (not linked by any note): ${noBacklinks.length}`);
             for (const note of cappedNoBacklinks) {
-                lines.push(`  - ${note.path}`);
+                lines.push(`  - ${displayLinkValue(note.path)}`);
             }
             if (cappedNoBacklinks.length < noBacklinks.length) {
                 lines.push(`  ... and ${noBacklinks.length - cappedNoBacklinks.length} more`);
@@ -451,7 +550,7 @@ export function registerLinkTools(server, vaultPath) {
             if (includeOutlinksCheck) {
                 lines.push(`\nNo outlinks (links to no other notes): ${noOutlinks.length}`);
                 for (const note of cappedNoOutlinks) {
-                    lines.push(`  - ${note.path}`);
+                    lines.push(`  - ${displayLinkValue(note.path)}`);
                 }
                 if (cappedNoOutlinks.length < noOutlinks.length) {
                     lines.push(`  ... and ${noOutlinks.length - cappedNoOutlinks.length} more`);
@@ -492,60 +591,20 @@ export function registerLinkTools(server, vaultPath) {
         },
     }, async ({ folder, maxResults }) => {
         try {
-            // Get all notes in vault for resolution, but only scan the folder.
-            // Reads go through the shared mtime cache (`readAllCached`) so the
-            // scan parallelizes within the cache's concurrency cap and re-runs
-            // hit the cache instead of stat+read every file again - matching
-            // the pattern search_notes uses for similar full-vault sweeps.
-            const allNotes = await listNotes(vaultPath);
-            const scanNotes = folder ? await listNotes(vaultPath, folder) : allNotes;
-            // Build the alias map from the full vault so cross-folder alias
-            // resolution still works when scoping to a single folder.
-            const { contents: allContents } = await readAllCached(vaultPath, allNotes, (note, err) => {
-                log.warn("find_broken_links: note read failed", { note, err });
-            });
-            const aliasMap = new Map();
-            for (const notePath of allNotes) {
-                const content = allContents.get(notePath);
-                if (content === undefined)
-                    continue;
-                for (const alias of extractAliases(content)) {
-                    const key = alias.toLowerCase();
-                    if (!key)
-                        continue;
-                    aliasMap.set(key, notePath);
-                }
-            }
+            // Validate and capture folder scope before the whole-vault graph work
+            // so a missing folder fails fast. Resolution still uses the full graph.
+            const scanNotes = folder ? await listNotes(vaultPath, folder) : null;
+            const graph = await buildLinkGraph(vaultPath);
+            const notesToScan = scanNotes ?? graph.allNotes;
             const brokenBySource = new Map();
-            for (const notePath of scanNotes) {
-                const content = allContents.get(notePath);
-                if (content === undefined)
+            for (const notePath of notesToScan) {
+                const brokenLinks = graph.brokenLinks.get(notePath);
+                if (!brokenLinks || brokenLinks.length === 0)
                     continue;
-                const lines = content.split("\n");
-                const links = extractWikilinks(content);
-                for (const link of links) {
-                    const targetBase = link.target.split("#")[0].trim();
-                    if (!targetBase)
-                        continue;
-                    const resolved = resolveWikilink(targetBase, notePath, allNotes, {
-                        aliasMap,
-                    });
-                    if (!resolved) {
-                        const lineInfo = findLineWithLink(lines, link.target);
-                        const broken = {
-                            sourcePath: notePath,
-                            targetLink: link.target,
-                            line: lineInfo.line,
-                        };
-                        if (!brokenBySource.has(notePath)) {
-                            brokenBySource.set(notePath, []);
-                        }
-                        brokenBySource.get(notePath).push(broken);
-                    }
-                }
+                brokenBySource.set(notePath, brokenLinks);
             }
             if (brokenBySource.size === 0) {
-                const scopeStr = folder ? ` in folder: ${folder}` : "";
+                const scopeStr = folder ? ` in folder: ${displayLinkValue(folder)}` : "";
                 return {
                     content: [
                         {
@@ -560,18 +619,18 @@ export function registerLinkTools(server, vaultPath) {
                 totalBroken += brokenLinks.length;
             }
             const lines = [];
-            const scopeStr = folder ? ` (folder: ${folder})` : "";
+            const scopeStr = folder ? ` (folder: ${displayLinkValue(folder)})` : "";
             lines.push(`Broken links report${scopeStr}\n`);
             let shown = 0;
             for (const [sourcePath, brokenLinks] of brokenBySource) {
                 if (shown >= maxResults)
                     break;
-                lines.push(`${sourcePath}:`);
+                lines.push(`${displayLinkValue(sourcePath)}:`);
                 for (const bl of brokenLinks) {
                     if (shown >= maxResults)
                         break;
                     const lineStr = bl.line > 0 ? ` (line ${bl.line})` : "";
-                    lines.push(`  - [[${bl.targetLink}]]${lineStr}`);
+                    lines.push(`  - [[${displayLinkValue(bl.targetLink)}]]${lineStr}`);
                     shown++;
                 }
                 lines.push("");
@@ -653,7 +712,7 @@ export function registerLinkTools(server, vaultPath) {
                 }
             }
             if (!resolvedStart) {
-                return errorResult(`No note found matching path: ${startPath}`);
+                return errorResult(`No note found matching path: ${displayLinkValue(startPath)}`);
             }
             // BFS traversal with maxResults cap to prevent explosion at higher depths
             const visited = new Map();
@@ -715,7 +774,7 @@ export function registerLinkTools(server, vaultPath) {
                     content: [
                         {
                             type: "text",
-                            text: `No neighbors found for: ${resolvedStart} (depth: ${depth}, direction: ${direction})`,
+                            text: `No neighbors found for: ${displayLinkValue(resolvedStart)} (depth: ${depth}, direction: ${direction})`,
                         },
                     ],
                 };
@@ -730,9 +789,9 @@ export function registerLinkTools(server, vaultPath) {
             }
             const truncatedStr = truncated ? " (TRUNCATED)" : "";
             const lines = [
-                `Graph neighbors of: ${resolvedStart}`,
+                `Graph neighbors of: ${displayLinkValue(resolvedStart)}`,
                 `Direction: ${direction} | Max depth: ${depth} | Found: ${visited.size} note(s)${truncatedStr}\n`,
-                resolvedStart,
+                displayLinkValue(resolvedStart),
             ];
             const sortedDepths = [...byDepth.keys()].sort((a, b) => a - b);
             for (const d of sortedDepths) {
@@ -745,7 +804,7 @@ export function registerLinkTools(server, vaultPath) {
                         : neighbor.direction === "outbound"
                             ? "→"
                             : "↔";
-                    lines.push(`${indent}${arrow} ${neighbor.path} (depth ${d})`);
+                    lines.push(`${indent}${arrow} ${displayLinkValue(neighbor.path)} (depth ${d})`);
                 }
             }
             if (truncated) {