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
/**
* Unit coverage for the caption pipeline. Mocks `captionImage` and
* the fs commands so we can pin the cache + rewrite logic without
* touching either the LLM or the filesystem.
*/
import { describe, it, expect, vi, beforeEach } from "vitest"
const { mockCaption, mockReadBase64, mockReadFile, mockWriteFile, mockFileExists, mockCreateDir } =
vi.hoisted(() => ({
mockCaption: vi.fn(),
mockReadBase64: vi.fn(),
mockReadFile: vi.fn(),
mockWriteFile: vi.fn(),
mockFileExists: vi.fn(),
mockCreateDir: vi.fn(),
}))
vi.mock("@/lib/vision-caption", () => ({
captionImage: mockCaption,
}))
vi.mock("@/commands/fs", () => ({
readFile: (p: string) => mockReadFile(p),
writeFile: (p: string, c: string) => mockWriteFile(p, c),
fileExists: (p: string) => mockFileExists(p),
createDirectory: (p: string) => mockCreateDir(p),
readFileAsBase64: (p: string) => mockReadBase64(p),
}))
import {
captionMarkdownImages,
loadCaptionCache,
stripMarkdownImageReferences,
__test,
} from "./image-caption-pipeline"
import type { LlmConfig } from "@/stores/wiki-store"
const cfg: LlmConfig = {
provider: "custom",
apiKey: "",
model: "vl-test",
ollamaUrl: "",
customEndpoint: "http://example/v1",
apiMode: "chat_completions",
maxContextSize: 8192,
}
beforeEach(() => {
mockCaption.mockReset()
mockReadBase64.mockReset()
mockReadFile.mockReset()
mockWriteFile.mockReset()
mockFileExists.mockReset()
mockCreateDir.mockReset()
// Default: no cache file present, no images to read.
mockFileExists.mockResolvedValue(false)
mockCreateDir.mockResolvedValue(undefined)
mockWriteFile.mockResolvedValue(undefined)
})
describe("findImageReferences (helper)", () => {
it("captures markdown image syntax with position info", () => {
const refs = __test.findImageReferences("text\n\n more")
expect(refs).toEqual([
{ full: "", alt: "", url: "a.png", destination: "a.png", index: 5, length: 10 },
{ full: "", alt: "label", url: "b.jpg", destination: "b.jpg", index: 16, length: 15 },
])
})
it("ignores links and HTML img", () => {
const refs = __test.findImageReferences("[link](url) <img src=foo.png /> ")
expect(refs).toHaveLength(1)
expect(refs[0].url).toBe("z.png")
})
it("captures local image destinations containing spaces", () => {
const refs = __test.findImageReferences(
" ",
)
expect(refs.map((ref) => ref.url)).toEqual([
"assets/figure one.png",
"assets/figure two.jpg",
])
})
it("handles parentheses, optional titles, encoded spaces, and empty destinations", () => {
const refs = __test.findImageReferences([
".png)",
".png> \"Screenshot\")",
"",
"",
].join("\n"))
expect(refs.map((ref) => ref.url)).toEqual([
"media/Shot (1).png",
"media/Shot (2).png",
"media/figure three.png",
])
})
it("does not mistake a trailing parenthesized filename segment for a title", () => {
const refs = __test.findImageReferences(")")
expect(refs[0]?.url).toBe("media/Shot (1)")
})
it("stops malformed image candidates at the current line", () => {
const markdown = ""
const refs = __test.findImageReferences(markdown)
expect(refs).toHaveLength(1)
expect(refs[0].url).toBe("real image.png")
expect(refs[0].index).toBe(markdown.indexOf(")
})
it("does not join embeds or reference images to a later Markdown link", () => {
const samples = [
"See ![[a.png]] and [docs](https://x.test)",
"![logo][1] then [link](https://x.test)",
"x![citation needed] see [here](https://x.test)",
]
for (const sample of samples) {
expect(__test.findImageReferences(sample)).toEqual([])
expect(stripMarkdownImageReferences(sample)).toBe(sample)
}
})
it("normalizes encoded spaces and escaped parentheses for filesystem access", () => {
const refs = __test.findImageReferences(
" two.png)",
)
expect(refs.map((ref) => ref.url)).toEqual([
"media/figure one.png",
"media/figure)two.png",
])
})
})
describe("stripMarkdownImageReferences", () => {
it("strips titled and adjacent image references without touching malformed input", () => {
expect(stripMarkdownImageReferences("ab"))
.toBe("a b")
expect(stripMarkdownImageReferences(")
.toBe("
})
})
describe("captionMarkdownImages", () => {
it("returns input unchanged when there are no image references", async () => {
const out = await captionMarkdownImages("/proj", "no images here", cfg)
expect(out.enrichedMarkdown).toBe("no images here")
expect(out.freshCaptions).toBe(0)
expect(out.cachedCaptions).toBe(0)
expect(mockCaption).not.toHaveBeenCalled()
})
it("captions a fresh image, rewrites alt text, persists cache", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("a red square")
const md = "Before\n\n\n\nAfter"
const out = await captionMarkdownImages("/proj", md, cfg)
expect(out.freshCaptions).toBe(1)
expect(out.cachedCaptions).toBe(0)
expect(out.enrichedMarkdown).toBe(
"Before\n\n\n\nAfter",
)
expect(mockCaption).toHaveBeenCalledTimes(1)
expect(mockCaption).toHaveBeenCalledWith(
"AAAA",
"image/png",
cfg,
undefined,
// Pipeline always passes a context options object, even when
// both sides are empty (image at start/end of doc).
expect.objectContaining({ contextBefore: expect.any(String), contextAfter: expect.any(String) }),
)
// Cache file written exactly once at the end of the batch.
expect(mockWriteFile).toHaveBeenCalledTimes(1)
const [cachePath, contents] = mockWriteFile.mock.calls[0] as [string, string]
expect(cachePath).toBe("/proj/.llm-wiki/image-caption-cache.json")
const written = JSON.parse(contents)
const entries = Object.values(written) as Array<Record<string, unknown>>
expect(entries).toHaveLength(1)
expect(entries[0]).toMatchObject({
caption: "a red square",
mimeType: "image/png",
model: "vl-test",
})
})
it("captions and preserves an image destination containing spaces", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("a process diagram")
const out = await captionMarkdownImages(
"/proj",
"",
cfg,
)
expect(mockReadBase64).toHaveBeenCalledWith("/proj/wiki/assets/process flow.png")
expect(out.enrichedMarkdown).toBe(
"",
)
})
it("deduplicates equivalent plain and angle-bracket destinations", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("same image")
const out = await captionMarkdownImages(
"/proj",
"\n",
cfg,
)
expect(mockCaption).toHaveBeenCalledTimes(1)
expect(out.enrichedMarkdown).toBe(
"\n",
)
})
it("forwards outputLanguage to captionImage", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("ein rotes Quadrat")
await captionMarkdownImages("/proj", "", cfg, {
outputLanguage: "German",
})
expect(mockCaption).toHaveBeenCalledWith(
"AAAA",
"image/png",
cfg,
undefined,
expect.objectContaining({ outputLanguage: "German" }),
)
})
it("does not reuse a caption cached for a different output language", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("ein rotes Quadrat")
const knownHash = await __test.sha256OfBase64("AAAA")
mockFileExists.mockResolvedValue(true)
mockReadFile.mockResolvedValue(JSON.stringify({
[knownHash]: {
caption: "a red square",
mimeType: "image/png",
model: "vl-old",
capturedAt: "2026-01-01T00:00:00Z",
},
}))
const out = await captionMarkdownImages("/proj", "", cfg, {
outputLanguage: "German",
})
expect(out.freshCaptions).toBe(1)
expect(out.cachedCaptions).toBe(0)
expect(mockCaption).toHaveBeenCalledTimes(1)
const written = JSON.parse(mockWriteFile.mock.calls[0][1] as string)
expect(written[__test.captionCacheKey(knownHash, "German")]).toMatchObject({
caption: "ein rotes Quadrat",
imageHash: knownHash,
outputLanguage: "German",
})
})
it("reuses a caption cached for the same output language", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
const knownHash = await __test.sha256OfBase64("AAAA")
const key = __test.captionCacheKey(knownHash, "German")
mockFileExists.mockResolvedValue(true)
mockReadFile.mockResolvedValue(JSON.stringify({
[key]: {
caption: "ein rotes Quadrat",
mimeType: "image/png",
model: "vl-old",
capturedAt: "2026-01-01T00:00:00Z",
imageHash: knownHash,
outputLanguage: "German",
},
}))
const out = await captionMarkdownImages("/proj", "", cfg, {
outputLanguage: "german",
})
expect(out.cachedCaptions).toBe(1)
expect(out.freshCaptions).toBe(0)
expect(mockCaption).not.toHaveBeenCalled()
expect(out.enrichedMarkdown).toContain("![ein rotes Quadrat]")
})
it("dedupes by SHA-256: two refs to the same bytes → one LLM call, both rewritten", async () => {
// Both URLs return the same base64 bytes — same hash → single
// caption call, both alt-texts populated.
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("the logo")
const md = " and "
const out = await captionMarkdownImages("/proj", md, cfg)
// Two reads, ONE caption call, both refs rewritten.
expect(mockReadBase64).toHaveBeenCalledTimes(2)
expect(mockCaption).toHaveBeenCalledTimes(1)
expect(out.freshCaptions).toBe(1)
expect(out.enrichedMarkdown).toBe(
" and ",
)
})
it("uses cached caption when SHA-256 hash matches", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
// Pre-populate the cache file. Hash of base64-decoded "AAAA"
// (bytes 0,0,0): we compute it via the same helper to keep
// the test deterministic and decoupled from a literal hash.
const knownHash = await __test.sha256OfBase64("AAAA")
const cacheJson = {
[knownHash]: {
caption: "previously captioned",
mimeType: "image/png",
model: "vl-old",
capturedAt: "2026-01-01T00:00:00Z",
},
}
mockFileExists.mockResolvedValue(true)
mockReadFile.mockResolvedValue(JSON.stringify(cacheJson))
const md = ""
const out = await captionMarkdownImages("/proj", md, cfg)
expect(out.cachedCaptions).toBe(1)
expect(out.freshCaptions).toBe(0)
expect(mockCaption).not.toHaveBeenCalled()
expect(out.enrichedMarkdown).toBe("")
// Cache wasn't grown → no write.
expect(mockWriteFile).not.toHaveBeenCalled()
})
it("sanitizes captions: strips newlines and replaces ] with )", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("line1\nline2 with ] bracket")
const md = ""
const out = await captionMarkdownImages("/proj", md, cfg)
expect(out.enrichedMarkdown).toBe("")
})
it("continues batch when one caption call fails, reporting failed count", async () => {
mockReadBase64.mockImplementation(async (p: string) => {
if (p === "/abs/a.png") return { base64: "AAAA", mimeType: "image/png" }
return { base64: "BBBB", mimeType: "image/png" }
})
mockCaption.mockImplementation(async (b64: string) => {
if (b64 === "AAAA") return "first"
throw new Error("HTTP 500")
})
const md = " "
const out = await captionMarkdownImages("/proj", md, cfg)
expect(out.freshCaptions).toBe(1)
expect(out.failed).toBe(1)
// Successful one rewritten, failing one keeps original empty alt.
expect(out.enrichedMarkdown).toBe(" ")
})
it("respects shouldCaption filter: skips URLs that don't match", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("c")
const md = " "
const out = await captionMarkdownImages("/proj", md, cfg, {
shouldCaption: (url) => url.startsWith("/wanted/"),
})
expect(mockReadBase64).toHaveBeenCalledTimes(1)
expect(mockReadBase64).toHaveBeenCalledWith("/wanted/img.png")
expect(out.enrichedMarkdown).toBe(
" ",
)
})
it("uses urlToAbsPath hook when provided", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("c")
const md = ""
await captionMarkdownImages("/proj", md, cfg, {
urlToAbsPath: (url) => `/custom/anchor/${url}`,
})
expect(mockReadBase64).toHaveBeenCalledWith("/custom/anchor/media/foo/img-1.png")
})
it("skips Codex CLI captioning once before reading image bytes", async () => {
const out = await captionMarkdownImages("/proj", "\n", {
...cfg,
provider: "codex-cli",
})
expect(out.enrichedMarkdown).toBe("\n")
expect(out.failed).toBe(2)
expect(mockReadBase64).not.toHaveBeenCalled()
expect(mockCaption).not.toHaveBeenCalled()
})
it("forwards AbortSignal to captionImage", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("c")
const ctl = new AbortController()
await captionMarkdownImages("/proj", "", cfg, {
signal: ctl.signal,
})
expect(mockCaption).toHaveBeenCalledWith(
"AAAA",
"image/png",
cfg,
ctl.signal,
expect.objectContaining({ contextBefore: expect.any(String), contextAfter: expect.any(String) }),
)
})
it("recovers from corrupt cache JSON (logs and starts fresh)", async () => {
mockFileExists.mockResolvedValue(true)
mockReadFile.mockResolvedValue("{ this is not valid JSON")
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("ok")
const out = await captionMarkdownImages("/proj", "", cfg)
expect(out.enrichedMarkdown).toBe("")
expect(out.freshCaptions).toBe(1)
})
it("respects concurrency limit — three caption calls dispatch in parallel when concurrency=3", async () => {
// Need three distinct valid base64 strings so each image
// hashes to a unique cache key (otherwise dedupe collapses
// to one call). `atob` requires legal base64 — `AQ==` /
// `Ag==` / `Aw==` are bytes 0x01, 0x02, 0x03 respectively.
const b64ByPath: Record<string, string> = {
"/abs/a.png": "AQ==",
"/abs/b.png": "Ag==",
"/abs/c.png": "Aw==",
}
mockReadBase64.mockImplementation(async (p: string) => ({
base64: b64ByPath[p] ?? "AAAA",
mimeType: "image/png",
}))
let inFlight = 0
let peakInFlight = 0
mockCaption.mockImplementation(async (b64: string) => {
inFlight++
peakInFlight = Math.max(peakInFlight, inFlight)
// Yield one microtask boundary so the worker pool spins up
// additional tasks before this one resolves.
await Promise.resolve()
await new Promise((r) => setTimeout(r, 5))
inFlight--
return `cap-${b64}`
})
const md = "  "
const out = await captionMarkdownImages("/proj", md, cfg, { concurrency: 3 })
expect(out.freshCaptions).toBe(3)
// With concurrency=3 and ALL three workers spawned before any
// resolve, the peak should reach 3. We assert >=2 to leave
// some slack for tight scheduler races but still detect
// strictly-sequential regressions (peak would be 1).
expect(peakInFlight).toBeGreaterThanOrEqual(2)
})
it("calls onProgress after each image with running counts", async () => {
const b64ByPath: Record<string, string> = {
"/abs/a.png": "AQ==",
"/abs/b.png": "Ag==",
}
mockReadBase64.mockImplementation(async (p: string) => ({
base64: b64ByPath[p] ?? "AAAA",
mimeType: "image/png",
}))
mockCaption.mockResolvedValue("c")
const progressCalls: Array<{ done: number; total: number }> = []
const md = " "
await captionMarkdownImages("/proj", md, cfg, {
onProgress: (done, total) => progressCalls.push({ done, total }),
})
expect(progressCalls).toEqual([
{ done: 1, total: 2 },
{ done: 2, total: 2 },
])
})
it("passes surrounding text as contextBefore / contextAfter to captionImage", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("c")
// Image is sandwiched between recognizable before / after
// markers so the slice content is easy to assert on.
const before = "Figure 3: Quarterly revenue 2024 — preceding text. ".repeat(2)
const after = " Following commentary about the chart. ".repeat(2)
const md = `${before}${after}`
await captionMarkdownImages("/proj", md, cfg)
const args = mockCaption.mock.calls[0]
const opts = args[4] as { contextBefore: string; contextAfter: string }
expect(opts.contextBefore).toContain("Figure 3: Quarterly revenue 2024")
expect(opts.contextAfter).toContain("Following commentary about the chart")
// The image's own `` must NOT leak into either side
// — slicing is by index/length, not by string match.
expect(opts.contextBefore).not.toContain("")
expect(opts.contextAfter).not.toContain("")
})
it("clamps context windows at document boundaries (no out-of-range read)", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("c")
// Image at the very start: contextBefore must be empty string.
// Image at the very end: contextAfter must be empty string.
const md1 = " trailing text only"
await captionMarkdownImages("/proj", md1, cfg)
let opts = mockCaption.mock.calls[0][4] as { contextBefore: string; contextAfter: string }
expect(opts.contextBefore).toBe("")
expect(opts.contextAfter).toBe(" trailing text only")
mockCaption.mockClear()
const md2 = "leading text only "
await captionMarkdownImages("/proj", md2, cfg)
opts = mockCaption.mock.calls[0][4] as { contextBefore: string; contextAfter: string }
expect(opts.contextBefore).toBe("leading text only ")
expect(opts.contextAfter).toBe("")
})
})
describe("loadCaptionCache", () => {
it("selects the newest caption per image when no language is requested", async () => {
const knownHash = await __test.sha256OfBase64("AAAA")
const germanKey = __test.captionCacheKey(knownHash, "German")
mockFileExists.mockResolvedValue(true)
// Put the legacy entry last to prove selection does not depend on JSON key order.
mockReadFile.mockResolvedValue(JSON.stringify({
[germanKey]: {
caption: "neue Beschreibung",
mimeType: "image/png",
model: "vl-new",
capturedAt: "2026-08-18T00:00:00Z",
imageHash: knownHash,
outputLanguage: "German",
},
[knownHash]: {
caption: "old description",
mimeType: "image/png",
model: "vl-old",
capturedAt: "2026-01-01T00:00:00Z",
},
}))
const captions = await loadCaptionCache("/proj")
expect(captions.get(knownHash)).toBe("neue Beschreibung")
})
})