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: scenario framework for lint + enrich-wikilinks

nash_su6dadf0e414a0
diff --git a/src/lib/enrich-wikilinks.scenarios.test.ts b/src/lib/enrich-wikilinks.scenarios.test.ts
new file mode 100644
index 00000000..7029f49a
--- /dev/null
+++ b/src/lib/enrich-wikilinks.scenarios.test.ts
@@ -0,0 +1,125 @@
+/**
+ * Scenario-driven tests for enrichWithWikilinks.
+ *
+ * Each scenario materializes an initial wiki, runs enrichWithWikilinks on
+ * a specified page with a canned LLM response, then asserts whether the
+ * file on disk was overwritten and (if so) whether it has the expected
+ * content exactly.
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from "vitest"
+import path from "node:path"
+import fs from "node:fs/promises"
+import { realFs, createTempProject, readFileRaw } from "@/test-helpers/fs-temp"
+import { materializeScenario, copyDir } from "@/test-helpers/scenarios/materialize"
+import { enrichScenarios } from "@/test-helpers/scenarios/enrich-scenarios"
+import type { EnrichScenario } from "@/test-helpers/scenarios/types"
+
+vi.mock("@/commands/fs", () => realFs)
+
+let currentLlmResponse = ""
+vi.mock("./llm-client", () => ({
+ streamChat: vi.fn(async (_cfg, _msgs, cb) => {
+ cb.onToken(currentLlmResponse)
+ cb.onDone()
+ }),
+}))
+
+import { enrichWithWikilinks } from "./enrich-wikilinks"
+import { useWikiStore } from "@/stores/wiki-store"
+
+const FIXTURES_ROOT = path.join(process.cwd(), "tests", "fixtures", "scenarios-enrich")
+
+beforeAll(async () => {
+ await fs.rm(FIXTURES_ROOT, { recursive: true, force: true })
+ await fs.mkdir(FIXTURES_ROOT, { recursive: true })
+ for (const s of enrichScenarios) {
+ await materializeScenario(s, FIXTURES_ROOT)
+ }
+})
+
+beforeEach(() => {
+ currentLlmResponse = ""
+})
+
+interface Ctx {
+ tmp: { path: string; cleanup: () => Promise<void> }
+}
+let ctx: Ctx | undefined
+
+async function setup(scenario: EnrichScenario): Promise<Ctx> {
+ const tmp = await createTempProject(
+ `enrich-${scenario.name.replace(/\//g, "-")}`,
+ )
+ const initialWikiDir = path.join(FIXTURES_ROOT, scenario.name, "initial-wiki")
+ await copyDir(initialWikiDir, tmp.path)
+
+ useWikiStore.setState({
+ project: {
+ name: "t",
+ path: tmp.path,
+ 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,
+ })
+
+ currentLlmResponse = await fs.readFile(
+ path.join(FIXTURES_ROOT, scenario.name, "llm-response.txt"),
+ "utf-8",
+ )
+ return { tmp }
+}
+
+afterEach(async () => {
+ if (ctx) {
+ await ctx.tmp.cleanup()
+ ctx = undefined
+ }
+})
+
+describe("enrich-wikilinks scenarios (fixture-driven)", () => {
+ it.each(enrichScenarios.map((s) => [s.name, s]))(
+ "%s",
+ async (_name, scenario) => {
+ ctx = await setup(scenario)
+ const pagePath = path.join(ctx.tmp.path, scenario.pageToEnrich)
+ const originalContent = await readFileRaw(pagePath)
+
+ await enrichWithWikilinks(
+ ctx.tmp.path,
+ pagePath,
+ useWikiStore.getState().llmConfig,
+ )
+
+ const finalContent = await readFileRaw(pagePath)
+
+ try {
+ if (scenario.expected.writeCalled) {
+ expect(finalContent).not.toBe(originalContent)
+ if (scenario.expected.expectedContent !== undefined) {
+ expect(finalContent).toBe(scenario.expected.expectedContent)
+ }
+ } else {
+ expect(finalContent).toBe(originalContent)
+ }
+ } catch (err) {
+ // eslint-disable-next-line no-console
+ console.error(
+ `\n[enrich: ${scenario.name}] FAILED.\n` +
+ `--- ORIGINAL ---\n${originalContent}\n` +
+ `--- FINAL ---\n${finalContent}\n` +
+ `--- LLM RESPONSE ---\n${currentLlmResponse}\n`,
+ )
+ throw err
+ }
+ },
+ )
+})
diff --git a/src/lib/lint.scenarios.test.ts b/src/lib/lint.scenarios.test.ts
new file mode 100644
index 00000000..f430b150
--- /dev/null
+++ b/src/lib/lint.scenarios.test.ts
@@ -0,0 +1,167 @@
+/**
+ * Scenario-driven lint tests.
+ *
+ * Exercises runStructuralLint (always) and runSemanticLint (when the
+ * scenario provides an llm-response.txt) against a materialized wiki dir.
+ */
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from "vitest"
+import path from "node:path"
+import fs from "node:fs/promises"
+import { realFs, createTempProject } from "@/test-helpers/fs-temp"
+import { materializeScenario, copyDir } from "@/test-helpers/scenarios/materialize"
+import { lintScenarios } from "@/test-helpers/scenarios/lint-scenarios"
+import type { LintScenario } from "@/test-helpers/scenarios/types"
+
+vi.mock("@/commands/fs", () => realFs)
+
+let currentLlmResponse: string | null = null
+vi.mock("./llm-client", () => ({
+ streamChat: vi.fn(async (_cfg, _msgs, cb) => {
+ if (currentLlmResponse !== null) cb.onToken(currentLlmResponse)
+ cb.onDone()
+ }),
+}))
+
+import { runStructuralLint, runSemanticLint, type LintResult } from "./lint"
+import { useWikiStore } from "@/stores/wiki-store"
+import { useActivityStore } from "@/stores/activity-store"
+
+const FIXTURES_ROOT = path.join(process.cwd(), "tests", "fixtures", "scenarios-lint")
+
+const shimScenarios = lintScenarios // shorthand
+
+beforeAll(async () => {
+ await fs.rm(FIXTURES_ROOT, { recursive: true, force: true })
+ await fs.mkdir(FIXTURES_ROOT, { recursive: true })
+ for (const s of shimScenarios) {
+ await materializeScenario(s, FIXTURES_ROOT)
+ }
+})
+
+beforeEach(() => {
+ currentLlmResponse = null
+ useActivityStore.setState({ items: [] })
+})
+
+interface Ctx {
+ tmp: { path: string; cleanup: () => Promise<void> }
+}
+let ctx: Ctx | undefined
+
+async function setup(scenario: LintScenario): Promise<Ctx> {
+ const tmp = await createTempProject(
+ `lint-${scenario.name.replace(/\//g, "-")}`,
+ )
+ const initialWikiDir = path.join(FIXTURES_ROOT, scenario.name, "initial-wiki")
+ await copyDir(initialWikiDir, tmp.path)
+
+ useWikiStore.setState({
+ project: {
+ name: "t",
+ path: tmp.path,
+ 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,
+ })
+
+ if (scenario.llmResponse !== undefined) {
+ currentLlmResponse = await fs.readFile(
+ path.join(FIXTURES_ROOT, scenario.name, "llm-response.txt"),
+ "utf-8",
+ )
+ }
+ return { tmp }
+}
+
+afterEach(async () => {
+ if (ctx) {
+ await ctx.tmp.cleanup()
+ ctx = undefined
+ }
+})
+
+// ── Assertions ──────────────────────────────────────────────────────────────
+
+function assertStructural(
+ scenario: LintScenario,
+ actual: LintResult[],
+): void {
+ const expected = scenario.expected.structural
+ try {
+ expect(actual.length).toBe(expected.length)
+ for (const e of expected) {
+ const match = actual.find(
+ (a) =>
+ a.type === e.type &&
+ a.page.includes(e.page) &&
+ (e.linkName === undefined || a.detail.includes(e.linkName)),
+ )
+ expect(match, `no structural finding matching ${JSON.stringify(e)}`).toBeTruthy()
+ }
+ } catch (err) {
+ // eslint-disable-next-line no-console
+ console.error(
+ `\n[lint: ${scenario.name}] structural mismatch. Actual findings:\n` +
+ JSON.stringify(actual, null, 2),
+ )
+ throw err
+ }
+}
+
+function assertSemantic(
+ scenario: LintScenario,
+ actual: LintResult[],
+): void {
+ const expected = scenario.expected.semantic ?? []
+ try {
+ expect(actual.length).toBe(expected.length)
+ for (const e of expected) {
+ const match = actual.find(
+ (a) =>
+ a.type === e.type &&
+ a.severity === (e.severity as "warning" | "info") &&
+ (e.titleContains === undefined || a.detail.includes(e.titleContains) ||
+ a.page.includes(e.titleContains)),
+ )
+ expect(match, `no semantic finding matching ${JSON.stringify(e)}`).toBeTruthy()
+ }
+ } catch (err) {
+ // eslint-disable-next-line no-console
+ console.error(
+ `\n[lint: ${scenario.name}] semantic mismatch. Actual findings:\n` +
+ JSON.stringify(actual, null, 2),
+ )
+ throw err
+ }
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe("lint scenarios (fixture-driven)", () => {
+ it.each(shimScenarios.map((s) => [s.name, s]))(
+ "%s",
+ async (_name, scenario) => {
+ ctx = await setup(scenario)
+
+ const structural = await runStructuralLint(ctx.tmp.path)
+ assertStructural(scenario, structural)
+
+ if (scenario.llmResponse !== undefined) {
+ const semantic = await runSemanticLint(
+ ctx.tmp.path,
+ useWikiStore.getState().llmConfig,
+ )
+ assertSemantic(scenario, semantic)
+ }
+ },
+ )
+})
diff --git a/src/test-helpers/scenarios/enrich-scenarios.ts b/src/test-helpers/scenarios/enrich-scenarios.ts
new file mode 100644
index 00000000..9dff06b0
--- /dev/null
+++ b/src/test-helpers/scenarios/enrich-scenarios.ts
@@ -0,0 +1,142 @@
+import type { EnrichScenario } from "./types"
+
+/**
+ * Reminder: enrichWithWikilinks only writes back to disk if the LLM
+ * response length is at least 50% of the original content length
+ * (guards against LLM errors returning something short and bogus).
+ */
+
+const WIKI_INDEX_WITH_TRANSFORMER = `# Index
+
+## Concepts
+- [[attention]]
+- [[transformer]]
+- [[encoder]]
+`
+
+export const enrichScenarios: EnrichScenario[] = [
+ // 1. adds-wikilinks — LLM wraps recognized terms with [[...]]
+ {
+ name: "adds-wikilinks",
+ description:
+ "A page mentions 'Transformer' without wikilinks. LLM returns the " +
+ "same content with [[Transformer]] added on first mention. " +
+ "writeFile must be called with the enriched content.",
+ initialWiki: {
+ "wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
+ "wiki/survey.md":
+ "# Deep Learning Survey\n\n" +
+ "Modern NLP relies on Transformer architectures for most tasks. " +
+ "The Transformer was introduced in 2017 and has since dominated. " +
+ "Attention is the key mechanism that makes it work.\n",
+ },
+ pageToEnrich: "wiki/survey.md",
+ // Enriched version — same length-ish (LLM guard: >= 50% of original length).
+ llmResponse:
+ "# Deep Learning Survey\n\n" +
+ "Modern NLP relies on [[Transformer]] architectures for most tasks. " +
+ "The Transformer was introduced in 2017 and has since dominated. " +
+ "[[Attention]] is the key mechanism that makes it work.\n",
+ expected: {
+ writeCalled: true,
+ expectedContent:
+ "# Deep Learning Survey\n\n" +
+ "Modern NLP relies on [[Transformer]] architectures for most tasks. " +
+ "The Transformer was introduced in 2017 and has since dominated. " +
+ "[[Attention]] is the key mechanism that makes it work.\n",
+ },
+ },
+
+ // 2. preserves-frontmatter — YAML block must survive enrichment verbatim
+ {
+ name: "preserves-frontmatter",
+ description:
+ "Page has YAML frontmatter with title, tags, sources. LLM response " +
+ "must preserve the frontmatter exactly. writeFile is called and the " +
+ "content starts with the original frontmatter.",
+ initialWiki: {
+ "wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
+ "wiki/attention.md":
+ "---\n" +
+ "title: Attention\n" +
+ "tags: [deep-learning, transformer]\n" +
+ "sources: [paper-2017.pdf]\n" +
+ "---\n\n" +
+ "# Attention\n\n" +
+ "Attention scores are computed by the encoder. The encoder layer " +
+ "uses these scores to weight values. Detailed derivation below.\n",
+ },
+ pageToEnrich: "wiki/attention.md",
+ llmResponse:
+ "---\n" +
+ "title: Attention\n" +
+ "tags: [deep-learning, transformer]\n" +
+ "sources: [paper-2017.pdf]\n" +
+ "---\n\n" +
+ "# Attention\n\n" +
+ "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " +
+ "uses these scores to weight values. Detailed derivation below.\n",
+ expected: {
+ writeCalled: true,
+ expectedContent:
+ "---\n" +
+ "title: Attention\n" +
+ "tags: [deep-learning, transformer]\n" +
+ "sources: [paper-2017.pdf]\n" +
+ "---\n\n" +
+ "# Attention\n\n" +
+ "Attention scores are computed by the [[encoder]]. The [[encoder]] layer " +
+ "uses these scores to weight values. Detailed derivation below.\n",
+ },
+ },
+
+ // 3. short-response-rejected — guards against truncated LLM replies
+ {
+ name: "short-response-rejected",
+ description:
+ "Original content is long (~400 chars) but LLM returns only a brief " +
+ "snippet (<50% original length). The guard rejects the write to avoid " +
+ "data loss. writeFile MUST NOT be called.",
+ initialWiki: {
+ "wiki/index.md": WIKI_INDEX_WITH_TRANSFORMER,
+ "wiki/long-page.md":
+ "# Long Page\n\n" +
+ "This page has substantial content that must not be clobbered by a " +
+ "truncated LLM response. ".repeat(10) +
+ "\n\nFinal line here for good measure.\n",
+ },
+ pageToEnrich: "wiki/long-page.md",
+ // Way shorter than original — must trigger the guard
+ llmResponse: "Short reply with [[attention]].",
+ expected: {
+ writeCalled: false,
+ },
+ },
+
+ // 4. cjk-terms — Chinese content + Chinese wikilinks
+ {
+ name: "cjk-terms",
+ description:
+ "Chinese content with Chinese wiki index entries. LLM adds CJK " +
+ "wikilinks on first mention. UTF-8 round-trip must be clean.",
+ initialWiki: {
+ "wiki/index.md": "# 索引\n\n- [[注意力机制]]\n- [[transformer]]\n",
+ "wiki/intro.md":
+ "# 简介\n\n" +
+ "注意力机制是 transformer 架构的核心组件之一。" +
+ "注意力机制让模型能够关注序列中最相关的部分。\n",
+ },
+ pageToEnrich: "wiki/intro.md",
+ llmResponse:
+ "# 简介\n\n" +
+ "[[注意力机制]]是 [[transformer]] 架构的核心组件之一。" +
+ "注意力机制让模型能够关注序列中最相关的部分。\n",
+ expected: {
+ writeCalled: true,
+ expectedContent:
+ "# 简介\n\n" +
+ "[[注意力机制]]是 [[transformer]] 架构的核心组件之一。" +
+ "注意力机制让模型能够关注序列中最相关的部分。\n",
+ },
+ },
+]
diff --git a/src/test-helpers/scenarios/lint-scenarios.ts b/src/test-helpers/scenarios/lint-scenarios.ts
new file mode 100644
index 00000000..57d84b82
--- /dev/null
+++ b/src/test-helpers/scenarios/lint-scenarios.ts
@@ -0,0 +1,146 @@
+import type { LintScenario } from "./types"
+
+// NOTE: Structural lint only counts inbound wikilinks from OTHER content
+// pages (index.md and log.md are excluded from the slug map). So to avoid
+// an "orphan" finding on a page, at least one non-index content page must
+// [[link]] to it. Scenario wikis here are built with that in mind.
+
+function page(title: string, body: string): string {
+ return `---\ntitle: ${title}\n---\n\n# ${title}\n\n${body}\n`
+}
+
+export const lintScenarios: LintScenario[] = [
+ // 1. clean-wiki — fully interlinked, no findings
+ {
+ name: "structural/clean-wiki",
+ description:
+ "Two content pages cross-link each other. No orphans, no broken " +
+ "links, no no-outlinks. Structural lint returns an empty result.",
+ initialWiki: {
+ "wiki/index.md": "# Index\n\n- [[attention]]\n- [[transformer]]\n",
+ "wiki/attention.md": page(
+ "Attention",
+ "See the [[transformer]] architecture for how this is applied.",
+ ),
+ "wiki/transformer.md": page(
+ "Transformer",
+ "Transformers are built on the [[attention]] mechanism.",
+ ),
+ },
+ expected: {
+ structural: [],
+ },
+ },
+
+ // 2. orphan-page — no inbound wikilinks
+ {
+ name: "structural/orphan-page",
+ description:
+ "orphan.md links out to attention.md but no content page links BACK " +
+ "to orphan.md. Structural lint should flag it as orphan, nothing else.",
+ initialWiki: {
+ "wiki/index.md": "# Index\n\n- [[attention]]\n- [[transformer]]\n",
+ "wiki/attention.md": page("Attention", "Related: [[transformer]]."),
+ "wiki/transformer.md": page("Transformer", "Built on [[attention]]."),
+ "wiki/orphan.md": page(
+ "Orphan",
+ "This page links to [[attention]] but nobody links back here.",
+ ),
+ },
+ expected: {
+ structural: [{ type: "orphan", page: "orphan.md" }],
+ },
+ },
+
+ // 3. broken-link — wikilink to a page that doesn't exist
+ {
+ name: "structural/broken-link",
+ description:
+ "attention.md contains a wikilink to [[nonexistent-page]] which has " +
+ "no corresponding file. Structural lint must flag the broken link " +
+ "and name it in the detail.",
+ initialWiki: {
+ "wiki/index.md": "# Index\n\n- [[attention]]\n- [[transformer]]\n",
+ "wiki/attention.md": page(
+ "Attention",
+ "Related to [[transformer]] and also to [[nonexistent-page]].",
+ ),
+ "wiki/transformer.md": page("Transformer", "Built on [[attention]]."),
+ },
+ expected: {
+ structural: [
+ {
+ type: "broken-link",
+ page: "attention.md",
+ linkName: "nonexistent-page",
+ },
+ ],
+ },
+ },
+
+ // 4. no-outlinks — a page has zero [[wikilinks]]
+ {
+ name: "structural/no-outlinks",
+ description:
+ "leaf.md is linked-to by transformer.md but has no outgoing links " +
+ "of its own. Lint should flag 'no-outlinks' on leaf.md.",
+ initialWiki: {
+ "wiki/index.md": "# Index\n\n- [[attention]]\n- [[transformer]]\n- [[leaf]]\n",
+ "wiki/attention.md": page("Attention", "Related: [[transformer]]."),
+ "wiki/transformer.md": page(
+ "Transformer",
+ "Uses [[attention]] and references [[leaf]] as a concept.",
+ ),
+ "wiki/leaf.md": page(
+ "Leaf",
+ "This page describes a leaf concept and makes no external references.",
+ ),
+ },
+ expected: {
+ // Only the no-outlinks finding — transformer still outlinks, attention
+ // still outlinks, leaf has inbound from transformer.
+ structural: [{ type: "no-outlinks", page: "leaf.md" }],
+ },
+ },
+
+ // 5. semantic-contradiction (LLM-backed)
+ {
+ name: "semantic/contradiction-found",
+ description:
+ "Two cross-linked pages make conflicting claims. Structural lint " +
+ "sees no issues, but the mocked semantic LLM response emits a LINT " +
+ "block that the parser extracts into a contradiction finding.",
+ initialWiki: {
+ "wiki/index.md": "# Index\n\n- [[attention]]\n- [[transformer]]\n",
+ "wiki/attention.md": page(
+ "Attention",
+ "Attention ALWAYS uses the softmax function. See [[transformer]].",
+ ),
+ "wiki/transformer.md": page(
+ "Transformer",
+ "The transformer's [[attention]] layer uses a linear kernel, not softmax.",
+ ),
+ },
+ llmResponse: [
+ "Reviewing the pages I found one contradiction:",
+ "",
+ "---LINT: contradiction | warning | Attention function differs between pages---",
+ "attention.md claims softmax is always used, but transformer.md describes a",
+ "linear attention kernel. One page needs correction.",
+ "PAGES: attention.md, transformer.md",
+ "---END LINT---",
+ ].join("\n"),
+ expected: {
+ structural: [],
+ semantic: [
+ {
+ // Parser collapses all semantic findings to type="semantic";
+ // the original LLM-declared type ("contradiction") lives in detail.
+ type: "semantic",
+ severity: "warning",
+ titleContains: "Attention function differs",
+ },
+ ],
+ },
+ },
+]
diff --git a/src/test-helpers/scenarios/materialize.ts b/src/test-helpers/scenarios/materialize.ts
index 48faa78e..d319a29c 100644
--- a/src/test-helpers/scenarios/materialize.ts
+++ b/src/test-helpers/scenarios/materialize.ts
@@ -5,10 +5,25 @@
*/
import fs from "node:fs/promises"
import path from "node:path"
-import type { SweepScenario } from "./types"
+
+/**
+ * Minimal shape every scenario shares: name, description, initialWiki,
+ * optional llmResponse, expected. Scenario-specific fields (reviews for
+ * sweep, pageToEnrich for enrich, etc.) are picked up opportunistically.
+ */
+type AnyScenario = {
+ name: string
+ description: string
+ initialWiki: Record<string, string>
+ llmResponse?: string
+ expected: unknown
+ // optional per-domain fields
+ reviews?: unknown
+ pageToEnrich?: string
+}
export async function materializeScenario(
- scenario: SweepScenario,
+ scenario: AnyScenario,
rootDir: string,
): Promise<{ scenarioPath: string }> {
const scenarioPath = path.join(rootDir, scenario.name)
@@ -17,7 +32,7 @@ export async function materializeScenario(
await fs.rm(scenarioPath, { recursive: true, force: true })
await fs.mkdir(scenarioPath, { recursive: true })
- // initial-wiki/ — the project state before sweep runs
+ // initial-wiki/ — the project state before the tested operation runs
const wikiDir = path.join(scenarioPath, "initial-wiki")
for (const [relPath, content] of Object.entries(scenario.initialWiki)) {
const full = path.join(wikiDir, relPath)
@@ -25,12 +40,23 @@ export async function materializeScenario(
await fs.writeFile(full, content, "utf-8")
}
- // reviews.json — what to inject into the review store
- await fs.writeFile(
- path.join(scenarioPath, "reviews.json"),
- JSON.stringify(scenario.reviews, null, 2),
- "utf-8",
- )
+ // reviews.json — only for sweep scenarios
+ if (scenario.reviews !== undefined) {
+ await fs.writeFile(
+ path.join(scenarioPath, "reviews.json"),
+ JSON.stringify(scenario.reviews, null, 2),
+ "utf-8",
+ )
+ }
+
+ // page-to-enrich.txt — only for enrich scenarios; stored as a pointer file
+ if (scenario.pageToEnrich !== undefined) {
+ await fs.writeFile(
+ path.join(scenarioPath, "page-to-enrich.txt"),
+ scenario.pageToEnrich,
+ "utf-8",
+ )
+ }
// llm-response.txt — raw text the mocked streamChat will emit (if any)
if (scenario.llmResponse !== undefined) {
@@ -41,7 +67,7 @@ export async function materializeScenario(
)
}
- // expected.json — what sweep should produce
+ // expected.json — what the operation should produce
await fs.writeFile(
path.join(scenarioPath, "expected.json"),
JSON.stringify(scenario.expected, null, 2),
diff --git a/src/test-helpers/scenarios/types.ts b/src/test-helpers/scenarios/types.ts
index eeac0bd4..95a4c771 100644
--- a/src/test-helpers/scenarios/types.ts
+++ b/src/test-helpers/scenarios/types.ts
@@ -38,6 +38,63 @@ export interface SweepScenarioExpected {
resolvedActions?: Record<string, string>
}
+/**
+ * Lint scenarios exercise both runStructuralLint (deterministic — orphans,
+ * broken links, no-outlinks) and optionally runSemanticLint (LLM-backed).
+ */
+export interface LintScenario {
+ name: string
+ description: string
+ /** Virtual project tree. Must include a wiki/ subfolder. */
+ initialWiki: Record<string, string>
+ /**
+ * Optional raw LLM response for semantic lint. When absent, the semantic
+ * stage is skipped — only structural assertions apply.
+ */
+ llmResponse?: string
+ expected: {
+ /** Expected structural lint findings. Order-independent. */
+ structural: Array<{
+ type: "orphan" | "broken-link" | "no-outlinks"
+ /** Page path relative to wiki/ (e.g. "attention.md") */
+ page: string
+ /** For broken-link, the substring that should appear in the detail */
+ linkName?: string
+ }>
+ /** Expected semantic lint findings (when llmResponse provided) */
+ semantic?: Array<{
+ type: string
+ severity: string
+ titleContains?: string
+ }>
+ }
+}
+
+/**
+ * Enrich-wikilinks scenarios assert the behavior of enrichWithWikilinks:
+ * given an existing page + wiki index + canned LLM response, does the
+ * function write the expected new content (or correctly refuse to write)?
+ */
+export interface EnrichScenario {
+ name: string
+ description: string
+ /** Virtual project tree. Must include wiki/index.md. */
+ initialWiki: Record<string, string>
+ /** Project-relative path of the page to enrich (e.g. "wiki/transformer.md"). */
+ pageToEnrich: string
+ /** Raw streamChat response text (including fences, prose wrappers, etc). */
+ llmResponse: string
+ expected: {
+ /** True if the page on disk should have been overwritten. */
+ writeCalled: boolean
+ /**
+ * Exact expected content of pageToEnrich after the call — only checked
+ * when writeCalled is true.
+ */
+ expectedContent?: string
+ }
+}
+
export interface SweepScenario {
/**
* Path-like name used as the scenario's folder under