dsh-plugin-wiki-tools 0.13.0 → 0.14.1

package/README.md

@@ -16,7 +16,7 @@ The vault layout and operation contracts follow the LLM Wiki pattern (Andrej Kar
 | --- | --- |
 | `wiki_query` | Quick mode returns `hot.md` + `index.md` verbatim (the skill's read order); standard mode is full-text search over content pages with snippets and the inbound/outbound link graph |
 | `wiki_write` | Writes one page with complete bookkeeping: type→folder routing, frontmatter completion (keeps `created` and unknown fields on update), filename-uniqueness guard, master-index entry, log entry; with `source_path`, records the source hash and skips unchanged sources unless `force` |
-| `wiki_lint` | Health check: duplicate filenames, dead wikilinks, orphan pages, frontmatter gaps, empty sections, stale index entries, stale hot cache — report only, with suggestions, written to `wiki/meta/lint-report-<date>.md` |
+| `wiki_lint` | Health check: duplicate filenames, dead wikilinks, orphan pages, frontmatter gaps, empty sections, stale index entries, stale hot cache — report only, with suggestions, written to `wiki/meta/Lint Report <date>.md` |
 
 ## Install and configure
 

package/lib/lint.js

@@ -1,12 +1,12 @@
 /**
  * Vault health checks: the mechanical half of the wiki-lint skill. Report
  * only — auto-fixing is a human decision, so every issue carries a suggestion
- * and the report lands in `wiki/meta/lint-report-YYYY-MM-DD.md`.
+ * and the report lands in `wiki/meta/Lint Report YYYY-MM-DD.md`.
  *
  * @module dsh-plugin-wiki-tools/lib/lint
  */
 
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import {
   PAGE_STATUSES,
@@ -39,6 +39,7 @@ export async function lintVault(root) {
   checkOrphans(pages, inbound, indexed, add)
   checkFrontmatterGaps(pages, add)
   checkStatusVocabulary(pages, add)
+  await checkStructurePages(root, add)
   checkEmptySections(pages, add)
   await checkHotCacheStaleness(root, pages, add)
 
@@ -193,6 +194,23 @@ function checkStatusVocabulary(pages, add) {
   }
 }
 
+/**
+ * The narrative structure page every vault layout expects. `overview.md` is
+ * human-maintained, so its absence is info — a nudge, not a defect.
+ * @param {string} root - absolute vault root.
+ * @param {Add} add - issue recorder.
+ */
+async function checkStructurePages(root, add) {
+  const overview = join(root, 'wiki', 'overview.md')
+  const exists = await stat(overview).then(() => true, () => false)
+  if (!exists) {
+    add('missing-structure', 'info', 'overview',
+      'wiki/overview.md does not exist',
+      'Run wiki_scaffold (generic) or write a ~200-word vault overview: what the vault is for, its areas, and where things go',
+    )
+  }
+}
+
 /**
  * Headings with no content before the next heading.
  * @param {Pages} pages - collected pages.
@@ -271,7 +289,7 @@ async function checkHotCacheStaleness(root, pages, add) {
  */
 async function writeReport(root, issues, pagesScanned) {
   const date = today()
-  const path = join(root, 'wiki', 'meta', `lint-report-${date}.md`)
+  const path = join(root, 'wiki', 'meta', `Lint Report ${date}.md`)
   const sections = new Map()
   for (const issue of issues) {
     if (!sections.has(issue.check)) sections.set(issue.check, [])

package/lib/vault.js

@@ -132,9 +132,32 @@ export class Vault {
     )
     /** Per-file write chains so concurrent tool calls serialize per target. */
     this.writeChains = new Map()
+    /** collectMarkdown result cache: { pages, ts }. Invalidated on every mutation. */
+    this._collectCache = null
   }
 
-  /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
+    /**
+  * Cached wrapper around the module-level collectMarkdown. The cache lives
+  * for 30 s or until the next invalidateCollectCache call, whichever comes
+  * first. Writes always invalidate first, so a writer never sees stale data
+  * from its own session. Cross-process writes are visible on the next call
+  * after the cache expires.
+  * @returns {Promise<ReturnType<typeof collectMarkdown>>}
+  */
+ async collectPages() {
+   if (this._collectCache !== null) {
+     const { pages, ts } = this._collectCache
+     if (Date.now() - ts < 30000) return pages
+   }
+   const pages = await collectMarkdown(join(this.root, 'wiki'))
+   this._collectCache = { pages, ts: Date.now() }
+   return pages
+ }
+
+ /** Drop the collectMarkdown cache. Call after every vault mutation. */
+ invalidateCollectCache() { this._collectCache = null }
+
+ /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
   pagePath(type, title) {
     const folder = this.typeFolders[type]
     if (folder === undefined) throw new Error(`wiki-tools: unknown page type "${type}"`)
@@ -333,6 +356,7 @@ export class Vault {
       const file = `---\n${stringifyYaml(fields).trimEnd()}\n---\n\n${content.replace(/^\s*\n/, '')}\n`
       await mkdir(join(path, '..'), { recursive: true })
       await writeFile(path, file, 'utf8')
+      this.invalidateCollectCache()
       await this.updateIndex(type, cleanTitle, summary ?? firstContentLine(content))
       await this.updateFolderIndex(type, cleanTitle, summary ?? firstContentLine(content))
       await this.prependLog(`## [${date}] ${existing === undefined ? 'create' : 'update'} | ${cleanTitle}`, [
@@ -349,7 +373,11 @@ export class Vault {
       // Surface dead-on-arrival wikilinks now, not at the next lint: forward
       // links to pages about to be created are legitimate, so this is a note,
       // never a rejection.
-      const pagesNow = await collectMarkdown(join(this.root, 'wiki'))
+      // All vault mutations above this point may have invalidated earlier
+      // cache entries; force a fresh scan so the unresolved-links report
+      // reflects every page the vault actually contains right now.
+      this.invalidateCollectCache()
+      const pagesNow = await this.collectPages()
       const names = new Set(pagesNow.map(page => page.name))
       const aliases = buildAliasMap(pagesNow)
       const unresolvedLinks = [...new Set(extractWikilinks(content))]
@@ -414,7 +442,7 @@ export class Vault {
         throw new Error(`wiki-tools: newTitle must be a plain filename without path separators (got ${JSON.stringify(newTitle)})`)
       }
       if (cleanNew === title) throw new Error('wiki-tools: newTitle equals the current title')
-      const pages = await collectMarkdown(join(this.root, 'wiki'))
+      const pages = await this.collectPages()
       const target = pages.find(page => page.name === title)
       if (target === undefined) throw new Error(`wiki-tools: no page named "${title}" exists in the vault`)
       if (isMachineryPage(title)) {
@@ -430,7 +458,7 @@ export class Vault {
       // 1. Rewrite links everywhere except immutable records.
       const rewritten = []
       for (const page of pages) {
-        if (page.name === title || page.name.toLowerCase() === 'log' || /^lint-report-/.test(page.name)) continue
+        if (page.name === title || page.name.toLowerCase() === 'log' || isMachineryPage(page.name)) continue
         const raw = await readFile(page.path, 'utf8').catch(() => undefined)
         if (raw === undefined) continue
         // Exact-target boundary: the title must end the link target (`]]`),
@@ -439,7 +467,9 @@ export class Vault {
         // `\]` / `\|` would be eaten by the template literal and leave an
         // empty alternation branch matching every `[[title` prefix.
         const pattern = new RegExp(`\\[\\[${escapeRegExp(title)}(\\]\\]|\\||#)`, 'g')
-        const updated = raw.replace(pattern, `[[${cleanNew}$1`)
+        let updated = raw.replace(pattern, `[[${cleanNew}$1`)
+        // A page whose links changed today is not "current" as of yesterday.
+        if (updated !== raw) updated = updated.replace(/^(updated:\s*).+$/m, `$1${today()}`)
         if (updated !== raw) {
           await writeFile(page.path, updated, 'utf8')
           rewritten.push(page.name)
@@ -463,6 +493,7 @@ export class Vault {
         `- Renamed: [[${title}]] → [[${cleanNew}]] (${rewritten.length} files' links rewritten)`,
       ])
       this.gitCommit(`wiki: rename ${title} -> ${cleanNew}`)
+      this.invalidateCollectCache()
       return { from: title, to: cleanNew, path: newPath, linksRewritten: rewritten.length, filesRewritten: rewritten }
     }))
   }
@@ -501,6 +532,7 @@ export class Vault {
         `- Archived: \`${rel}\` → \`.archive/${rel.slice('.raw/'.length)}\``,
       ])
       this.gitCommit(`wiki: archive ${rel}`)
+      this.invalidateCollectCache()
       return { archivedFrom: rel, archivedTo: `.archive/${rel.slice('.raw/'.length)}` }
     }))
   }
@@ -528,7 +560,7 @@ export class Vault {
    * @param {string} path - the routed destination path.
    */
   async assertUniqueFilename(title, path) {
-    const pages = await collectMarkdown(join(this.root, 'wiki'))
+    const pages = await this.collectPages()
     for (const page of pages) {
       if (page.name.toLowerCase() === title.toLowerCase() && page.path !== path) {
         throw new Error(`wiki-tools: filename "${title}.md" already exists at ${page.path}; wikilinks need unique filenames`)
@@ -558,7 +590,8 @@ export class Vault {
     const lines = raw.split('\n')
     let headingLine = lines.findIndex(line => line === heading)
     if (headingLine < 0) {
-      lines.push('', heading, `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`)
+      const separator = dominantSeparator(raw)
+      lines.push('', heading, `- [[${title}]]${separator} ${summary.replace(/\n/g, ' ')}`)
       await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
       return
     }
@@ -721,6 +754,20 @@ function indexSeparator(section, matched) {
   return dashes > colons ? ' —' : ':'
 }
 
+/**
+ * Pick the dominant separator style across all index entry lines in one body
+ * of text: ` — ` (em-dash) if it appears in more entries than `: `, else colon.
+ * Used when a new section has no prior entries to copy style from.
+ * @param {string} text - the full index text.
+ * @returns {string} either ' —' or ':'.
+ */
+function dominantSeparator(text) {
+  const entries = text.split('\n').filter(line => /^- \[\[/.test(line))
+  const dashCount = entries.filter(line => line.includes(' — ')).length
+  const colonCount = entries.filter(line => line.includes(': ')).length
+  return dashCount > colonCount ? ' —' : ':'
+}
+
 /**
  * Read a JSON file, returning the fallback when absent.
  * @param {string} path - absolute file path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wiki-tools",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Native DeepSeek Harness tools for an Obsidian wiki vault: wiki_query, wiki_write, and wiki_lint implement the mechanical core (path routing, delta tracking, index/log bookkeeping, health checks) of the wiki skill suite.",
   "license": "MIT",
   "type": "module",