Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

fix(vault): stop logging duplicate stems; the integrity report already carries them

Ronalds Palacisf29078ac6fed
diff --git a/lib/vault/dup-stems.test.ts b/lib/vault/dup-stems.test.ts
index 649e2ce..b255703 100644
--- a/lib/vault/dup-stems.test.ts
+++ b/lib/vault/dup-stems.test.ts
@@ -2,16 +2,14 @@ import { test, expect, beforeEach } from "bun:test";
import fs from "node:fs";
import path from "node:path";
import { TEST_VAULT } from "../../test/setup";
-import { rebuildIndex, refreshPaths } from "./store";
+import { rebuildIndex, refreshPaths, vaultConventions } from "./store";
/**
- * A duplicated filename stem is a permanent property of a vault's layout — no reindex resolves it.
- * The warning therefore has to be edge-triggered, because `recomputeLinks` runs on every write and
- * every watcher flush. Warning on state instead of on change is what made a 4-README vault reprint
- * the same line into the deploy log forever.
- *
- * "Already warned" is process-lifetime state, so each test below claims its OWN stem. Sharing one
- * across tests would make them order-dependent — which is the honest cost of the memo, not a bug.
+ * A duplicated filename stem is a property of the vault's layout, not an event: no reindex
+ * resolves it, and `recomputeLinks` runs on every write, every watcher flush and every rebuild.
+ * Logging it from there put the same line in the deploy log forever. It belongs in the integrity
+ * report, which is queryable on demand — so the console stays silent no matter how the index is
+ * rebuilt, and the finding is still available in full.
*/
function write(rel: string, body: string) {
@@ -20,16 +18,20 @@ function write(rel: string, body: string) {
fs.writeFileSync(abs, body);
}
-function warnings(fn: () => void): string[] {
+/** Anything the vault index writes to console.warn / console.error while `fn` runs. */
+function consoleOutput(fn: () => void): string[] {
const out: string[] = [];
- const orig = console.warn;
+ const warn = console.warn;
+ const error = console.error;
console.warn = (...a: unknown[]) => void out.push(a.join(" "));
+ console.error = (...a: unknown[]) => void out.push(a.join(" "));
try {
fn();
} finally {
- console.warn = orig;
+ console.warn = warn;
+ console.error = error;
}
- return out.filter((l) => l.includes("duplicate stem"));
+ return out;
}
/** Four notes sharing one stem, the layout that produced the original report. */
@@ -45,42 +47,44 @@ beforeEach(() => {
fs.mkdirSync(TEST_VAULT, { recursive: true });
});
-test("duplicate stems nothing links to stay silent", () => {
- fourWay("OVERVIEW");
- write("notes/a.md", "# A\n\nno wikilinks here\n");
- expect(warnings(rebuildIndex)).toEqual([]);
-});
-
-test("a linked duplicate stem is reported once, not on every later reindex", () => {
+test("a linked duplicate stem is never logged — not once, not on any reindex", () => {
fourWay("README");
write("notes/a.md", "# A\n\nsee [[README]] for context\n");
- const first = warnings(rebuildIndex);
- expect(first).toHaveLength(1);
- // Actionable: names the note holding the link, the winner, and what it shadows.
- expect(first[0]).toContain("notes/a.md");
- expect(first[0]).toContain("resolves to README.md");
- expect(first[0]).toContain("leads/brands/README.md");
+ expect(consoleOutput(rebuildIndex)).toEqual([]);
- // Unrelated writes each re-run recomputeLinks. None of them may reprint.
+ // Every write re-runs recomputeLinks; a full rebuild runs it too. All must stay silent.
for (let i = 0; i < 3; i++) {
write(`notes/b${i}.md`, `# B${i}\n\nunrelated\n`);
- expect(warnings(() => refreshPaths([`notes/b${i}.md`]))).toEqual([]);
+ expect(consoleOutput(() => refreshPaths([`notes/b${i}.md`]))).toEqual([]);
}
- // Neither may a full rebuild.
- expect(warnings(rebuildIndex)).toEqual([]);
+ expect(consoleOutput(rebuildIndex)).toEqual([]);
});
-test("a collision that is resolved and then reintroduced warns again", () => {
- fourWay("GUIDE");
- write("notes/a.md", "# A\n\nsee [[GUIDE]]\n");
- expect(warnings(rebuildIndex)).toHaveLength(1);
+test("the collision is reported in full by the integrity report instead", () => {
+ fourWay("README");
+ write("notes/a.md", "# A\n\nsee [[README]] for context\n");
+ rebuildIndex();
+
+ const { integrity } = vaultConventions();
+ const dupe = integrity.duplicateStems.find((d) => d.stem === "README");
+ expect(dupe).toBeDefined();
+ expect(dupe!.paths).toEqual(["README.md", "archive/README.md", "leads/README.md", "leads/brands/README.md"]);
+ // Names the note to edit — the signal the log line carried, kept.
+ expect(dupe!.linkedFrom).toBe("notes/a.md");
+ expect(integrity.duplicateStemWarning).toContain("notes/a.md");
+ expect(integrity.duplicateStemWarning).toContain("resolves to README.md");
+});
- // Resolve it: nothing links the ambiguous stem any more.
- write("notes/a.md", "# A\n\nno link now\n");
- expect(warnings(() => refreshPaths(["notes/a.md"]))).toEqual([]);
+test("a collision no wikilink reaches is listed but not flagged", () => {
+ fourWay("OVERVIEW");
+ write("notes/a.md", "# A\n\nno wikilinks here\n");
+ rebuildIndex();
- // Reintroduce it — the earlier report must not suppress the new one.
- write("notes/a.md", "# A\n\nsee [[GUIDE]] again\n");
- expect(warnings(() => refreshPaths(["notes/a.md"]))).toHaveLength(1);
+ const { integrity } = vaultConventions();
+ // Still visible — the report is the full picture.
+ expect(integrity.duplicateStems.find((d) => d.stem === "OVERVIEW")).toBeDefined();
+ expect(integrity.duplicateStems.find((d) => d.stem === "OVERVIEW")!.linkedFrom).toBeUndefined();
+ // But no warning: nothing resolves to the wrong note, so there is nothing to act on.
+ expect(integrity.duplicateStemWarning).toBeUndefined();
});
diff --git a/lib/vault/store.ts b/lib/vault/store.ts
index b4c0e6f..594f0b2 100644
--- a/lib/vault/store.ts
+++ b/lib/vault/store.ts
@@ -46,18 +46,6 @@ let state: IndexState | null = null;
let watcher: FSWatcher | null = null;
let watchedDir = "";
-/**
- * Ambiguous stems already reported, and the vault they belong to.
- *
- * `recomputeLinks` runs on every write, every watcher flush and every full rebuild, so anything
- * warned unconditionally from it reprints for as long as the vault keeps the collision — which is
- * forever, because no reindex resolves a naming collision. Remembering what was already said turns
- * the warning from level-triggered to edge-triggered: it fires when a collision appears, and stays
- * quiet afterwards. Resolved stems are dropped from the set, so a collision reintroduced later is
- * reported again.
- */
-let warnedStems = { dir: "", stems: new Set<string>() };
-
function newIndex(): MiniSearch<IndexDoc> {
return new MiniSearch<IndexDoc>({
fields: ["title", "aliases", "tags", "body", "folder", "type"],
@@ -126,28 +114,11 @@ function recomputeLinks(s: IndexState): void {
s.duplicateStems.set(slug, dupes);
}
}
- // Only warn when something actually links the ambiguous stem: two notes sharing a filename
- // nothing references is harmless (every vault has a few READMEs). Name a note that links it,
- // so the warning points at the file to edit instead of just asserting a collision exists.
- // The full set stays in s.duplicateStems for the integrity report either way.
- const linkedFrom = new Map<string, string>();
- for (const [src, stems] of s.linksBySource) {
- for (const stem of stems) if (!linkedFrom.has(stem)) linkedFrom.set(stem, src);
- }
- if (warnedStems.dir !== s.dir) warnedStems = { dir: s.dir, stems: new Set() };
- const ambiguous = new Set<string>();
- for (const [slug, paths] of s.duplicateStems) {
- const src = linkedFrom.get(slug);
- if (src === undefined) continue;
- ambiguous.add(slug);
- if (warnedStems.stems.has(slug)) continue; // already reported — see warnedStems
- const [winner, ...shadowed] = paths;
- console.warn(
- `[vault] duplicate stem "${slug}" — [[${slug}]] (linked from ${src}) resolves to ${winner}, ` +
- `shadowing ${shadowed.join(", ")}.`,
- );
- }
- warnedStems.stems = ambiguous;
+ // A stem collision is a property of the vault's layout, not an event, so it is reported by
+ // `vaultConventions().integrity` — queryable on demand via brain_schema and the dashboard —
+ // and deliberately not logged. Console output is the wrong channel for standing state: it
+ // cannot be dismissed or acted on where it appears, and printing from here (which runs on
+ // every write, flush and rebuild) is what buried the deploy log in the first place.
s.outEdges = new Map();
s.inEdges = new Map();
@@ -515,6 +486,22 @@ export function vaultConventions() {
else if (n.validUntil != null && n.validUntil < now) expired++;
}
+ // Which ambiguous stems a wikilink actually reaches. Computed here, on demand, rather than in
+ // recomputeLinks: that runs on every write and this is read only when someone asks for the
+ // report. `linkedFrom` names one note holding such a link, so the finding points at a file to
+ // edit instead of only asserting that a collision exists somewhere.
+ const linkedFrom = new Map<string, string>();
+ for (const [src, stems] of s.linksBySource) {
+ for (const stem of stems) if (!linkedFrom.has(stem)) linkedFrom.set(stem, src);
+ }
+ const duplicateStems = [...s.duplicateStems.entries()].map(([stem, paths]) => {
+ const from = linkedFrom.get(stem);
+ return from === undefined ? { stem, paths } : { stem, paths, linkedFrom: from };
+ });
+ const misresolving = duplicateStems.filter(
+ (d): d is { stem: string; paths: string[]; linkedFrom: string } => "linkedFrom" in d,
+ );
+
return {
noteCount: s.notes.size,
archivedCount: archived,
@@ -527,11 +514,22 @@ export function vaultConventions() {
.map(([status, count]) => ({ status, count })),
ranking: authorityRules(),
integrity: {
- duplicateStems: [...s.duplicateStems.entries()].map(([stem, paths]) => ({ stem, paths })),
+ duplicateStems,
malformedFrontmatter: malformed,
unrecognizedStatus: unknownStatus,
- ...(s.duplicateStems.size > 0
- ? { duplicateStemWarning: "Wikilinks to a duplicated stem resolve to the first path only. Rename one." }
+ // Only flag collisions a link actually hits. Two notes sharing a filename nothing
+ // references changes no resolution — every vault has a few READMEs — so warning about
+ // those buries the one collision that is silently sending a wikilink to the wrong note.
+ ...(misresolving.length > 0
+ ? {
+ duplicateStemWarning:
+ `Wikilinks to a duplicated stem resolve to the first path only. ` +
+ misresolving
+ .map((d) => `[[${d.stem}]] (linked from ${d.linkedFrom}) resolves to ${d.paths[0]}`)
+ .join("; ") +
+ `. Rename the colliding file — a folder-qualified link like [[folder/${misresolving[0].stem}]] ` +
+ `will not help, the path is only a hint and still collapses to the bare stem.`,
+ }
: {}),
...(malformed.length > 0
? {