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

test: Tier 5 LLM prompt contract tests

nash_sudd02c0772d67
diff --git a/src/lib/enrich-wikilinks.test.ts b/src/lib/enrich-wikilinks.test.ts
new file mode 100644
index 00000000..f38d02ee
--- /dev/null
+++ b/src/lib/enrich-wikilinks.test.ts
@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach, vi } from "vitest"
+import type { LlmConfig } from "@/stores/wiki-store"
+
+// Mock the LLM client (capture prompts) and the Tauri fs commands (no real FS).
+vi.mock("./llm-client", () => ({
+ streamChat: vi.fn(),
+}))
+vi.mock("@/commands/fs", () => ({
+ readFile: vi.fn(),
+ writeFile: vi.fn(),
+ listDirectory: vi.fn(),
+}))
+
+import { enrichWithWikilinks } from "./enrich-wikilinks"
+import { streamChat } from "./llm-client"
+import { readFile, writeFile } from "@/commands/fs"
+import { useWikiStore } from "@/stores/wiki-store"
+
+const mockStreamChat = vi.mocked(streamChat)
+const mockReadFile = vi.mocked(readFile)
+const mockWriteFile = vi.mocked(writeFile)
+
+function fakeLlmConfig(): LlmConfig {
+ return {
+ provider: "openai",
+ apiKey: "k",
+ model: "m",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 128000,
+ }
+}
+
+// Returns a large-enough enriched response so the "too short" guard (0.5x) passes.
+function mockStreamChatReturns(text: string) {
+ mockStreamChat.mockImplementation(async (_cfg, _msgs, callbacks) => {
+ callbacks.onToken(text)
+ callbacks.onDone()
+ })
+}
+
+beforeEach(() => {
+ mockStreamChat.mockReset()
+ mockReadFile.mockReset()
+ mockWriteFile.mockReset()
+ useWikiStore.getState().setOutputLanguage("auto")
+})
+
+describe("enrichWithWikilinks — language directive is built at call time", () => {
+ // This is the regression for LANGUAGE_RULE being a module-load constant.
+ // Setting the output language AFTER the module is already imported must
+ // affect the next call's prompt.
+ it("uses the language configured at call time, not at module load", async () => {
+ useWikiStore.getState().setOutputLanguage("Chinese")
+ mockReadFile.mockResolvedValue("some page content that is long enough to write back to disk")
+ mockStreamChatReturns("some [[enriched]] page content that is long enough to write back to disk")
+
+ await enrichWithWikilinks("/project", "/project/wiki/note.md", fakeLlmConfig())
+
+ const systemMsg = mockStreamChat.mock.calls[0][1][0]
+ expect(systemMsg.role).toBe("system")
+ expect(systemMsg.content).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("picks up a language change between two successive calls", async () => {
+ mockReadFile.mockResolvedValue("content that is definitely long enough for the length guard")
+ mockStreamChatReturns("content that is definitely long enough for the length guard [[link]]")
+
+ useWikiStore.getState().setOutputLanguage("Japanese")
+ await enrichWithWikilinks("/p", "/p/wiki/a.md", fakeLlmConfig())
+
+ useWikiStore.getState().setOutputLanguage("Korean")
+ await enrichWithWikilinks("/p", "/p/wiki/b.md", fakeLlmConfig())
+
+ const first = mockStreamChat.mock.calls[0][1][0].content
+ const second = mockStreamChat.mock.calls[1][1][0].content
+ expect(first).toContain("MANDATORY OUTPUT LANGUAGE: Japanese")
+ expect(second).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ })
+
+ it("auto mode falls back to detecting from the page content", async () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ mockReadFile.mockResolvedValue("这是一篇关于注意力机制的长中文页面,内容足够长所以能通过守卫")
+ mockStreamChatReturns("这是一篇关于[[注意力机制]]的长中文页面,内容足够长所以能通过守卫")
+
+ await enrichWithWikilinks("/p", "/p/wiki/attention.md", fakeLlmConfig())
+
+ const content = mockStreamChat.mock.calls[0][1][0].content
+ expect(content).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("explicit setting beats source content detection", async () => {
+ useWikiStore.getState().setOutputLanguage("English")
+ mockReadFile.mockResolvedValue("这段中文页面内容非常长,足够通过守卫,里面讲的是注意力机制")
+ mockStreamChatReturns("This is english replacement content that is long enough to pass the guard [[link]]")
+
+ await enrichWithWikilinks("/p", "/p/wiki/x.md", fakeLlmConfig())
+
+ const content = mockStreamChat.mock.calls[0][1][0].content
+ expect(content).toContain("MANDATORY OUTPUT LANGUAGE: English")
+ expect(content).not.toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+})
+
+describe("enrichWithWikilinks — short-response guard", () => {
+ it("does NOT overwrite when LLM returns <50% of original length", async () => {
+ const longContent = "x".repeat(1000)
+ mockReadFile.mockResolvedValue(longContent)
+ mockStreamChatReturns("too short")
+
+ await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
+ expect(mockWriteFile).not.toHaveBeenCalled()
+ })
+
+ it("writes back when enriched response is long enough", async () => {
+ mockReadFile.mockResolvedValue("hello world, this is long enough content for the guard to pass")
+ mockStreamChatReturns("hello [[world]], this is long enough content for the guard to pass")
+
+ await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
+ expect(mockWriteFile).toHaveBeenCalledOnce()
+ })
+
+ it("returns early when content or index is missing", async () => {
+ mockReadFile.mockResolvedValueOnce("").mockResolvedValueOnce("index has things")
+ await enrichWithWikilinks("/p", "/p/f.md", fakeLlmConfig())
+ expect(mockStreamChat).not.toHaveBeenCalled()
+ })
+})
diff --git a/src/lib/ingest.prompt.test.ts b/src/lib/ingest.prompt.test.ts
new file mode 100644
index 00000000..fcf99718
--- /dev/null
+++ b/src/lib/ingest.prompt.test.ts
@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { buildAnalysisPrompt, buildGenerationPrompt } from "./ingest"
+import { useWikiStore } from "@/stores/wiki-store"
+
+beforeEach(() => {
+ useWikiStore.getState().setOutputLanguage("auto")
+})
+
+describe("buildAnalysisPrompt language directive", () => {
+ it("injects the user's explicit language setting", () => {
+ useWikiStore.getState().setOutputLanguage("Chinese")
+ const prompt = buildAnalysisPrompt("purpose", "index", "english source content")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("uses user setting even when source is in a different language", () => {
+ useWikiStore.getState().setOutputLanguage("Japanese")
+ const prompt = buildAnalysisPrompt("", "", "这段内容是中文")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Japanese")
+ expect(prompt).not.toContain("OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("auto mode falls back to detecting source content language", () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ const prompt = buildAnalysisPrompt("", "", "これは日本語の文章です")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Japanese")
+ })
+
+ it("auto mode with empty source defaults to English", () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ const prompt = buildAnalysisPrompt("", "", "")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: English")
+ })
+
+ it("contains structural analysis sections", () => {
+ const prompt = buildAnalysisPrompt("", "", "")
+ expect(prompt).toContain("## Key Entities")
+ expect(prompt).toContain("## Key Concepts")
+ expect(prompt).toContain("## Main Arguments & Findings")
+ expect(prompt).toContain("## Recommendations")
+ })
+})
+
+describe("buildGenerationPrompt language directive", () => {
+ it("injects the user's explicit language setting", () => {
+ useWikiStore.getState().setOutputLanguage("Chinese")
+ const prompt = buildGenerationPrompt("schema", "purpose", "index", "source.pdf")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("honors Vietnamese setting", () => {
+ useWikiStore.getState().setOutputLanguage("Vietnamese")
+ const prompt = buildGenerationPrompt("", "", "", "file.pdf")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Vietnamese")
+ })
+
+ it("auto mode detects from source content", () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ const prompt = buildGenerationPrompt("", "", "", "file.pdf", undefined, "这是中文源文档内容")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("includes the source filename in output instructions", () => {
+ const prompt = buildGenerationPrompt("", "", "", "my-paper.pdf")
+ expect(prompt).toContain("my-paper.pdf")
+ })
+
+ it("respects user setting regardless of source content language", () => {
+ useWikiStore.getState().setOutputLanguage("English")
+ const prompt = buildGenerationPrompt("", "", "", "x.pdf", undefined, "私は日本語の文章を書きます")
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: English")
+ expect(prompt).not.toContain("OUTPUT LANGUAGE: Japanese")
+ })
+})
+
+describe("analysis + generation prompt consistency", () => {
+ // Both stages MUST declare the same target language — otherwise the wiki
+ // files generated in stage 2 may disagree with the analysis from stage 1.
+ it("both stages declare the same language for a given setting", () => {
+ useWikiStore.getState().setOutputLanguage("Korean")
+ const analysis = buildAnalysisPrompt("", "", "")
+ const generation = buildGenerationPrompt("", "", "", "f.pdf")
+ expect(analysis).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ expect(generation).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ })
+
+ it("both stages in auto mode agree on detected language from source", () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ const korean = "이것은 한국어 문장입니다"
+ const analysis = buildAnalysisPrompt("", "", korean)
+ const generation = buildGenerationPrompt("", "", "", "f.pdf", undefined, korean)
+ expect(analysis).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ expect(generation).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ })
+})
diff --git a/src/lib/ingest.ts b/src/lib/ingest.ts
index 416a2556..8a35256e 100644
--- a/src/lib/ingest.ts
+++ b/src/lib/ingest.ts
@@ -319,7 +319,7 @@ function parseReviewBlocks(
* Step 1 prompt: AI reads the source and produces a structured analysis.
* This is the "discussion" step — the AI reasons about the source before writing wiki pages.
*/
-function buildAnalysisPrompt(purpose: string, index: string, sourceContent: string = ""): string {
+export function buildAnalysisPrompt(purpose: string, index: string, sourceContent: string = ""): string {
return [
"You are an expert research analyst. Read the source document and produce a structured analysis.",
"",
@@ -369,7 +369,7 @@ function buildAnalysisPrompt(purpose: string, index: string, sourceContent: stri
/**
* Step 2 prompt: AI takes its own analysis and generates wiki files + review items.
*/
-function buildGenerationPrompt(schema: string, purpose: string, index: string, sourceFileName: string, overview?: string, sourceContent: string = ""): string {
+export function buildGenerationPrompt(schema: string, purpose: string, index: string, sourceFileName: string, overview?: string, sourceContent: string = ""): string {
// Use original filename (without extension) as the source summary page name
const sourceBaseName = sourceFileName.replace(/\.[^.]+$/, "")
diff --git a/src/lib/lint.test.ts b/src/lib/lint.test.ts
new file mode 100644
index 00000000..9812fec9
--- /dev/null
+++ b/src/lib/lint.test.ts
@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach, vi } from "vitest"
+import type { LlmConfig } from "@/stores/wiki-store"
+import type { FileNode } from "@/types/wiki"
+
+// Mock LLM + Tauri FS — the lint runner also touches the activity store
+// (we leave that real so we can assert status transitions).
+vi.mock("./llm-client", () => ({
+ streamChat: vi.fn(),
+}))
+vi.mock("@/commands/fs", () => ({
+ readFile: vi.fn(),
+ writeFile: vi.fn(),
+ listDirectory: vi.fn(),
+}))
+
+import { runSemanticLint } from "./lint"
+import { streamChat } from "./llm-client"
+import { readFile, listDirectory } from "@/commands/fs"
+import { useWikiStore } from "@/stores/wiki-store"
+import { useActivityStore } from "@/stores/activity-store"
+
+const mockStreamChat = vi.mocked(streamChat)
+const mockReadFile = vi.mocked(readFile)
+const mockListDirectory = vi.mocked(listDirectory)
+
+function fakeLlmConfig(): LlmConfig {
+ return {
+ provider: "openai",
+ apiKey: "k",
+ model: "m",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 128000,
+ }
+}
+
+function makeFileNode(name: string, content: string): { node: FileNode; content: string } {
+ return {
+ node: {
+ name,
+ path: `/project/wiki/${name}`,
+ is_dir: false,
+ children: [],
+ } as FileNode,
+ content,
+ }
+}
+
+beforeEach(() => {
+ mockStreamChat.mockReset()
+ mockReadFile.mockReset()
+ mockListDirectory.mockReset()
+ useWikiStore.getState().setOutputLanguage("auto")
+ useActivityStore.setState({ items: [] })
+})
+
+describe("runSemanticLint — language directive", () => {
+ it("uses explicit user setting", async () => {
+ const pages = [
+ makeFileNode("a.md", "Page A content here"),
+ makeFileNode("b.md", "Page B content here"),
+ ]
+ mockListDirectory.mockResolvedValue(pages.map((p) => p.node))
+ mockReadFile.mockImplementation(async (path) => {
+ const match = pages.find((p) => p.node.path === path)
+ return match?.content ?? ""
+ })
+ mockStreamChat.mockImplementation(async (_c, _m, cb) => {
+ cb.onToken("")
+ cb.onDone()
+ })
+
+ useWikiStore.getState().setOutputLanguage("Korean")
+ await runSemanticLint("/project", fakeLlmConfig())
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Korean")
+ })
+
+ it("auto mode detects from the concatenated page summaries", async () => {
+ const cjkContent = "这是一篇关于注意力机制和神经网络的长中文页面"
+ const pages = [
+ makeFileNode("attention.md", cjkContent),
+ makeFileNode("transformer.md", cjkContent),
+ ]
+ mockListDirectory.mockResolvedValue(pages.map((p) => p.node))
+ mockReadFile.mockImplementation(async (path) => {
+ const match = pages.find((p) => p.node.path === path)
+ return match?.content ?? ""
+ })
+ mockStreamChat.mockImplementation(async (_c, _m, cb) => {
+ cb.onToken("")
+ cb.onDone()
+ })
+
+ useWikiStore.getState().setOutputLanguage("auto")
+ await runSemanticLint("/project", fakeLlmConfig())
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("explicit setting wins over source language", async () => {
+ const pages = [makeFileNode("x.md", "これは日本語の内容です")]
+ mockListDirectory.mockResolvedValue(pages.map((p) => p.node))
+ mockReadFile.mockResolvedValue(pages[0].content)
+ mockStreamChat.mockImplementation(async (_c, _m, cb) => {
+ cb.onToken("")
+ cb.onDone()
+ })
+
+ useWikiStore.getState().setOutputLanguage("English")
+ await runSemanticLint("/project", fakeLlmConfig())
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: English")
+ expect(prompt).not.toContain("MANDATORY OUTPUT LANGUAGE: Japanese")
+ })
+})
+
+describe("runSemanticLint — activity & early returns", () => {
+ it("logs a running activity item and marks done", async () => {
+ mockListDirectory.mockResolvedValue([makeFileNode("a.md", "content").node])
+ mockReadFile.mockResolvedValue("content")
+ mockStreamChat.mockImplementation(async (_c, _m, cb) => {
+ cb.onDone()
+ })
+
+ await runSemanticLint("/project", fakeLlmConfig())
+ const items = useActivityStore.getState().items
+ expect(items).toHaveLength(1)
+ // Final state after run completes
+ expect(items[0].type).toBe("lint")
+ expect(["done", "error"]).toContain(items[0].status)
+ })
+
+ it("returns empty and marks done when wiki has no pages", async () => {
+ mockListDirectory.mockResolvedValue([])
+
+ const result = await runSemanticLint("/project", fakeLlmConfig())
+ expect(result).toEqual([])
+ expect(mockStreamChat).not.toHaveBeenCalled()
+
+ const items = useActivityStore.getState().items
+ expect(items[0].detail).toMatch(/no wiki pages/i)
+ })
+
+ it("marks error status when wiki directory read fails", async () => {
+ mockListDirectory.mockRejectedValue(new Error("ENOENT"))
+ await runSemanticLint("/project", fakeLlmConfig())
+ const items = useActivityStore.getState().items
+ expect(items[0].status).toBe("error")
+ })
+})
diff --git a/src/lib/optimize-research-topic.test.ts b/src/lib/optimize-research-topic.test.ts
new file mode 100644
index 00000000..2fbf194d
--- /dev/null
+++ b/src/lib/optimize-research-topic.test.ts
@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, vi } from "vitest"
+import type { LlmConfig } from "@/stores/wiki-store"
+
+// Mock streamChat — we don't want real network, we just want to capture
+// the prompt sent to the LLM and simulate a canned response.
+vi.mock("./llm-client", () => ({
+ streamChat: vi.fn(),
+}))
+
+import { optimizeResearchTopic } from "./optimize-research-topic"
+import { streamChat } from "./llm-client"
+import { useWikiStore } from "@/stores/wiki-store"
+
+const mockStreamChat = vi.mocked(streamChat)
+
+function fakeLlmConfig(): LlmConfig {
+ return {
+ provider: "openai",
+ apiKey: "test-key",
+ model: "gpt-4",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 128000,
+ }
+}
+
+// Helper: simulate streamChat firing a canned response then completing.
+function mockStreamChatReturns(text: string) {
+ mockStreamChat.mockImplementation(async (_config, _msgs, callbacks) => {
+ callbacks.onToken(text)
+ callbacks.onDone()
+ })
+}
+
+beforeEach(() => {
+ mockStreamChat.mockReset()
+ useWikiStore.getState().setOutputLanguage("auto")
+ mockStreamChatReturns("TOPIC: Test topic\nQUERY: q1\nQUERY: q2\nQUERY: q3")
+})
+
+describe("optimizeResearchTopic — language directive", () => {
+ it("includes MANDATORY OUTPUT LANGUAGE header in the prompt", async () => {
+ useWikiStore.getState().setOutputLanguage("Chinese")
+ await optimizeResearchTopic(fakeLlmConfig(), "gap", "desc", "missing-page", "", "")
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("honors auto mode by detecting from gap content", async () => {
+ useWikiStore.getState().setOutputLanguage("auto")
+ await optimizeResearchTopic(
+ fakeLlmConfig(),
+ "注意力机制",
+ "Transformer 里的核心组件",
+ "missing-page",
+ "深度学习 Wiki 总览",
+ "专注于深度学习研究",
+ )
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("user setting beats the detected source language", async () => {
+ useWikiStore.getState().setOutputLanguage("English")
+ await optimizeResearchTopic(
+ fakeLlmConfig(),
+ "注意力机制",
+ "Transformer 里的核心组件",
+ "missing-page",
+ "",
+ "",
+ )
+
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("MANDATORY OUTPUT LANGUAGE: English")
+ expect(prompt).not.toContain("MANDATORY OUTPUT LANGUAGE: Chinese")
+ })
+
+ it("TOPIC output-format hint tells the LLM to use the mandatory language", async () => {
+ await optimizeResearchTopic(fakeLlmConfig(), "x", "y", "suggestion", "", "")
+ const prompt = mockStreamChat.mock.calls[0][1][0].content
+ expect(prompt).toContain("TOPIC:")
+ expect(prompt).toMatch(/TOPIC:.*mandatory output language/i)
+ })
+})
+
+describe("optimizeResearchTopic — response parsing", () => {
+ it("extracts topic and 3 queries from the expected format", async () => {
+ mockStreamChatReturns([
+ "TOPIC: How does attention scale with context length",
+ "QUERY: attention transformer context length scaling",
+ "QUERY: long context attention mechanisms survey",
+ "QUERY: efficient attention sparse",
+ ].join("\n"))
+
+ const result = await optimizeResearchTopic(fakeLlmConfig(), "x", "y", "z", "", "")
+ expect(result.topic).toBe("How does attention scale with context length")
+ expect(result.searchQueries).toEqual([
+ "attention transformer context length scaling",
+ "long context attention mechanisms survey",
+ "efficient attention sparse",
+ ])
+ })
+
+ it("falls back to gapTitle when the LLM response has no TOPIC line", async () => {
+ mockStreamChatReturns("")
+ const result = await optimizeResearchTopic(fakeLlmConfig(), "original gap", "", "z", "", "")
+ expect(result.topic).toBe("original gap")
+ // Fallback: when no queries parsed, uses the topic as the single query
+ expect(result.searchQueries).toEqual(["original gap"])
+ })
+
+ it("caps queries at 3 even if the LLM emits more", async () => {
+ mockStreamChatReturns([
+ "TOPIC: t",
+ "QUERY: 1", "QUERY: 2", "QUERY: 3", "QUERY: 4", "QUERY: 5",
+ ].join("\n"))
+ const result = await optimizeResearchTopic(fakeLlmConfig(), "x", "y", "z", "", "")
+ expect(result.searchQueries).toHaveLength(3)
+ })
+})