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

feat(ingest): enforce schema routing on generated pages

Dongmin, Yud969cd4e6755
diff --git a/src/lib/ingest.prompt.test.ts b/src/lib/ingest.prompt.test.ts
index 83ee323b..36a075f3 100644
--- a/src/lib/ingest.prompt.test.ts
+++ b/src/lib/ingest.prompt.test.ts
@@ -81,6 +81,7 @@ describe("buildGenerationPrompt language directive", () => {
)
expect(prompt).toContain("## Project Schema and Routing (AUTHORITATIVE)")
expect(prompt).toContain("write pages into those schema-defined folders")
+ expect(prompt).toContain("frontmatter type must match the schema directory")
expect(prompt).toContain("otherwise use wiki/entities/")
expect(prompt).not.toContain("Entity pages in wiki/entities/ for key entities")
})
diff --git a/src/lib/ingest.scenarios.test.ts b/src/lib/ingest.scenarios.test.ts
index a93a5e85..cb317cf2 100644
--- a/src/lib/ingest.scenarios.test.ts
+++ b/src/lib/ingest.scenarios.test.ts
@@ -196,6 +196,85 @@ describe("ingest scenarios (fixture-driven)", () => {
},
)
+ it("drops generated pages whose frontmatter type disagrees with schema routing", async () => {
+ ctx = { tmp: await createTempProject("ingest-schema-routing") }
+ const projectPath = ctx.tmp.path
+
+ await writeFileRaw(
+ `${projectPath}/schema.md`,
+ [
+ "# Wiki Schema",
+ "",
+ "## Page Types",
+ "",
+ "| Type | Directory | Purpose |",
+ "| ---- | --------- | ------- |",
+ "| source | wiki/sources/ | Source summaries |",
+ "| concept | wiki/concepts/ | Ideas |",
+ ].join("\n"),
+ )
+ await writeFileRaw(`${projectPath}/purpose.md`, "")
+ await writeFileRaw(`${projectPath}/wiki/index.md`, "# Index\n")
+ await writeFileRaw(`${projectPath}/wiki/overview.md`, "# Overview\n")
+ await writeFileRaw(`${projectPath}/raw/sources/schema-routing.md`, "source\n")
+
+ useWikiStore.setState({
+ project: {
+ name: "t",
+ path: projectPath,
+ createdAt: 0,
+ purposeText: "",
+ fileTree: [],
+ } as unknown as ReturnType<typeof useWikiStore.getState>["project"],
+ })
+ useWikiStore.getState().setLlmConfig({
+ provider: "openai",
+ apiKey: "test-key",
+ model: "gpt-4",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 128000,
+ })
+
+ pendingResponses = [
+ "analysis",
+ [
+ "---FILE: wiki/sources/schema-routing.md---",
+ "---",
+ "type: source",
+ "title: Source: schema-routing.md",
+ "sources: [schema-routing.md]",
+ "tags: []",
+ "related: []",
+ "---",
+ "",
+ "# Source: schema-routing.md",
+ "---END FILE---",
+ "",
+ "---FILE: wiki/concepts/wrong-place.md---",
+ "---",
+ "type: source",
+ "title: Wrong Place",
+ "sources: [schema-routing.md]",
+ "tags: []",
+ "related: []",
+ "---",
+ "",
+ "# Wrong Place",
+ "---END FILE---",
+ ].join("\n"),
+ ]
+
+ const written = await autoIngest(
+ projectPath,
+ `${projectPath}/raw/sources/schema-routing.md`,
+ useWikiStore.getState().llmConfig,
+ )
+
+ expect(written).not.toContain("wiki/concepts/wrong-place.md")
+ expect(await fileExists(`${projectPath}/wiki/concepts/wrong-place.md`)).toBe(false)
+ })
+
it("keeps source summaries distinct for same basenames in different source folders", async () => {
ctx = { tmp: await createTempProject("ingest-duplicate-source-basenames") }
const projectPath = ctx.tmp.path
diff --git a/src/lib/ingest.ts b/src/lib/ingest.ts
index da4b2a99..cfe91189 100644
--- a/src/lib/ingest.ts
+++ b/src/lib/ingest.ts
@@ -201,6 +201,10 @@ function resolveCaptionConfig(
import { buildLanguageDirective } from "@/lib/output-language"
import { detectLanguage } from "@/lib/detect-language"
import { sameScriptFamily } from "@/lib/language-metadata"
+import {
+ loadProjectWikiSchemaRouting,
+ validateWikiPageRouting,
+} from "@/lib/wiki-schema"
// Legacy export kept for backward compatibility with existing diagnostic
// tests. The live pipeline goes through parseFileBlocks() below, which
@@ -1191,6 +1195,7 @@ async function writeFileBlocks(
// be written, so the next re-ingest goes through the full pipeline
// instead of replaying the partial result forever.
const hardFailures: string[] = []
+ const projectSchemaRouting = await loadProjectWikiSchemaRouting(projectPath)
const targetLang = useWikiStore.getState().outputLanguage
@@ -1213,6 +1218,24 @@ async function writeFileBlocks(
content = canonicalizeSourcesField(content, sourceFileName)
}
+ if (
+ projectSchemaRouting &&
+ !isLogPath(relativePath) &&
+ !isListingPath(relativePath)
+ ) {
+ const routingIssue = validateWikiPageRouting(
+ relativePath,
+ content,
+ projectSchemaRouting,
+ )
+ if (routingIssue) {
+ const msg = `Dropped "${relativePath}" — ${routingIssue.message}`
+ console.warn(`[ingest] ${msg}`)
+ warnings.push(msg)
+ continue
+ }
+ }
+
// Language guard: reject individual FILE blocks whose body contradicts
// the user-set target language. Skip:
// - log.md (structural, short)
@@ -1457,6 +1480,7 @@ export function buildGenerationPrompt(
"Use this schema as the primary routing rule for page types and directories.",
"If it defines custom folders or distinctions (for example people, technologies, organizations, methods, or cases), write pages into those schema-defined folders instead of forcing them into wiki/entities/ or wiki/concepts/.",
"Use wiki/entities/ and wiki/concepts/ only when the schema does not provide a more specific destination.",
+ "Every generated page's frontmatter type must match the schema directory used in its FILE path.",
].join("\n")
: "",
"",
diff --git a/src/lib/wiki-schema.test.ts b/src/lib/wiki-schema.test.ts
new file mode 100644
index 00000000..b5fe412c
--- /dev/null
+++ b/src/lib/wiki-schema.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest"
+import {
+ parseWikiSchemaRouting,
+ validateWikiPageRouting,
+} from "./wiki-schema"
+
+const SCHEMA = `# Wiki Schema
+
+## Page Types
+
+| Type | Directory | Purpose |
+| ---- | --------- | ------- |
+| source | wiki/sources/ | Source summaries |
+| concept | wiki/concepts/ | Ideas |
+| method | wiki/methods/ | Methods |
+| overview | wiki/ | Top-level overview |
+`
+
+describe("parseWikiSchemaRouting", () => {
+ it("extracts type directories from the Page Types table", () => {
+ const routing = parseWikiSchemaRouting(SCHEMA)
+
+ expect(routing.typeDirs).toEqual({
+ source: "wiki/sources",
+ concept: "wiki/concepts",
+ method: "wiki/methods",
+ overview: "wiki",
+ })
+ })
+})
+
+describe("validateWikiPageRouting", () => {
+ const routing = parseWikiSchemaRouting(SCHEMA)
+
+ it("reports a mismatch between frontmatter type and schema directory", () => {
+ const issue = validateWikiPageRouting(
+ "wiki/concepts/flash-attention.md",
+ [
+ "---",
+ "type: source",
+ "title: Flash Attention",
+ "---",
+ "",
+ "# Flash Attention",
+ ].join("\n"),
+ routing,
+ )
+
+ expect(issue?.message).toContain('type "source" must be under "wiki/sources/"')
+ })
+
+ it("allows custom schema types routed by the table", () => {
+ expect(
+ validateWikiPageRouting(
+ "wiki/methods/retrieval.md",
+ [
+ "---",
+ "type: method",
+ "title: Retrieval",
+ "---",
+ "",
+ "# Retrieval",
+ ].join("\n"),
+ routing,
+ ),
+ ).toBeNull()
+ })
+
+ it("does not enforce pages without a parseable type", () => {
+ expect(validateWikiPageRouting("wiki/concepts/no-type.md", "# No Type", routing)).toBeNull()
+ })
+})
diff --git a/src/lib/wiki-schema.ts b/src/lib/wiki-schema.ts
new file mode 100644
index 00000000..73053540
--- /dev/null
+++ b/src/lib/wiki-schema.ts
@@ -0,0 +1,98 @@
+import { readFile } from "@/commands/fs"
+import { parseFrontmatter } from "@/lib/frontmatter"
+
+export interface WikiSchemaRouting {
+ typeDirs: Record<string, string>
+}
+
+export interface WikiSchemaRoutingIssue {
+ message: string
+}
+
+export async function loadProjectWikiSchemaRouting(
+ projectPath: string,
+): Promise<WikiSchemaRouting | null> {
+ let raw = ""
+ try {
+ raw = await readFile(`${projectPath.replace(/\/+$/, "")}/schema.md`)
+ } catch {
+ return null
+ }
+ if (!raw.trim()) return null
+
+ const routing = parseWikiSchemaRouting(raw)
+ return Object.keys(routing.typeDirs).length > 0 ? routing : null
+}
+
+export function parseWikiSchemaRouting(markdown: string): WikiSchemaRouting {
+ const typeDirs: Record<string, string> = {}
+ for (const line of markdown.split("\n")) {
+ if (!line.trim().startsWith("|")) continue
+ const cells = line
+ .split("|")
+ .slice(1, -1)
+ .map((cell) => cell.trim())
+ if (cells.length < 2) continue
+
+ const [type, dir] = cells
+ if (!/^[a-z][a-z0-9_-]*$/i.test(type)) continue
+ if (dir !== "wiki" && !dir.startsWith("wiki/")) continue
+
+ typeDirs[type] = stripTrailingSlash(dir)
+ }
+
+ return { typeDirs }
+}
+
+export function validateWikiPageRouting(
+ relativePath: string,
+ content: string,
+ routing: WikiSchemaRouting,
+): WikiSchemaRoutingIssue | null {
+ const parsed = parseFrontmatter(content)
+ const type = parsed.frontmatter?.type
+ if (typeof type !== "string" || !type.trim()) return null
+
+ const normalizedPath = normalizeRelativePath(relativePath)
+ const actualDir = dirname(normalizedPath)
+ const expectedDir = routing.typeDirs[type]
+ if (expectedDir && actualDir !== expectedDir) {
+ return {
+ message: `Page type "${type}" must be under "${expectedDir}/". Current directory: "${actualDir}".`,
+ }
+ }
+
+ const typeFromPath = inferTypeFromSchemaPath(normalizedPath, routing)
+ if (typeFromPath && typeFromPath !== type) {
+ return {
+ message: `Pages under "${actualDir}/" must use type "${typeFromPath}", but found "${type}".`,
+ }
+ }
+
+ return null
+}
+
+function inferTypeFromSchemaPath(
+ relativePath: string,
+ routing: WikiSchemaRouting,
+): string | null {
+ const actualDir = dirname(relativePath)
+ for (const [type, dir] of Object.entries(routing.typeDirs)) {
+ if (actualDir === dir) return type
+ }
+ return null
+}
+
+function normalizeRelativePath(relativePath: string): string {
+ return relativePath.replace(/\\/g, "/").replace(/^\/+/, "")
+}
+
+function dirname(relativePath: string): string {
+ const normalized = normalizeRelativePath(relativePath)
+ const index = normalized.lastIndexOf("/")
+ return index >= 0 ? normalized.slice(0, index) : "."
+}
+
+function stripTrailingSlash(value: string): string {
+ return value.replace(/\/+$/, "")
+}