Skip to content

LLM Wiki is a cross-platform desktop application that turns your documents into an organized, interlinked knowledge base — automatically. Instead of traditional RAG (retrieve-and-answer from scratch every time), the LLM incrementally builds and maintains a persistent wiki from your sources。

TypeScript

perf: add project path resolver index

nash_sua0ce7eff44e7
diff --git a/src/components/editor/frontmatter-panel.tsx b/src/components/editor/frontmatter-panel.tsx
index 0759fc7b..4644f648 100644
--- a/src/components/editor/frontmatter-panel.tsx
+++ b/src/components/editor/frontmatter-panel.tsx
@@ -41,7 +41,7 @@ const TOP_LEVEL_KEYS = new Set([
export function FrontmatterPanel({ data }: FrontmatterPanelProps) {
const project = useWikiStore((s) => s.project)
- const fileTree = useWikiStore((s) => s.fileTree)
+ const projectPathIndex = useWikiStore((s) => s.projectPathIndex)
const openPathInPreview = useWikiStore((s) => s.openPathInPreview)
const title = stringValue(data.title)
@@ -150,7 +150,7 @@ export function FrontmatterPanel({ data }: FrontmatterPanelProps) {
{sources.map((source) => {
const { slug, label } = unwrapWikilink(source)
const path = sourcesRoot
- ? resolveSourceName(fileTree, slug, sourcesRoot)
+ ? resolveSourceName(projectPathIndex, slug, sourcesRoot)
: null
return (
<SourceCard
@@ -177,7 +177,7 @@ export function FrontmatterPanel({ data }: FrontmatterPanelProps) {
{related.map((entry) => {
const { slug, label } = unwrapWikilink(entry)
const path = wikiRoot
- ? resolveRelatedSlug(fileTree, slug, wikiRoot)
+ ? resolveRelatedSlug(projectPathIndex, slug, wikiRoot)
: null
return (
<RelatedChip
diff --git a/src/components/editor/wiki-reader.tsx b/src/components/editor/wiki-reader.tsx
index a1cf4e7b..39961151 100644
--- a/src/components/editor/wiki-reader.tsx
+++ b/src/components/editor/wiki-reader.tsx
@@ -39,7 +39,7 @@ interface WikiReaderProps {
*/
export function WikiReader({ body, filePath }: WikiReaderProps) {
const project = useWikiStore((s) => s.project)
- const fileTree = useWikiStore((s) => s.fileTree)
+ const projectPathIndex = useWikiStore((s) => s.projectPathIndex)
const openPathInPreview = useWikiStore((s) => s.openPathInPreview)
// Image embeds (`![[…]]`) must be rewritten BEFORE the generic
@@ -74,7 +74,7 @@ export function WikiReader({ body, filePath }: WikiReaderProps) {
return href.slice(1)
}
})()
- const path = resolveRelatedSlug(fileTree, slug, wikiRoot)
+ const path = resolveRelatedSlug(projectPathIndex, slug, wikiRoot)
if (path) openPathInPreview(path)
}
diff --git a/src/lib/wiki-page-resolver.test.ts b/src/lib/wiki-page-resolver.test.ts
index b4c41309..e42531db 100644
--- a/src/lib/wiki-page-resolver.test.ts
+++ b/src/lib/wiki-page-resolver.test.ts
@@ -1,6 +1,8 @@
import { describe, it, expect } from "vitest"
import type { FileNode } from "@/types/wiki"
import {
+ buildProjectPathIndexFromTree,
+ createEmptyProjectPathIndex,
findInTreeByName,
resolveRelatedSlug,
resolveSourceName,
@@ -38,6 +40,30 @@ const TREE: FileNode[] = [
]),
]
+const INDEX = buildProjectPathIndexFromTree(TREE)
+
+const DUP_TREE: FileNode[] = [
+ dir(`${PP}/raw`, [
+ dir(`${SOURCES}`, [file(`${SOURCES}/dup.md`)]),
+ ]),
+ dir(`${PP}/wiki`, [
+ dir(`${WIKI}/a`, [file(`${WIKI}/a/dup.md`)]),
+ dir(`${WIKI}/b`, [file(`${WIKI}/b/dup.md`)]),
+ dir(`${WIKI}/dir-only.md`, []),
+ ]),
+]
+
+const DUP_INDEX = buildProjectPathIndexFromTree(DUP_TREE)
+
+const STRAY_CHILDREN_INDEX = buildProjectPathIndexFromTree([
+ {
+ name: "file-with-children.md",
+ path: `${WIKI}/file-with-children.md`,
+ is_dir: false,
+ children: [file(`${WIKI}/should-not-index.md`)],
+ },
+])
+
describe("unwrapWikilink", () => {
it("unwraps a bare [[target]]", () => {
expect(unwrapWikilink("[[nh3-n]]")).toEqual({ slug: "nh3-n", label: "nh3-n" })
@@ -77,114 +103,164 @@ describe("unwrapWikilink", () => {
describe("findInTreeByName", () => {
it("returns null on an empty tree", () => {
- expect(findInTreeByName([], "foo.md", "/wiki/")).toBeNull()
+ expect(findInTreeByName(createEmptyProjectPathIndex(), "foo.md", "/wiki/")).toBeNull()
})
it("finds a file at the top of a subtree", () => {
- expect(findInTreeByName(TREE, "foo.md", `${WIKI}/`)).toBe(`${WIKI}/entities/foo.md`)
+ expect(findInTreeByName(INDEX, "foo.md", `${WIKI}/`)).toBe(`${WIKI}/entities/foo.md`)
})
it("recurses into nested directories", () => {
- expect(findInTreeByName(TREE, "q1.pdf", `${SOURCES}/`)).toBe(
+ expect(findInTreeByName(INDEX, "q1.pdf", `${SOURCES}/`)).toBe(
`${SOURCES}/year-2025/q1.pdf`,
)
})
it("respects pathContains as a subtree filter", () => {
// "notes.md" exists under raw/sources/year-2025 but not under wiki/.
- expect(findInTreeByName(TREE, "notes.md", `${WIKI}/`)).toBeNull()
- expect(findInTreeByName(TREE, "notes.md", `${SOURCES}/`)).toBe(
+ expect(findInTreeByName(INDEX, "notes.md", `${WIKI}/`)).toBeNull()
+ expect(findInTreeByName(INDEX, "notes.md", `${SOURCES}/`)).toBe(
`${SOURCES}/year-2025/notes.md`,
)
})
it("returns null when nothing matches", () => {
- expect(findInTreeByName(TREE, "missing.md", `${WIKI}/`)).toBeNull()
+ expect(findInTreeByName(INDEX, "missing.md", `${WIKI}/`)).toBeNull()
+ })
+
+ it("can resolve from the lightweight project path index", () => {
+ expect(findInTreeByName(INDEX, "foo.md", `${WIKI}/`)).toBe(`${WIKI}/entities/foo.md`)
+ expect(findInTreeByName(INDEX, "q1.pdf", `${SOURCES}/`)).toBe(
+ `${SOURCES}/year-2025/q1.pdf`,
+ )
+ })
+
+ it("preserves first-match DFS order for duplicate filenames in the index", () => {
+ expect(findInTreeByName(DUP_INDEX, "dup.md", `${WIKI}/`)).toBe(`${WIKI}/a/dup.md`)
+ })
+
+ it("skips earlier duplicate filenames outside the requested path scope", () => {
+ expect(findInTreeByName(DUP_INDEX, "dup.md", `${SOURCES}/`)).toBe(`${SOURCES}/dup.md`)
+ expect(findInTreeByName(DUP_INDEX, "dup.md", `${WIKI}/`)).toBe(`${WIKI}/a/dup.md`)
+ })
+
+ it("never returns directories from filename lookups in the index", () => {
+ expect(findInTreeByName(DUP_INDEX, "dir-only.md", `${WIKI}/`)).toBeNull()
+ })
+
+ it("does not descend into malformed file nodes that carry children", () => {
+ expect(findInTreeByName(STRAY_CHILDREN_INDEX, "file-with-children.md", `${WIKI}/`)).toBe(
+ `${WIKI}/file-with-children.md`,
+ )
+ expect(findInTreeByName(STRAY_CHILDREN_INDEX, "should-not-index.md", `${WIKI}/`)).toBeNull()
})
})
describe("resolveRelatedSlug", () => {
it("appends .md and finds entities by bare slug", () => {
- expect(resolveRelatedSlug(TREE, "foo", WIKI)).toBe(`${WIKI}/entities/foo.md`)
+ expect(resolveRelatedSlug(INDEX, "foo", WIKI)).toBe(`${WIKI}/entities/foo.md`)
})
it("finds queries with hyphenated slugs", () => {
- expect(resolveRelatedSlug(TREE, "what-is-foo", WIKI)).toBe(
+ expect(resolveRelatedSlug(INDEX, "what-is-foo", WIKI)).toBe(
`${WIKI}/queries/what-is-foo.md`,
)
})
it("accepts bare filename with .md extension", () => {
- expect(resolveRelatedSlug(TREE, "foo.md", WIKI)).toBe(`${WIKI}/entities/foo.md`)
+ expect(resolveRelatedSlug(INDEX, "foo.md", WIKI)).toBe(`${WIKI}/entities/foo.md`)
})
it("accepts a project-relative wiki path", () => {
- expect(resolveRelatedSlug(TREE, "wiki/entities/foo.md", WIKI)).toBe(
+ expect(resolveRelatedSlug(INDEX, "wiki/entities/foo.md", WIKI)).toBe(
`${WIKI}/entities/foo.md`,
)
})
it("accepts a project-relative path under nested wiki subfolder", () => {
- expect(resolveRelatedSlug(TREE, "wiki/concepts/bar.md", WIKI)).toBe(
+ expect(resolveRelatedSlug(INDEX, "wiki/concepts/bar.md", WIKI)).toBe(
`${WIKI}/concepts/bar.md`,
)
})
it("returns null when slug doesn't exist", () => {
- expect(resolveRelatedSlug(TREE, "ghost", WIKI)).toBeNull()
+ expect(resolveRelatedSlug(INDEX, "ghost", WIKI)).toBeNull()
})
it("returns null when path-like ref doesn't exist", () => {
- expect(resolveRelatedSlug(TREE, "wiki/entities/ghost.md", WIKI)).toBeNull()
+ expect(resolveRelatedSlug(INDEX, "wiki/entities/ghost.md", WIKI)).toBeNull()
})
it("never returns a path under raw/sources, even if a matching .md exists there", () => {
- expect(resolveRelatedSlug(TREE, "notes", WIKI)).toBeNull()
+ expect(resolveRelatedSlug(INDEX, "notes", WIKI)).toBeNull()
})
it("rejects path-like refs that point outside wiki/", () => {
- expect(resolveRelatedSlug(TREE, "raw/sources/year-2025/notes.md", WIKI)).toBeNull()
+ expect(resolveRelatedSlug(INDEX, "raw/sources/year-2025/notes.md", WIKI)).toBeNull()
+ })
+
+ it("resolves related slugs from the project path index", () => {
+ expect(resolveRelatedSlug(INDEX, "foo", WIKI)).toBe(`${WIKI}/entities/foo.md`)
+ expect(resolveRelatedSlug(INDEX, "wiki/concepts/bar.md", WIKI)).toBe(
+ `${WIKI}/concepts/bar.md`,
+ )
})
})
describe("resolveSourceName", () => {
it("finds a top-level source file", () => {
- expect(resolveSourceName(TREE, "report.pdf", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "report.pdf", SOURCES)).toBe(
`${SOURCES}/report.pdf`,
)
})
it("finds a source nested in a subfolder", () => {
- expect(resolveSourceName(TREE, "q1.pdf", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "q1.pdf", SOURCES)).toBe(
`${SOURCES}/year-2025/q1.pdf`,
)
})
it("returns null when filename doesn't exist", () => {
- expect(resolveSourceName(TREE, "ghost.pdf", SOURCES)).toBeNull()
+ expect(resolveSourceName(INDEX, "ghost.pdf", SOURCES)).toBeNull()
})
it("prefers wiki/sources/<name>.md over raw/sources for bare .md refs", () => {
// paper.md only exists under wiki/sources, so it should resolve there.
- expect(resolveSourceName(TREE, "paper.md", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "paper.md", SOURCES)).toBe(
`${WIKI}/sources/paper.md`,
)
})
it("accepts a project-relative path", () => {
- expect(resolveSourceName(TREE, "raw/sources/year-2025/q1.pdf", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "raw/sources/year-2025/q1.pdf", SOURCES)).toBe(
`${SOURCES}/year-2025/q1.pdf`,
)
})
it("accepts a raw/sources relative source identity", () => {
- expect(resolveSourceName(TREE, "year-2025/q1.pdf", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "year-2025/q1.pdf", SOURCES)).toBe(
`${SOURCES}/year-2025/q1.pdf`,
)
})
it("accepts a project-relative wiki/sources path", () => {
- expect(resolveSourceName(TREE, "wiki/sources/paper.md", SOURCES)).toBe(
+ expect(resolveSourceName(INDEX, "wiki/sources/paper.md", SOURCES)).toBe(
+ `${WIKI}/sources/paper.md`,
+ )
+ })
+
+ it("resolves source names from the project path index", () => {
+ expect(resolveSourceName(INDEX, "report.pdf", SOURCES)).toBe(`${SOURCES}/report.pdf`)
+ expect(resolveSourceName(INDEX, "year-2025/q1.pdf", SOURCES)).toBe(
+ `${SOURCES}/year-2025/q1.pdf`,
+ )
+ })
+
+ it("resolves path-like source refs from the project path index", () => {
+ expect(resolveSourceName(INDEX, "raw/sources/year-2025/q1.pdf", SOURCES)).toBe(
+ `${SOURCES}/year-2025/q1.pdf`,
+ )
+ expect(resolveSourceName(INDEX, "wiki/sources/paper.md", SOURCES)).toBe(
`${WIKI}/sources/paper.md`,
)
})
diff --git a/src/lib/wiki-page-resolver.ts b/src/lib/wiki-page-resolver.ts
index effa515f..d11a7082 100644
--- a/src/lib/wiki-page-resolver.ts
+++ b/src/lib/wiki-page-resolver.ts
@@ -1,5 +1,43 @@
import type { FileNode } from "@/types/wiki"
+export interface ProjectPathIndexEntry {
+ name: string
+ path: string
+}
+
+export interface ProjectPathIndex {
+ byPath: ReadonlyMap<string, ProjectPathIndexEntry>
+ filesByName: ReadonlyMap<string, readonly ProjectPathIndexEntry[]>
+}
+
+export function createEmptyProjectPathIndex(): ProjectPathIndex {
+ return { byPath: new Map(), filesByName: new Map() }
+}
+
+export function buildProjectPathIndexFromTree(tree: FileNode[]): ProjectPathIndex {
+ const byPath = new Map<string, ProjectPathIndexEntry>()
+ const filesByName = new Map<string, ProjectPathIndexEntry[]>()
+
+ function walk(nodes: FileNode[]) {
+ for (const node of nodes) {
+ const entry: ProjectPathIndexEntry = {
+ name: node.name,
+ path: node.path,
+ }
+ byPath.set(node.path, entry)
+ if (!node.is_dir) {
+ const bucket = filesByName.get(node.name)
+ if (bucket) bucket.push(entry)
+ else filesByName.set(node.name, [entry])
+ }
+ if (node.is_dir && node.children) walk(node.children)
+ }
+ }
+
+ walk(tree)
+ return { byPath, filesByName }
+}
+
/**
* Strip Obsidian-style `[[target]]` or `[[target|alias]]` wrapping
* from a value, returning `{ slug, label }`. Frontmatter authors
@@ -18,40 +56,28 @@ export function unwrapWikilink(s: string): { slug: string; label: string } {
}
/**
- * Walk a FileNode tree and return the absolute path of the first
- * file whose name matches `targetName`, restricted to subtrees that
- * sit underneath any directory whose absolute path contains
- * `pathContains`. Returns null when nothing matches.
+ * Return the absolute path of the first indexed file whose basename
+ * matches `targetName` and whose path contains `pathContains`.
+ * Returns null when nothing matches.
*
* Used by the frontmatter panel to resolve `related: [slug]` to a
* concrete `wiki/.../<slug>.md` path so a chip can navigate, and
* `sources: [name.pdf]` to a `raw/sources/.../name.pdf` path so a
* card can open the raw file. We intentionally take the first
- * match — duplicate basenames across subfolders are a wiki-author
- * collision the user sees in the file tree anyway, and resolving
- * arbitrarily is no worse than the prior text-only display.
+ * match in the original FileNode DFS order — duplicate basenames
+ * across subfolders are a wiki-author collision the user sees in
+ * the file tree anyway, and resolving arbitrarily is no worse than
+ * the prior text-only display.
*/
export function findInTreeByName(
- tree: FileNode[],
+ index: ProjectPathIndex,
targetName: string,
pathContains: string,
): string | null {
- function walk(nodes: FileNode[]): string | null {
- for (const node of nodes) {
- if (node.is_dir) {
- if (node.children) {
- const r = walk(node.children)
- if (r) return r
- }
- continue
- }
- if (node.name === targetName && node.path.includes(pathContains)) {
- return node.path
- }
- }
- return null
+ for (const entry of index.filesByName.get(targetName) ?? []) {
+ if (entry.path.includes(pathContains)) return entry.path
}
- return walk(tree)
+ return null
}
/**
@@ -65,7 +91,7 @@ export function findInTreeByName(
* in a same-named file from `raw/sources/`.
*/
export function resolveRelatedSlug(
- tree: FileNode[],
+ index: ProjectPathIndex,
ref: string,
wikiRoot: string,
): string | null {
@@ -74,12 +100,12 @@ export function resolveRelatedSlug(
if (ref.includes("/")) {
const projectRoot = wikiRoot.replace(/\/wiki$/, "")
const target = `${projectRoot}/${ref}`
- const found = findInTreeByPath(tree, target)
+ const found = findInTreeByPath(index, target)
return found && found.includes(`${wikiRoot}/`) ? found : null
}
const filename = ref.endsWith(".md") ? ref : `${ref}.md`
- return findInTreeByName(tree, filename, `${wikiRoot}/`)
+ return findInTreeByName(index, filename, `${wikiRoot}/`)
}
/**
@@ -93,7 +119,7 @@ export function resolveRelatedSlug(
* back to raw/sources/. Returns null if nothing matches.
*/
export function resolveSourceName(
- tree: FileNode[],
+ index: ProjectPathIndex,
ref: string,
sourcesRoot: string,
): string | null {
@@ -113,7 +139,7 @@ export function resolveSourceName(
]
for (const target of candidates) {
- const found = findInTreeByPath(tree, target)
+ const found = findInTreeByPath(index, target)
if (found) return found
}
return null
@@ -122,24 +148,15 @@ export function resolveSourceName(
// Bare .md filename → look in wiki/sources/ first (ingest's
// canonical home for source-summary pages).
if (ref.endsWith(".md")) {
- const inWiki = findInTreeByName(tree, ref, `${wikiSources}/`)
+ const inWiki = findInTreeByName(index, ref, `${wikiSources}/`)
if (inWiki) return inWiki
}
// Otherwise, search raw/sources/.
- return findInTreeByName(tree, ref, `${sourcesRoot}/`)
+ return findInTreeByName(index, ref, `${sourcesRoot}/`)
}
-function findInTreeByPath(tree: FileNode[], targetPath: string): string | null {
- function walk(nodes: FileNode[]): string | null {
- for (const node of nodes) {
- if (node.path === targetPath) return node.path
- if (node.is_dir && node.children) {
- const r = walk(node.children)
- if (r) return r
- }
- }
- return null
- }
- return walk(tree)
+function findInTreeByPath(index: ProjectPathIndex, targetPath: string): string | null {
+ const found = index.byPath.get(targetPath)
+ return found?.path ?? null
}
diff --git a/src/stores/wiki-store.test.ts b/src/stores/wiki-store.test.ts
index b4384701..1213868e 100644
--- a/src/stores/wiki-store.test.ts
+++ b/src/stores/wiki-store.test.ts
@@ -1,7 +1,72 @@
-import { describe, expect, it } from "vitest"
+import { beforeEach, describe, expect, it } from "vitest"
import { useWikiStore } from "./wiki-store"
describe("wiki preview store actions", () => {
+ beforeEach(() => {
+ useWikiStore.getState().setFileTree([])
+ useWikiStore.setState({
+ activeView: "wiki",
+ selectedFile: null,
+ fileContent: "",
+ previewContentPath: null,
+ externalPreview: null,
+ })
+ })
+
+ it("keeps the project path index in sync when setting the file tree", () => {
+ useWikiStore.getState().setFileTree([
+ {
+ name: "wiki",
+ path: "/project/wiki",
+ is_dir: true,
+ children: [
+ {
+ name: "entities",
+ path: "/project/wiki/entities",
+ is_dir: true,
+ children: [
+ { name: "foo.md", path: "/project/wiki/entities/foo.md", is_dir: false },
+ ],
+ },
+ ],
+ },
+ ])
+
+ const index = useWikiStore.getState().projectPathIndex
+ expect(index.byPath.get("/project/wiki/entities/foo.md")?.name).toBe("foo.md")
+ expect(index.filesByName.get("foo.md")?.[0]?.path).toBe(
+ "/project/wiki/entities/foo.md",
+ )
+ })
+
+ it("clears the project path index when clearing the file tree", () => {
+ useWikiStore.getState().setFileTree([
+ { name: "foo.md", path: "/project/wiki/foo.md", is_dir: false },
+ ])
+ expect(useWikiStore.getState().projectPathIndex.byPath.size).toBe(1)
+
+ useWikiStore.getState().setFileTree([])
+
+ const index = useWikiStore.getState().projectPathIndex
+ expect(index.byPath.size).toBe(0)
+ expect(index.filesByName.size).toBe(0)
+ })
+
+ it("replaces the project path index when replacing the file tree", () => {
+ useWikiStore.getState().setFileTree([
+ { name: "old.md", path: "/project/wiki/old.md", is_dir: false },
+ ])
+
+ useWikiStore.getState().setFileTree([
+ { name: "new.md", path: "/project/wiki/new.md", is_dir: false },
+ ])
+
+ const index = useWikiStore.getState().projectPathIndex
+ expect(index.filesByName.get("old.md")).toBeUndefined()
+ expect(index.byPath.get("/project/wiki/old.md")).toBeUndefined()
+ expect(index.filesByName.get("new.md")?.[0]?.path).toBe("/project/wiki/new.md")
+ })
+
it("opens a path in the wiki preview and clears external previews", () => {
useWikiStore.setState({
activeView: "chat",
diff --git a/src/stores/wiki-store.ts b/src/stores/wiki-store.ts
index 771162b3..ef88c933 100644
--- a/src/stores/wiki-store.ts
+++ b/src/stores/wiki-store.ts
@@ -1,6 +1,11 @@
import { create } from "zustand"
import type { WikiProject, FileNode } from "@/types/wiki"
import { DEFAULT_SOURCE_WATCH_CONFIG } from "@/lib/source-watch-config"
+import {
+ buildProjectPathIndexFromTree,
+ createEmptyProjectPathIndex,
+ type ProjectPathIndex,
+} from "@/lib/wiki-page-resolver"
/**
* Wire protocol used when `provider === "custom"`. Other providers have a
@@ -308,6 +313,13 @@ export interface ExternalPreview {
interface WikiState {
project: WikiProject | null
fileTree: FileNode[]
+ /**
+ * Lightweight lookup index derived from `fileTree`. Production code must
+ * update fileTree through `setFileTree` so this stays in sync; direct
+ * `useWikiStore.setState({ fileTree })` is only for tests that also reset or
+ * do not read path resolution.
+ */
+ projectPathIndex: ProjectPathIndex
selectedFile: string | null
fileContent: string
previewContentPath: string | null
@@ -373,6 +385,7 @@ interface WikiState {
export const useWikiStore = create<WikiState>((set) => ({
project: null,
fileTree: [],
+ projectPathIndex: createEmptyProjectPathIndex(),
selectedFile: null,
fileContent: "",
previewContentPath: null,
@@ -396,7 +409,8 @@ export const useWikiStore = create<WikiState>((set) => ({
dataVersion: 0,
setProject: (project) => set({ project }),
- setFileTree: (fileTree) => set({ fileTree }),
+ setFileTree: (fileTree) =>
+ set({ fileTree, projectPathIndex: buildProjectPathIndexFromTree(fileTree) }),
setSelectedFile: (selectedFile) =>
set({ selectedFile, previewContentPath: null, externalPreview: null }),
setFileContent: (fileContent) => set({ fileContent }),