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

fix: support spaced image caption paths

nash_sudbe720ec46db
diff --git a/src/lib/image-caption-pipeline.test.ts b/src/lib/image-caption-pipeline.test.ts
index 3e297d6a..e0320c77 100644
--- a/src/lib/image-caption-pipeline.test.ts
+++ b/src/lib/image-caption-pipeline.test.ts
@@ -27,7 +27,12 @@ vi.mock("@/commands/fs", () => ({
readFileAsBase64: (p: string) => mockReadBase64(p),
}))
-import { captionMarkdownImages, loadCaptionCache, __test } from "./image-caption-pipeline"
+import {
+ captionMarkdownImages,
+ loadCaptionCache,
+ stripMarkdownImageReferences,
+ __test,
+} from "./image-caption-pipeline"
import type { LlmConfig } from "@/stores/wiki-store"
const cfg: LlmConfig = {
@@ -57,8 +62,8 @@ describe("findImageReferences (helper)", () => {
it("captures markdown image syntax with position info", () => {
const refs = __test.findImageReferences("text\n![](a.png)\n![label](b.jpg) more")
expect(refs).toEqual([
- { full: "![](a.png)", alt: "", url: "a.png", index: 5, length: 10 },
- { full: "![label](b.jpg)", alt: "label", url: "b.jpg", index: 16, length: 15 },
+ { full: "![](a.png)", alt: "", url: "a.png", destination: "a.png", index: 5, length: 10 },
+ { full: "![label](b.jpg)", alt: "label", url: "b.jpg", destination: "b.jpg", index: 16, length: 15 },
])
})
@@ -67,6 +72,76 @@ describe("findImageReferences (helper)", () => {
expect(refs).toHaveLength(1)
expect(refs[0].url).toBe("z.png")
})
+
+ it("captures local image destinations containing spaces", () => {
+ const refs = __test.findImageReferences(
+ "![](assets/figure one.png) ![two](<assets/figure two.jpg>)",
+ )
+
+ 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([
+ "![](media/Shot (1).png)",
+ "![](<media/Shot (2).png> \"Screenshot\")",
+ "![](media/figure%20three.png 'Figure')",
+ "![]( )",
+ ].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("![](media/Shot (1))")
+ expect(refs[0]?.url).toBe("media/Shot (1)")
+ })
+
+ it("stops malformed image candidates at the current line", () => {
+ const markdown = "![not an image\ntext\n![](real image.png)"
+ 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(
+ "![](media/figure%20one.png) ![](media/figure\\)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("a![](<x y.png> \"t\")![](z.png)b"))
+ .toBe("a b")
+ expect(stripMarkdownImageReferences("![not](image"))
+ .toBe("![not](image")
+ })
})
describe("captionMarkdownImages", () => {
@@ -116,6 +191,38 @@ describe("captionMarkdownImages", () => {
})
})
+ 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",
+ "![](<assets/process flow.png>)",
+ cfg,
+ )
+
+ expect(mockReadBase64).toHaveBeenCalledWith("/proj/wiki/assets/process flow.png")
+ expect(out.enrichedMarkdown).toBe(
+ "![a process diagram](<assets/process flow.png>)",
+ )
+ })
+
+ 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",
+ "![](assets/figure one.png)\n![](<assets/figure one.png>)",
+ cfg,
+ )
+
+ expect(mockCaption).toHaveBeenCalledTimes(1)
+ expect(out.enrichedMarkdown).toBe(
+ "![same image](assets/figure one.png)\n![same image](<assets/figure one.png>)",
+ )
+ })
+
it("forwards outputLanguage to captionImage", async () => {
mockReadBase64.mockResolvedValue({ base64: "AAAA", mimeType: "image/png" })
mockCaption.mockResolvedValue("ein rotes Quadrat")
diff --git a/src/lib/image-caption-pipeline.ts b/src/lib/image-caption-pipeline.ts
index 8f63b3cd..e9ac54aa 100644
--- a/src/lib/image-caption-pipeline.ts
+++ b/src/lib/image-caption-pipeline.ts
@@ -161,19 +161,41 @@ async function writeCache(projectPath: string, cache: CaptionCache): Promise<voi
* captured but ignored when deciding whether to caption (we
* re-caption even non-empty alt because user-typed alt text
* usually says "Figure 3" — useless to retrieval).
- * - HTML `<img src="...">`: NOT captured by this regex; we
+ * - HTML `<img src="...">`: NOT captured by this parser; we
* don't generate those, and re-captioning hand-typed HTML
* would surprise the user.
* - Reference-style images (`![alt][ref]` + `[ref]: url`): NOT
* handled — we don't generate them either. Add support if
* it matters.
*/
-const MD_IMAGE_RE = /(!\[)([^\]]*)(\]\()([^)\s]+)(\))/g
+const TRAILING_IMAGE_TITLE_RE = /\s+(?:"[^"]*"|'[^']*')\s*$/
+
+function normalizeImageDestination(destination: string): string {
+ let value = destination.trim()
+ if (value.startsWith("<")) {
+ const close = value.indexOf(">")
+ if (close < 0) return ""
+ value = value.slice(1, close).trim()
+ } else {
+ value = value.replace(TRAILING_IMAGE_TITLE_RE, "").trim()
+ }
+ if (!value) return ""
+ value = value.replace(/\\([\\() ])/g, "$1")
+ try {
+ // decodeURI resolves normal Markdown URL encoding such as %20 while
+ // deliberately preserving encoded path separators such as %2F.
+ return decodeURI(value)
+ } catch {
+ return value
+ }
+}
interface ImageRef {
full: string // the entire `![alt](url)` substring
alt: string
url: string
+ /** Destination exactly as written between parentheses, including a title. */
+ destination: string
/** 0-based offset of the match in the source markdown — used to
* slice the surrounding text for context-aware captioning. */
index: number
@@ -207,23 +229,103 @@ const CONTEXT_CHARS = 150
function findImageReferences(markdown: string): ImageRef[] {
const out: ImageRef[] = []
- // Use exec() in a loop instead of matchAll() so we capture
- // `m.index` (the position in the source) — needed for the
- // context slicer below.
- const re = new RegExp(MD_IMAGE_RE.source, MD_IMAGE_RE.flags)
- let m: RegExpExecArray | null
- while ((m = re.exec(markdown)) !== null) {
+ let cursor = 0
+ while (cursor < markdown.length) {
+ const start = markdown.indexOf("![", cursor)
+ if (start < 0) break
+ let altEnd = start + 2
+ let escapedAlt = false
+ for (; altEnd < markdown.length; altEnd++) {
+ const char = markdown[altEnd]
+ if (char === "\r" || char === "\n") break
+ if (escapedAlt) {
+ escapedAlt = false
+ continue
+ }
+ if (char === "\\") {
+ escapedAlt = true
+ continue
+ }
+ if (char === "]") break
+ }
+ if (!markdown.startsWith("](", altEnd)) {
+ cursor = Math.max(start + 2, altEnd + 1)
+ continue
+ }
+ const destinationStart = altEnd + 2
+ let end = destinationStart
+ if (markdown[destinationStart] === "<") {
+ let angleEnd = destinationStart + 1
+ while (
+ angleEnd < markdown.length &&
+ markdown[angleEnd] !== ">" &&
+ markdown[angleEnd] !== "\r" &&
+ markdown[angleEnd] !== "\n"
+ ) angleEnd++
+ if (markdown[angleEnd] !== ">") {
+ cursor = Math.max(destinationStart, angleEnd + 1)
+ continue
+ }
+ end = angleEnd + 1
+ while (end < markdown.length && markdown[end] !== ")" && !/[\r\n]/.test(markdown[end])) end++
+ } else {
+ let depth = 0
+ let escaped = false
+ for (; end < markdown.length; end++) {
+ const char = markdown[end]
+ if (char === "\r" || char === "\n") break
+ if (escaped) {
+ escaped = false
+ continue
+ }
+ if (char === "\\") {
+ escaped = true
+ continue
+ }
+ if (char === "(") depth++
+ else if (char === ")") {
+ if (depth === 0) break
+ depth--
+ }
+ }
+ }
+ if (markdown[end] !== ")") {
+ cursor = Math.max(destinationStart, end + 1)
+ continue
+ }
+ const destination = markdown.slice(destinationStart, end)
+ const url = normalizeImageDestination(destination)
+ if (!url) {
+ cursor = end + 1
+ continue
+ }
+ const full = markdown.slice(start, end + 1)
out.push({
- full: m[0],
- alt: m[2],
- url: m[4],
- index: m.index,
- length: m[0].length,
+ full,
+ alt: markdown.slice(start + 2, altEnd),
+ url,
+ destination,
+ index: start,
+ length: full.length,
})
+ cursor = end + 1
}
return out
}
+export function stripMarkdownImageReferences(markdown: string): string {
+ const refs = findImageReferences(markdown)
+ if (refs.length === 0) return markdown
+ const pieces: string[] = []
+ let cursor = 0
+ for (const ref of refs) {
+ pieces.push(markdown.slice(cursor, ref.index), " ")
+ cursor = ref.index + ref.length
+ }
+ pieces.push(markdown.slice(cursor))
+ return pieces.join("")
+}
+
/**
* Slice the chars BEFORE and AFTER an image match in the source
* markdown. Bounds-safe (window clamps to document edges) and
@@ -494,23 +596,28 @@ export async function captionMarkdownImages(
}
}
- // Rewrite the markdown — replace every captured image ref's alt
- // text with its caption. We use a callback-style replace rather
- // than running findImageReferences twice so we can sanitize the
- // alt text inline (no `]` characters or newlines, both of which
- // would break the markdown).
- const enrichedMarkdown = markdown.replace(
- MD_IMAGE_RE,
- (whole, openBang, _alt, closeBracket, url, closeParen) => {
- const caption = captionByUrl.get(url)
- if (!caption) return whole
- const safe = caption
- .replace(/[\r\n]+/g, " ") // collapse newlines
- .replace(/]/g, ")") // ] would close the alt early
- .trim()
- return `${openBang}${safe}${closeBracket}${url}${closeParen}`
- },
- )
+ // Rewrite all refs in one pass so large image-heavy documents do not copy
+ // the full Markdown string once per image.
+ const pieces: string[] = []
+ let rewriteCursor = 0
+ for (const ref of refs) {
+ const caption = captionByUrl.get(ref.url)
+ pieces.push(markdown.slice(rewriteCursor, ref.index))
+ rewriteCursor = ref.index + ref.length
+ if (!caption) {
+ pieces.push(ref.full)
+ continue
+ }
+ const safe = caption
+ .replace(/[\r\n]+/g, " ")
+ .replace(/]/g, ")")
+ .replace(/\\+$/g, "")
+ .trim()
+ const replacement = `![${safe}](${ref.destination})`
+ pieces.push(replacement)
+ }
+ pieces.push(markdown.slice(rewriteCursor))
+ const enrichedMarkdown = pieces.join("")
return { enrichedMarkdown, freshCaptions, cachedCaptions, failed }
}
@@ -522,5 +629,4 @@ export const __test = {
findImageReferences,
normalizeCaptionLanguage,
sha256OfBase64,
- MD_IMAGE_RE,
}
diff --git a/src/lib/ingest-queue.test.ts b/src/lib/ingest-queue.test.ts
index 238171fe..633c1f12 100644
--- a/src/lib/ingest-queue.test.ts
+++ b/src/lib/ingest-queue.test.ts
@@ -20,16 +20,13 @@ vi.mock("./sweep-reviews", () => ({
sweepResolvedReviews: vi.fn().mockResolvedValue(0),
}))
-// Mock embedding so cleanupWrittenFiles' cascade-delete to LanceDB is
-// observable. The real module is over in `./embedding` but
-// cleanupWrittenFiles dynamically imports it via `@/lib/embedding`,
-// hence the absolute mock target.
-const removePageEmbeddingMock = vi.fn<(projectPath: string, slug: string) => Promise<void>>(
+// Mock the centralized page cascade used by cleanupWrittenFiles.
+const cascadeDeleteWikiPageMock = vi.fn<(projectPath: string, filePath: string) => Promise<void>>(
async () => {},
)
-vi.mock("@/lib/embedding", () => ({
- removePageEmbedding: (projectPath: string, slug: string) =>
- removePageEmbeddingMock(projectPath, slug),
+vi.mock("@/lib/wiki-page-delete", () => ({
+ cascadeDeleteWikiPage: (projectPath: string, filePath: string) =>
+ cascadeDeleteWikiPageMock(projectPath, filePath),
}))
// Mock project-identity — tests don't hit Tauri plugin-store. Maps the
@@ -103,7 +100,11 @@ beforeEach(async () => {
mockDeleteFile.mockResolvedValue(undefined as unknown as void)
mockSweep.mockReset()
mockSweep.mockResolvedValue(0)
- removePageEmbeddingMock.mockReset()
+ cascadeDeleteWikiPageMock.mockReset()
+ cascadeDeleteWikiPageMock.mockImplementation(async (_projectPath, filePath) => {
+ const { deleteFile } = await import("@/commands/fs")
+ await deleteFile(filePath)
+ })
// Default: persisted queue file doesn't exist
mockReadFile.mockRejectedValue(new Error("ENOENT"))
@@ -1344,8 +1345,8 @@ describe("ingest-queue — pause/resume processing", () => {
})
})
-// ── cleanupWrittenFiles — file delete + LanceDB chunk cascade ──────
-describe("cleanupWrittenFiles — embedding cascade", () => {
+// ── cleanupWrittenFiles — centralized page cascade ─────────────────
+describe("cleanupWrittenFiles — page cascade", () => {
it("deletes each file AND drops its embedding chunks (relative paths)", async () => {
const { deleteFile } = await import("@/commands/fs")
const mockDeleteFile = vi.mocked(deleteFile)
@@ -1362,10 +1363,9 @@ describe("cleanupWrittenFiles — embedding cascade", () => {
expect(mockDeleteFile).toHaveBeenNthCalledWith(1, "/proj/wiki/concepts/rope.md")
expect(mockDeleteFile).toHaveBeenNthCalledWith(2, "/proj/wiki/entities/transformer.md")
- // Embedding cascade uses page slugs (basename minus .md).
- expect(removePageEmbeddingMock).toHaveBeenCalledTimes(2)
- expect(removePageEmbeddingMock).toHaveBeenNthCalledWith(1, "/proj", "rope")
- expect(removePageEmbeddingMock).toHaveBeenNthCalledWith(2, "/proj", "transformer")
+ expect(cascadeDeleteWikiPageMock).toHaveBeenCalledTimes(2)
+ expect(cascadeDeleteWikiPageMock).toHaveBeenNthCalledWith(1, "/proj", "/proj/wiki/concepts/rope.md")
+ expect(cascadeDeleteWikiPageMock).toHaveBeenNthCalledWith(2, "/proj", "/proj/wiki/entities/transformer.md")
})
it("uses absolute paths verbatim (doesn't double-prefix the project path)", async () => {
@@ -1377,8 +1377,10 @@ describe("cleanupWrittenFiles — embedding cascade", () => {
await cleanupWrittenFiles("/proj", ["/abs/elsewhere/wiki/concepts/foo.md"])
expect(mockDeleteFile).toHaveBeenCalledWith("/abs/elsewhere/wiki/concepts/foo.md")
- // Slug derivation still works on absolute paths.
- expect(removePageEmbeddingMock).toHaveBeenCalledWith("/proj", "foo")
+ expect(cascadeDeleteWikiPageMock).toHaveBeenCalledWith(
+ "/proj",
+ "/abs/elsewhere/wiki/concepts/foo.md",
+ )
})
it("continues to subsequent files when one delete throws", async () => {
@@ -1397,45 +1399,52 @@ describe("cleanupWrittenFiles — embedding cascade", () => {
// Both deleteFile attempts happened — the helper kept going.
expect(mockDeleteFile).toHaveBeenCalledTimes(2)
- // First file's embedding cascade was skipped (deleteFile threw),
- // second file's cascade still ran.
- expect(removePageEmbeddingMock).toHaveBeenCalledTimes(1)
- expect(removePageEmbeddingMock).toHaveBeenCalledWith("/proj", "present")
+ // Both cascades were attempted even though the first delete failed.
+ expect(cascadeDeleteWikiPageMock).toHaveBeenCalledTimes(2)
+ expect(cascadeDeleteWikiPageMock).toHaveBeenNthCalledWith(
+ 2,
+ "/proj",
+ "/proj/wiki/concepts/present.md",
+ )
})
- it("swallows removePageEmbedding errors so a LanceDB issue doesn't abort cleanup", async () => {
+ it("swallows page cascade errors so a LanceDB issue doesn't abort cleanup", async () => {
const { deleteFile } = await import("@/commands/fs")
const mockDeleteFile = vi.mocked(deleteFile)
mockDeleteFile.mockReset()
mockDeleteFile.mockResolvedValue(undefined)
- // First page's embedding cascade throws; second succeeds.
- removePageEmbeddingMock
- .mockRejectedValueOnce(new Error("lancedb unavailable"))
- .mockResolvedValueOnce(undefined)
+ // First page cascade throws; second succeeds.
+ cascadeDeleteWikiPageMock
+ .mockImplementationOnce(async (_projectPath, filePath) => {
+ await mockDeleteFile(filePath)
+ throw new Error("lancedb unavailable")
+ })
+ .mockImplementationOnce(async (_projectPath, filePath) => {
+ await mockDeleteFile(filePath)
+ })
await cleanupWrittenFiles("/proj", [
"wiki/concepts/a.md",
"wiki/concepts/b.md",
])
- // Both file deletes still happened.
- expect(mockDeleteFile).toHaveBeenCalledTimes(2)
// Second cascade still attempted despite first throwing.
- expect(removePageEmbeddingMock).toHaveBeenCalledTimes(2)
+ expect(cascadeDeleteWikiPageMock).toHaveBeenCalledTimes(2)
})
- it("handles Windows backslash paths via getFileStem", async () => {
+ it("passes Windows backslash paths to the centralized cascade", async () => {
const { deleteFile } = await import("@/commands/fs")
const mockDeleteFile = vi.mocked(deleteFile)
mockDeleteFile.mockReset()
mockDeleteFile.mockResolvedValue(undefined)
- // A path that's been rewritten with backslashes (Windows ingest
- // pipeline output before normalize). getFileStem must still
- // pull "rope" out cleanly so the cascade hits the right page.
+ // The centralized cascade owns path normalization and page-id derivation.
await cleanupWrittenFiles("C:/proj", ["wiki\\concepts\\rope.md"])
- expect(removePageEmbeddingMock).toHaveBeenCalledWith("C:/proj", "rope")
+ expect(cascadeDeleteWikiPageMock).toHaveBeenCalledWith(
+ "C:/proj",
+ "C:/proj/wiki\\concepts\\rope.md",
+ )
})
})
diff --git a/src/lib/ingest.ts b/src/lib/ingest.ts
index 360b5af9..8495044b 100644
--- a/src/lib/ingest.ts
+++ b/src/lib/ingest.ts
@@ -37,7 +37,11 @@ import {
buildImageMarkdownSection,
type SavedImage,
} from "@/lib/extract-source-images"
-import { captionMarkdownImages, loadCaptionCache } from "@/lib/image-caption-pipeline"
+import {
+ captionMarkdownImages,
+ loadCaptionCache,
+ stripMarkdownImageReferences,
+} from "@/lib/image-caption-pipeline"
import type { MultimodalConfig } from "@/stores/wiki-store"
import { GENERATION_WIKI_TYPES } from "@/lib/wiki-page-types"
import { computeContextBudget } from "@/lib/context-budget"
@@ -982,13 +986,9 @@ async function autoIngestImpl(
const mmCfg = useWikiStore.getState().multimodalConfig
const captionLlm = resolveCaptionConfig(mmCfg, llmConfig)
if (!mmCfg.enabled && savedImages.length > 0) {
- // Strip `![alt](url)` references — match the same regex shape
- // we use elsewhere for image refs. Preserve a single space
+ // Strip recognized `![alt](url)` references with the shared parser. Preserve a single space
// where the ref used to sit so adjacent words don't fuse.
- enrichedSourceContent = sourceContent.replace(
- /!\[[^\]]*\]\([^)\s]+\)/g,
- " ",
- )
+ enrichedSourceContent = stripMarkdownImageReferences(sourceContent)
console.log(
`[ingest:caption] disabled — stripped image refs from sourceContent (${savedImages.length} image(s) won't appear in wiki pages)`,
)