@sdsrs/llm-wiki 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.6.4 (2026-07-11)
+
+Six fixes from a full-pipeline self-test pass (as a real user across every
+command). No breaking changes, no KB migration, no config change. Suite 179 →
+185.
+
+- **fix(convert): PDF conversion was 100% broken** and is now restored. The code
+  imported `pdf-parse/lib/pdf-parse.js` — the v1 subpath — but the pinned
+  dependency is pdf-parse v2, whose export map has no such subpath, so *every*
+  PDF failed at import time before any parsing. Switched to the v2 API
+  (`new PDFParse({ data }).getText()`). It slipped through because there was no
+  PDF fixture and the only test fed garbage bytes, which the import failure also
+  satisfied; added a real `test/fixtures/hello.pdf` + a positive extraction test.
+- fix(ask): `ask --retrieve-only` no longer prints nothing (exit 0) when
+  retrieval locates zero pages — the state right after `init`/`scan`, before the
+  wiki is built. It now emits a diagnostic to stderr (stdout stays pipe-clean),
+  matching the LLM path which already errored.
+- fix(convert): a source file whose whole basename is emoji/symbols
+  (e.g. `😀.md`) no longer produces a hidden `raw/.md` that `status` skips
+  (silently dropping the source from the incremental workflow). `slugify` now
+  falls back to `untitled`, so the existing `-N` collision handler yields
+  visible, shell-safe names (`untitled.md`, `untitled-2.md`, …).
+- fix(scan): a missing or non-directory source path now gives a human-readable
+  error ("source directory not found: X" / "source path is not a directory: X")
+  instead of a raw `ENOENT`/`ENOTDIR`; also improves `status --src`.
+- fix(export): `export --out path/with/missing/dirs/graph.graphml` now creates
+  the parent directory (matching the markdown-export sibling) instead of leaking
+  a raw `ENOENT`.
+- docs: the layout diagram placed `llms.txt` under `wiki/`, but `index` writes it
+  to the KB root (the llms.txt convention); corrected the diagram and command
+  table.
+
+## 0.6.3 (2026-07-11)
+
+Two cosmetic fixes from an independent review of 0.6.0–0.6.2; no behavior
+change beyond the scan warning's rounding.
+
+- fix(scan): the tag-dispersion warning now flags on the same rounded top-tag
+  share it displays, so it can no longer print "top tag covers 30%" while
+  firing a "below 30%" rule. Effective threshold is 29.5% (was a raw 30% with
+  an inconsistent display); negligible for an advisory heuristic. Suite 178 →
+  179.
+- docs: note that the JSON Canvas map's `file` cards are vault-relative from the
+  KB root, so a canvas written outside the KB via `--out` won't resolve them in
+  Obsidian — open the canvas with the KB as its own vault.
+
 ## 0.6.2 (2026-07-11)
 
 No breaking changes, no KB migration, no default-behavior change — one additive

package/README.md

@@ -84,7 +84,7 @@ npx @sdsrs/llm-wiki@0 ask "what did we decide about X?"
 | `init [dir]` | scaffold a knowledge base (raw/, wiki/, AGENTS.md, wiki.config.json) |
 | `scan <srcDir>` | inventory a source dir: dedup, batches, incremental diff, token estimate |
 | `convert` | convert files from the scan plan into `raw/` markdown |
-| `index` | rebuild `wiki/index.md`, `graph.json`, `llms.txt` from page frontmatter |
+| `index` | rebuild `wiki/index.md`, `wiki/graph.json`, and root `llms.txt` from page frontmatter |
 | `ask <question>` | answer from the KB using full pages (never chunks), with citations |
 | `lint` | mechanical checks + a semantic worklist for the agent |
 | `status` | incremental state: uncompiled raw files, source-dir diff, affected wiki pages |
@@ -147,6 +147,9 @@ human to resolve.
 
 `export --format canvas` writes a JSON Canvas (`graph.canvas`) domain map —
 `file` cards laid out by page type that open as live notes in Obsidian Canvas.
+The card paths are vault-relative from the KB root, so open the canvas with the
+KB as its own vault; a canvas written outside the KB via `--out` won't resolve
+its cards.
 
 ### Skills (Claude Code / Codex)
 
@@ -213,7 +216,8 @@ my-kb/
   raw/                 immutable converted source documents (agents only read)
   wiki/
     sources/  entities/  concepts/  comparisons/   full pages, one file each
-    index.md  graph.json  llms.txt                 generated by `index`
+    index.md  graph.json                           generated by `index`
+  llms.txt             flat page listing for agents, KB root (generated by `index`)
   AGENTS.md            the contract every maintaining agent follows
   wiki.config.json     thresholds, batch size, language
 ```

package/bin/llm-wiki.mjs

@@ -74,6 +74,10 @@ program.command('ask <question>')
     if (!Number.isFinite(k) || k < 1) { console.error(`invalid -k value: ${opts.k} (expected a positive integer)`); process.exit(1) }
     const r = await askKb(opts.kb, question, { k, retrieveOnly: opts.retrieveOnly })
     if (opts.retrieveOnly) {
+      if (r.pages.length === 0) {
+        console.error('no pages located — the KB has no matching wiki pages (build them with the wiki-build skill, or check that wiki/ contains pages)')
+        return
+      }
       for (const h of r.pages) console.log(`${h.score.toFixed(3)}  ${h.relPath}  [${(h.sources ?? ['bm25']).join('+')}]`)
     } else {
       console.log(r.answer)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/llm-wiki",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Compile messy document directories into Karpathy-style llm_wiki knowledge bases — standalone Q&A CLI + Claude Code/Codex skills",
   "directories": {
     "test": "test"

package/src/convert.mjs

@@ -4,10 +4,14 @@ import path from 'node:path'
 export const SUPPORTED_EXTS = ['.md', '.markdown', '.txt', '.html', '.htm', '.pdf', '.docx']
 
 export function slugify(name) {
-  return name.toLowerCase()
+  const slug = name.toLowerCase()
     .replace(/\.[a-z0-9]+$/i, '')
     .replace(/[^\p{L}\p{N}]+/gu, '-')
     .replace(/^-+|-+$/g, '')
+  // A basename made entirely of emoji/symbols slugs to '' → a hidden `raw/.md`
+  // dotfile that `status` skips (source silently dropped). Never return empty;
+  // the caller's -N collision handler disambiguates untitled/untitled-2/…
+  return slug || 'untitled'
 }
 
 function titleFrom(markdown, fallback) {
@@ -44,9 +48,9 @@ export async function convertFile(srcPath) {
       return { markdown: `# ${article.title || base}\n\n${md}`, title: article.title || base, warnings }
     }
     if (ext === '.pdf') {
-      const pdfParse = (await import('pdf-parse/lib/pdf-parse.js')).default
-      const data = await pdfParse(fs.readFileSync(srcPath))
-      return { markdown: data.text, title: titleFrom(data.text, base), warnings }
+      const { PDFParse } = await import('pdf-parse')
+      const { text } = await new PDFParse({ data: fs.readFileSync(srcPath) }).getText()
+      return { markdown: text, title: titleFrom(text, base), warnings }
     }
     if (ext === '.docx') {
       const mammoth = await import('mammoth')

package/src/export.mjs

@@ -301,6 +301,9 @@ export function exportGraph(kbRoot, { format, out } = {}) {
   if (!render) throw new Error(`unknown format: ${format} (expected ${Object.keys(RENDERERS).join(' | ')} | markdown)`)
   const graph = loadGraph(kbRoot)
   const outPath = out ?? path.join(kbRoot, `graph.${EXT[format]}`)
+  // Match the markdown-export sibling: create the parent of an explicit --out so
+  // `--out new/dir/graph.graphml` writes instead of leaking a raw ENOENT.
+  fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true })
   fs.writeFileSync(outPath, render(graph))
   return { out: outPath, nodeCount: graph.nodes.length, edgeCount: graph.edges.length }
 }

package/src/scanner.mjs

@@ -33,8 +33,12 @@ function detectDomainMixture(files, kbRoot) {
   if (pages.length >= TAG_MIN_PAGES) {
     const counts = new Map()
     for (const p of pages) for (const t of new Set(p.data.tags)) counts.set(t, (counts.get(t) ?? 0) + 1)
-    const topShare = Math.max(...counts.values()) / pages.length
-    tags = { pages: pages.length, distinct: counts.size, topShare: Number(topShare.toFixed(2)), flagged: topShare < TAG_TOP_SHARE_MIN }
+    // Round once and flag on the rounded value so the stored/displayed share
+    // (CLI prints Math.round(topShare*100)) never reads "30%" while the strict
+    // `< TAG_TOP_SHARE_MIN` rule fired on a raw 0.29x. Effective threshold is
+    // 29.5%; negligible for an advisory heuristic, and flag/display now agree.
+    const topShare = Number((Math.max(...counts.values()) / pages.length).toFixed(2))
+    tags = { pages: pages.length, distinct: counts.size, topShare, flagged: topShare < TAG_TOP_SHARE_MIN }
   }
   return { language, tags, flagged: language.flagged || (tags?.flagged ?? false) }
 }
@@ -67,6 +71,9 @@ function* walk(dir, base = dir, skippedDirs = [], exclude = []) {
 // `persist: false` runs a read-only scan (e.g. for `status`) that does not
 // overwrite the .scan-plan.json a previous explicit `scan` produced.
 export async function scanSource(srcDir, kbRoot, { exclude = [], persist = true } = {}) {
+  const st = fs.statSync(srcDir, { throwIfNoEntry: false })
+  if (!st) throw new Error(`source directory not found: ${srcDir}`)
+  if (!st.isDirectory()) throw new Error(`source path is not a directory: ${srcDir}`)
   const cfg = loadKbConfig(kbRoot)
   const files = []
   const skipped = []