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-driven fixture framework for sweep behavior

nash_su5db97cfe003f
diff --git a/src/lib/sweep-reviews.scenarios.test.ts b/src/lib/sweep-reviews.scenarios.test.ts
new file mode 100644
index 00000000..151c708a
--- /dev/null
+++ b/src/lib/sweep-reviews.scenarios.test.ts
@@ -0,0 +1,210 @@
+/**
+ * Scenario-driven sweep tests.
+ *
+ * Each scenario (defined in src/test-helpers/scenarios/sweep-scenarios.ts):
+ * 1. Materializes a tests/fixtures/scenarios/<name>/ folder with a real
+ * initial-wiki, reviews.json, llm-response.txt, expected.json.
+ * 2. Copies initial-wiki into a tmp project dir.
+ * 3. Injects the reviews into useReviewStore.
+ * 4. If an llm-response.txt exists, mocks streamChat to emit it; otherwise
+ * disables the LLM stage entirely (apiKey="").
+ * 5. Runs sweepResolvedReviews.
+ * 6. Asserts resolvedIds / pendingIds / per-ID resolvedActions.
+ *
+ * The materialized fixtures are gitignored — the TS definitions are the
+ * only source tracked in version control. This lets the author eyeball the
+ * generated files on disk during debugging.
+ */
+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 { sweepScenarios } from "@/test-helpers/scenarios/sweep-scenarios"
+import type { SweepScenario, ReviewFixture } from "@/test-helpers/scenarios/types"
+
+vi.mock("@/commands/fs", () => realFs)
+
+// The LLM client is mocked per-test so we can inject the scenario's
+// llm-response.txt verbatim (streamed as a single token chunk, then onDone).
+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 { sweepResolvedReviews } from "./sweep-reviews"
+import { useWikiStore } from "@/stores/wiki-store"
+import { useReviewStore } from "@/stores/review-store"
+import { useActivityStore } from "@/stores/activity-store"
+
+const FIXTURES_ROOT = path.join(process.cwd(), "tests", "fixtures", "scenarios")
+
+// ── Setup ────────────────────────────────────────────────────────────────────
+
+beforeAll(async () => {
+ // Fresh start — clear any stale fixtures from previous runs so the disk
+ // tree is always an accurate reflection of the TS source.
+ await fs.rm(FIXTURES_ROOT, { recursive: true, force: true })
+ await fs.mkdir(FIXTURES_ROOT, { recursive: true })
+ // Materialize every scenario upfront.
+ for (const scenario of sweepScenarios) {
+ await materializeScenario(scenario, FIXTURES_ROOT)
+ }
+})
+
+beforeEach(() => {
+ currentLlmResponse = null
+ useReviewStore.setState({ items: [] })
+ useActivityStore.setState({ items: [] })
+})
+
+// ── Scenario runner ─────────────────────────────────────────────────────────
+
+interface RunContext {
+ tmp: { path: string; cleanup: () => Promise<void> }
+}
+
+async function setupScenario(scenario: SweepScenario): Promise<RunContext> {
+ const tmp = await createTempProject(`scenario-${scenario.name.replace(/\//g, "-")}`)
+
+ // Copy initial-wiki into the tmp project
+ const initialWikiDir = path.join(FIXTURES_ROOT, scenario.name, "initial-wiki")
+ await copyDir(initialWikiDir, tmp.path)
+
+ // Inject reviews (fill in the runtime-only fields)
+ const reviewsPath = path.join(FIXTURES_ROOT, scenario.name, "reviews.json")
+ const reviewsRaw = JSON.parse(await fs.readFile(reviewsPath, "utf-8")) as ReviewFixture[]
+ useReviewStore.setState({
+ items: reviewsRaw.map((r) => ({
+ id: r.id,
+ type: r.type,
+ title: r.title,
+ description: r.description ?? "",
+ affectedPages: r.affectedPages,
+ searchQueries: r.searchQueries,
+ sourcePath: r.sourcePath,
+ options: [],
+ resolved: false,
+ createdAt: 0,
+ })),
+ })
+
+ // Project identity for the sweep's project-identity guard
+ useWikiStore.setState({
+ project: {
+ name: "test",
+ path: tmp.path,
+ createdAt: 0,
+ purposeText: "",
+ fileTree: [],
+ } as unknown as ReturnType<typeof useWikiStore.getState>["project"],
+ })
+
+ // LLM config: real key iff the scenario has an LLM response. Otherwise,
+ // empty apiKey makes judgeBatch return an empty Set (no LLM calls).
+ const llmResponsePath = path.join(FIXTURES_ROOT, scenario.name, "llm-response.txt")
+ try {
+ currentLlmResponse = await fs.readFile(llmResponsePath, "utf-8")
+ useWikiStore.getState().setLlmConfig({
+ provider: "openai",
+ apiKey: "test-key",
+ model: "gpt-4",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 128000,
+ })
+ } catch {
+ // No llm-response.txt — disable LLM stage
+ currentLlmResponse = null
+ useWikiStore.getState().setLlmConfig({
+ provider: "openai",
+ apiKey: "",
+ model: "",
+ ollamaUrl: "",
+ customEndpoint: "",
+ maxContextSize: 0,
+ })
+ }
+
+ return { tmp }
+}
+
+function assertWithDump(
+ scenario: SweepScenario,
+ actualResolved: string[],
+ actualPending: string[],
+ actualActions: Record<string, string>,
+) {
+ const expected = scenario.expected
+ const storeItems = useReviewStore.getState().items
+
+ try {
+ expect(actualResolved.sort()).toEqual(expected.resolvedIds.slice().sort())
+ expect(actualPending.sort()).toEqual(expected.pendingIds.slice().sort())
+ if (expected.resolvedActions) {
+ for (const [id, action] of Object.entries(expected.resolvedActions)) {
+ expect(actualActions[id]).toBe(action)
+ }
+ }
+ } catch (err) {
+ // eslint-disable-next-line no-console
+ console.error(
+ `\n[scenario: ${scenario.name}] FAILED — actual review store state:\n` +
+ JSON.stringify(
+ storeItems.map((i) => ({
+ id: i.id,
+ type: i.type,
+ title: i.title,
+ resolved: i.resolved,
+ resolvedAction: i.resolvedAction,
+ })),
+ null,
+ 2,
+ ),
+ )
+ throw err
+ }
+}
+
+// ── Test cases ──────────────────────────────────────────────────────────────
+
+describe("sweep scenarios (fixture-driven)", () => {
+ // Keep context at the describe scope so afterEach can clean up even if
+ // the test itself throws.
+ let ctx: RunContext | undefined
+
+ afterEach(async () => {
+ if (ctx) {
+ await ctx.tmp.cleanup()
+ ctx = undefined
+ }
+ })
+
+ it.each(sweepScenarios.map((s) => [s.name, s]))(
+ "%s",
+ async (_name, scenario) => {
+ ctx = await setupScenario(scenario)
+
+ await sweepResolvedReviews(ctx.tmp.path)
+
+ const state = useReviewStore.getState().items
+ const actualResolved = state.filter((i) => i.resolved).map((i) => i.id)
+ const actualPending = state.filter((i) => !i.resolved).map((i) => i.id)
+ const actualActions = Object.fromEntries(
+ state
+ .filter((i) => i.resolved && i.resolvedAction)
+ .map((i) => [i.id, i.resolvedAction!]),
+ )
+
+ assertWithDump(scenario, actualResolved, actualPending, actualActions)
+ },
+ )
+})
diff --git a/src/test-helpers/scenarios/materialize.ts b/src/test-helpers/scenarios/materialize.ts
new file mode 100644
index 00000000..48faa78e
--- /dev/null
+++ b/src/test-helpers/scenarios/materialize.ts
@@ -0,0 +1,74 @@
+/**
+ * Materializes a scenario's TS definition onto disk so the runner can
+ * exercise the real FS code path and so humans can inspect/debug the
+ * generated fixture files directly. Output dir is gitignored.
+ */
+import fs from "node:fs/promises"
+import path from "node:path"
+import type { SweepScenario } from "./types"
+
+export async function materializeScenario(
+ scenario: SweepScenario,
+ rootDir: string,
+): Promise<{ scenarioPath: string }> {
+ const scenarioPath = path.join(rootDir, scenario.name)
+
+ // Wipe any previous materialization so stale files can't influence the test
+ await fs.rm(scenarioPath, { recursive: true, force: true })
+ await fs.mkdir(scenarioPath, { recursive: true })
+
+ // initial-wiki/ — the project state before sweep runs
+ const wikiDir = path.join(scenarioPath, "initial-wiki")
+ for (const [relPath, content] of Object.entries(scenario.initialWiki)) {
+ const full = path.join(wikiDir, relPath)
+ await fs.mkdir(path.dirname(full), { recursive: true })
+ 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",
+ )
+
+ // llm-response.txt — raw text the mocked streamChat will emit (if any)
+ if (scenario.llmResponse !== undefined) {
+ await fs.writeFile(
+ path.join(scenarioPath, "llm-response.txt"),
+ scenario.llmResponse,
+ "utf-8",
+ )
+ }
+
+ // expected.json — what sweep should produce
+ await fs.writeFile(
+ path.join(scenarioPath, "expected.json"),
+ JSON.stringify(scenario.expected, null, 2),
+ "utf-8",
+ )
+
+ // description.md — human-friendly summary so `find .` results are readable
+ await fs.writeFile(
+ path.join(scenarioPath, "description.md"),
+ `# ${scenario.name}\n\n${scenario.description}\n`,
+ "utf-8",
+ )
+
+ return { scenarioPath }
+}
+
+/** Recursively copy a directory. Used to clone initial-wiki into a tmp project. */
+export async function copyDir(src: string, dst: string): Promise<void> {
+ await fs.mkdir(dst, { recursive: true })
+ const entries = await fs.readdir(src, { withFileTypes: true })
+ for (const entry of entries) {
+ const srcPath = path.join(src, entry.name)
+ const dstPath = path.join(dst, entry.name)
+ if (entry.isDirectory()) {
+ await copyDir(srcPath, dstPath)
+ } else {
+ await fs.copyFile(srcPath, dstPath)
+ }
+ }
+}
diff --git a/src/test-helpers/scenarios/sweep-scenarios.ts b/src/test-helpers/scenarios/sweep-scenarios.ts
new file mode 100644
index 00000000..45fef159
--- /dev/null
+++ b/src/test-helpers/scenarios/sweep-scenarios.ts
@@ -0,0 +1,388 @@
+/**
+ * Authoritative definitions of sweep-behavior scenarios.
+ * Edit here to change a scenario — the runner materializes these to disk.
+ */
+import type { SweepScenario } from "./types"
+
+const SHARED_PURPOSE = `# Purpose
+
+This wiki tracks deep-learning research papers and the core concepts
+they introduce or rely on. Pages aim to be short, encyclopedic, and
+linked via [[wikilinks]] to neighboring concepts.
+`
+
+const SHARED_INDEX = `# Index
+
+## Concepts
+- [[attention]]
+- [[transformer]]
+
+## Papers
+`
+
+// ── Helpers for readable content ─────────────────────────────────────────────
+
+function page(title: string, body: string, extras: Record<string, string> = {}): string {
+ const fm = Object.entries({ title, ...extras })
+ .map(([k, v]) => `${k}: ${v}`)
+ .join("\n")
+ return `---\n${fm}\n---\n\n# ${title}\n\n${body}\n`
+}
+
+// ── Scenarios ────────────────────────────────────────────────────────────────
+
+export const sweepScenarios: SweepScenario[] = [
+ // 1. missing-page/filename-match
+ {
+ name: "missing-page/filename-match",
+ description:
+ "Review says the wiki is missing an 'attention' page. A page named " +
+ "attention.md has since been added. Rule stage matches by filename.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": SHARED_INDEX,
+ "wiki/attention.md": page(
+ "Attention",
+ "Attention assigns per-token weights within a sequence and lets " +
+ "[[transformer]] models capture long-range dependencies.",
+ ),
+ },
+ reviews: [
+ {
+ id: "r-missing-attention",
+ type: "missing-page",
+ title: "Missing page: attention",
+ description:
+ "Transformer page references attention but no dedicated page exists.",
+ affectedPages: ["wiki/transformer.md"],
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-missing-attention"],
+ pendingIds: [],
+ resolvedActions: { "r-missing-attention": "auto-resolved" },
+ },
+ },
+
+ // 2. missing-page/title-match
+ {
+ name: "missing-page/title-match",
+ description:
+ "Review asks about 'Attention Mechanism'. The filename is 'attn.md' " +
+ "but the frontmatter title matches — byTitle lookup should resolve it.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": SHARED_INDEX,
+ "wiki/attn.md": page(
+ "Attention Mechanism",
+ "The attention mechanism computes a weighted sum of value vectors.",
+ ),
+ },
+ reviews: [
+ {
+ id: "r-missing-attn-mech",
+ type: "missing-page",
+ title: "Missing page: Attention Mechanism",
+ description: "No dedicated page for the attention mechanism concept.",
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-missing-attn-mech"],
+ pendingIds: [],
+ },
+ },
+
+ // 3. missing-page/chinese-prefix-variant
+ {
+ name: "missing-page/chinese-prefix-variant",
+ description:
+ "Review title uses the Chinese '缺失页面:' prefix variant. The wiki " +
+ "page is named in Chinese too. Prefix-normalization should make them " +
+ "match the same dedupe/match key as an English 'Missing page:' variant.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": "# 索引\n\n- [[注意力机制]]\n",
+ "wiki/注意力机制.md": page(
+ "注意力机制",
+ "注意力机制是 [[transformer]] 架构的核心组件之一,用于加权聚合序列信息。",
+ ),
+ },
+ reviews: [
+ {
+ id: "r-missing-zh",
+ type: "missing-page",
+ title: "缺失页面: 注意力机制",
+ description: "关于注意力机制的页面尚未建立。",
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-missing-zh"],
+ pendingIds: [],
+ },
+ },
+
+ // 4. missing-page/not-resolved
+ {
+ name: "missing-page/not-resolved",
+ description:
+ "Review asks about a page that genuinely does not exist in the wiki " +
+ "yet. With no LLM configured, the sweep must leave it pending.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": SHARED_INDEX,
+ "wiki/attention.md": page("Attention", "..."),
+ },
+ reviews: [
+ {
+ id: "r-never-added",
+ type: "missing-page",
+ title: "Missing page: retrieval-augmented-generation",
+ description: "No page exists yet for RAG.",
+ },
+ ],
+ expected: {
+ resolvedIds: [],
+ pendingIds: ["r-never-added"],
+ },
+ },
+
+ // 5. missing-page/case-insensitive
+ {
+ name: "missing-page/case-insensitive",
+ description:
+ "Review title uses ALL-CAPS. Filename is lowercase. Match must be " +
+ "case-insensitive.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention.md": page("Attention", "..."),
+ },
+ reviews: [
+ {
+ id: "r-uppercase",
+ type: "missing-page",
+ title: "MISSING PAGE: ATTENTION",
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-uppercase"],
+ pendingIds: [],
+ },
+ },
+
+ // 6. missing-page/kebab-vs-space
+ {
+ name: "missing-page/kebab-vs-space",
+ description:
+ "Review says 'Missing page: attention mechanism' (space). Wiki has " +
+ "'attention-mechanism.md' (kebab-case). pageExists applies a " +
+ "space→hyphen fallback so the match still works.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention-mechanism.md": page("Attention Mechanism", "..."),
+ },
+ reviews: [
+ {
+ id: "r-kebab",
+ type: "missing-page",
+ title: "Missing page: attention mechanism",
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-kebab"],
+ pendingIds: [],
+ },
+ },
+
+ // 7. duplicate/one-page-deleted
+ {
+ name: "duplicate/one-page-deleted",
+ description:
+ "A duplicate review flagged that attention.md and attention-v2.md " +
+ "covered the same topic. The user has since deleted attention-v2.md, " +
+ "so the duplicate situation no longer exists — rule stage must resolve.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention.md": page("Attention", "..."),
+ // attention-v2.md intentionally absent (user deleted it after the review)
+ },
+ reviews: [
+ {
+ id: "r-dup-resolved",
+ type: "duplicate",
+ title: "Duplicate page: Attention concept split across two files",
+ description:
+ "attention.md and attention-v2.md cover the same material and " +
+ "should be merged or one deleted.",
+ affectedPages: ["wiki/attention.md", "wiki/attention-v2.md"],
+ },
+ ],
+ expected: {
+ resolvedIds: ["r-dup-resolved"],
+ pendingIds: [],
+ },
+ },
+
+ // 8. duplicate/both-present
+ {
+ name: "duplicate/both-present",
+ description:
+ "Both duplicated pages still exist — user hasn't resolved it yet. " +
+ "Rule stage must NOT auto-resolve; needs human judgment.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention.md": page("Attention", "..."),
+ "wiki/attention-v2.md": page("Attention (v2)", "..."),
+ },
+ reviews: [
+ {
+ id: "r-dup-pending",
+ type: "duplicate",
+ title: "Duplicate page: Attention concept split",
+ affectedPages: ["wiki/attention.md", "wiki/attention-v2.md"],
+ },
+ ],
+ expected: {
+ resolvedIds: [],
+ pendingIds: ["r-dup-pending"],
+ },
+ },
+
+ // 9. contradiction/never-auto-resolves
+ {
+ name: "contradiction/never-auto-resolves",
+ description:
+ "Contradiction items require human judgment and must NEVER be " +
+ "auto-resolved by the rule stage, even if the pages they reference " +
+ "still exist. Would only be resolved by a conservative-LLM scenario.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention.md": page("Attention", "Uses softmax over scores."),
+ "wiki/transformer.md": page("Transformer", "Uses linear attention."),
+ },
+ reviews: [
+ {
+ id: "r-contra",
+ type: "contradiction",
+ title: "Contradiction: attention mechanism details",
+ description:
+ "attention.md says softmax, transformer.md says linear. One must " +
+ "be wrong or underspecified.",
+ affectedPages: ["wiki/attention.md", "wiki/transformer.md"],
+ },
+ ],
+ expected: {
+ resolvedIds: [],
+ pendingIds: ["r-contra"],
+ },
+ },
+
+ // 10. suggestion/stays-pending-by-default
+ {
+ name: "suggestion/stays-pending-by-default",
+ description:
+ "Suggestion items are conservative by design — the rule stage " +
+ "doesn't touch them. Without LLM configured, they stay pending.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/attention.md": page("Attention", "..."),
+ },
+ reviews: [
+ {
+ id: "r-sugg",
+ type: "suggestion",
+ title: "Consider adding a 'Transformer variants' survey page",
+ description: "There are now several pages that reference variants.",
+ },
+ ],
+ expected: {
+ resolvedIds: [],
+ pendingIds: ["r-sugg"],
+ },
+ },
+
+ // 11. llm-judged/semantic-match
+ {
+ name: "llm-judged/semantic-match",
+ description:
+ "Rule stage can't match 'Missing: Context Window' to any existing " +
+ "page by filename or title. The LLM, given the wiki state, returns " +
+ "the review ID as resolved (attention.md covers context windows). " +
+ "Uses a fenced JSON response to exercise extractJsonObject.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": SHARED_INDEX,
+ "wiki/attention.md": page(
+ "Attention",
+ "Attention defines an effective context window — the span of tokens " +
+ "that can influence each output. Modern models extend this to " +
+ "hundreds of thousands of tokens. This covers what users usually " +
+ "mean by 'context window'.",
+ ),
+ },
+ reviews: [
+ {
+ id: "r-context-window",
+ type: "missing-page",
+ title: "Missing page: Context Window",
+ description: "Transformer page references context windows.",
+ },
+ ],
+ llmResponse: '```json\n{"resolved": ["r-context-window"]}\n```',
+ expected: {
+ resolvedIds: ["r-context-window"],
+ pendingIds: [],
+ resolvedActions: { "r-context-window": "llm-judged" },
+ },
+ },
+
+ // 12. mixed-batch/partial-resolution
+ {
+ name: "mixed-batch/partial-resolution",
+ description:
+ "A mix of reviews: one resolvable by rules (filename match), one " +
+ "contradiction that must stay pending, one missing-page the LLM " +
+ "confirms as resolved, one suggestion the LLM conservatively keeps.",
+ initialWiki: {
+ "purpose.md": SHARED_PURPOSE,
+ "wiki/index.md": SHARED_INDEX,
+ "wiki/attention.md": page(
+ "Attention",
+ "Attention mechanism details. Covers context windows too.",
+ ),
+ "wiki/transformer.md": page("Transformer", "..."),
+ },
+ reviews: [
+ {
+ id: "r-mix-rule",
+ type: "missing-page",
+ title: "Missing page: attention",
+ },
+ {
+ id: "r-mix-contra",
+ type: "contradiction",
+ title: "Contradiction: attention details differ",
+ affectedPages: ["wiki/attention.md", "wiki/transformer.md"],
+ },
+ {
+ id: "r-mix-llm",
+ type: "missing-page",
+ title: "Missing page: Context Window",
+ },
+ {
+ id: "r-mix-sugg",
+ type: "suggestion",
+ title: "Consider adding a glossary page",
+ },
+ ],
+ llmResponse: '```json\n{"resolved": ["r-mix-llm"]}\n```',
+ expected: {
+ // r-mix-rule resolved by rules; r-mix-llm resolved by LLM; others stay.
+ resolvedIds: ["r-mix-rule", "r-mix-llm"],
+ pendingIds: ["r-mix-contra", "r-mix-sugg"],
+ resolvedActions: {
+ "r-mix-rule": "auto-resolved",
+ "r-mix-llm": "llm-judged",
+ },
+ },
+ },
+]
diff --git a/src/test-helpers/scenarios/types.ts b/src/test-helpers/scenarios/types.ts
new file mode 100644
index 00000000..eeac0bd4
--- /dev/null
+++ b/src/test-helpers/scenarios/types.ts
@@ -0,0 +1,81 @@
+/**
+ * Scenario-driven sweep tests.
+ *
+ * Each scenario is the AUTHORITATIVE description of a sweep behavior —
+ * it contains the initial wiki state (realistic markdown + frontmatter),
+ * the review items to inject, optional raw LLM response text, and the
+ * expected outcome after sweepResolvedReviews runs.
+ *
+ * The materialize helper writes the scenario to disk under
+ * tests/fixtures/scenarios/<name>/ so authors can inspect actual files
+ * when debugging. Those files are gitignored (tests/ is ignored) — the
+ * TS source here is the only thing tracked.
+ */
+
+export type ReviewType =
+ | "contradiction"
+ | "duplicate"
+ | "missing-page"
+ | "confirm"
+ | "suggestion"
+
+export interface ReviewFixture {
+ id: string
+ type: ReviewType
+ title: string
+ description?: string
+ affectedPages?: string[]
+ searchQueries?: string[]
+ sourcePath?: string
+}
+
+export interface SweepScenarioExpected {
+ /** Review IDs that should be resolved after sweep. */
+ resolvedIds: string[]
+ /** Review IDs that should remain pending. */
+ pendingIds: string[]
+ /** Optional per-ID resolved action assertion (auto-resolved / llm-judged). */
+ resolvedActions?: Record<string, string>
+}
+
+export interface SweepScenario {
+ /**
+ * Path-like name used as the scenario's folder under
+ * tests/fixtures/scenarios/. Slashes create nested folders.
+ * Example: "missing-page/filename-match"
+ */
+ name: string
+
+ /** One-line human-readable description. Shown in test output. */
+ description: string
+
+ /**
+ * Virtual file tree for the initial wiki state. Keys are project-root
+ * relative paths, values are full file contents (usually markdown with
+ * YAML frontmatter). Materialized before the test runs.
+ *
+ * Example:
+ * {
+ * "purpose.md": "...",
+ * "wiki/index.md": "...",
+ * "wiki/attention.md": "---\ntitle: Attention\n---\n..."
+ * }
+ */
+ initialWiki: Record<string, string>
+
+ /**
+ * Review items to seed into useReviewStore before sweep runs. They
+ * don't need `resolved` / `createdAt` / `options` — those are filled in.
+ */
+ reviews: ReviewFixture[]
+
+ /**
+ * Optional raw LLM response text — exactly what `streamChat` would
+ * emit. Can include markdown fences, prose wrappers, etc. If absent,
+ * the LLM stage is disabled (apiKey="") so only the rule stage runs.
+ */
+ llmResponse?: string
+
+ /** What the sweep should have done when it finishes. */
+ expected: SweepScenarioExpected
+}