dsh-plugin-wiki-tools 0.1.0 → 0.2.1

package/README.md

@@ -30,9 +30,13 @@ dsh plugin --profile web add dsh-plugin-wiki-tools
 - id: wiki-tools
   config:
     vaultPath: /absolute/path/to/vault
+    # optional: reroute page types to your vault's folders; index section
+    # headings follow the mapped folder name (e.g. "## Areas")
+    typeFolders:
+      domain: wiki/areas
 ```
 
-The vault is the directory holding `wiki/` and `.raw/` — scaffold it first with the `wiki` skill's SCAFFOLD operation. `maxQueryResults` (default 10) is optional.
+The vault is the directory holding `wiki/` and `.raw/` — scaffold it first with the `wiki` skill's SCAFFOLD operation. `maxQueryResults` (default 10) is optional. `wiki_write` refreshes existing index entries in the section's own style (`: ` or ` — `), so em-dash vaults stay consistent.
 
 ## Design notes
 

package/index.js

@@ -26,6 +26,16 @@ export const Config = z.object({
   vaultPath: z.string().required(),
   /** Maximum pages returned by one wiki_query standard-mode call. */
   maxQueryResults: z.number().default(10),
+  /** Per-type folder overrides over the default routing, e.g. `{ domain: "wiki/areas" }`. */
+  typeFolders: z.object({
+    source: z.string(),
+    entity: z.string(),
+    concept: z.string(),
+    domain: z.string(),
+    question: z.string(),
+    comparison: z.string(),
+    meta: z.string(),
+  }).default({}),
 })
 
 const PAGE_TYPES = ['source', 'entity', 'concept', 'domain', 'question', 'comparison', 'meta']
@@ -201,7 +211,7 @@ export async function apply(ctx, config) {
       + 'The vault is the directory holding wiki/ and .raw/ (scaffold it with the wiki skill first).',
     )
   }
-  const vault = new Vault(config.vaultPath)
+  const vault = new Vault(config.vaultPath, config.typeFolders ?? {})
   await vault.assertRoot()
   for (const tool of createTools(vault, config)) {
     ctx.tools.register(tool)

package/lib/lint.js

@@ -53,8 +53,10 @@ export async function lintVault(root) {
  * @param {Add} add - issue recorder.
  */
 function checkDuplicateFilenames(pages, add) {
+  const isMachinery = page => META_FILENAMES.has(page.name.toLowerCase()) || page.name.startsWith('_')
   const seen = new Map()
   for (const page of pages) {
+    if (isMachinery(page)) continue
     const key = page.name.toLowerCase()
     if (seen.has(key)) {
       add('duplicate-filename', 'error', page.name,
@@ -160,18 +162,24 @@ function checkFrontmatterGaps(pages, add) {
  */
 function checkEmptySections(pages, add) {
   for (const page of pages) {
-    if (META_FILENAMES.has(page.name.toLowerCase())) continue
-    const lines = [...page.content.split('\n'), '# __eof__']
+    if (META_FILENAMES.has(page.name.toLowerCase()) || page.name.startsWith('_')) continue
+    const lines = [...page.content.split('\n'), '# __eof__ sentinel']
     let heading
+    let headingLevel = 0
     let hasContent = false
     for (const line of lines) {
-      if (/^#{1,6} /.test(line)) {
-        if (heading !== undefined && !hasContent) {
+      const match = /^(#{1,6}) (.+)$/.exec(line)
+      if (match !== null) {
+        const nextLevel = match[1].length
+        // A heading followed directly by a deeper heading is a container, not
+        // an empty section; only same-or-shallow succession or EOF is empty.
+        if (heading !== undefined && !hasContent && nextLevel <= headingLevel) {
           add('empty-section', 'info', page.name,
             `section "${heading}" has no content`,
             'Fill it, or remove the heading')
         }
-        heading = line.replace(/^#+\s*/, '').replace('__eof__', '').trim()
+        heading = match[2]
+        headingLevel = nextLevel
         hasContent = false
       } else if (line.trim().length > 0) {
         hasContent = true

package/lib/search.js

@@ -45,7 +45,8 @@ export async function searchVault(root, { query, limit = 10 }) {
     !META_FILENAMES.has(page.name.toLowerCase()) && !page.name.startsWith('_'))
   const inbound = new Map(pages.map(page => [page.name, []]))
   for (const page of searchable) {
-    for (const target of page.links) {
+    // One inbound record per source page, however many times it links.
+    for (const target of new Set(page.links)) {
       inbound.get(target)?.push(page.name)
     }
   }
@@ -68,7 +69,7 @@ export async function searchVault(root, { query, limit = 10 }) {
       score,
       snippets: matchLines(page.content, needle).slice(0, 2),
       inbound: inbound.get(page.name) ?? [],
-      outbound: page.links.length,
+      outbound: new Set(page.links).size,
     })
   }
   results.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name))

package/lib/vault.js

@@ -13,7 +13,7 @@
 
 import { createHash } from 'node:crypto'
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
-import { isAbsolute, join, relative, sep } from 'node:path'
+import { basename, isAbsolute, join, relative, sep } from 'node:path'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 
 /** Page-type to vault folder routing (the suite's generic mode). */
@@ -27,14 +27,15 @@ export const TYPE_FOLDERS = {
   meta: 'wiki/meta',
 }
 
-/** Master-index section heading per page type, in catalog order. */
-const INDEX_SECTIONS = {
-  domain: '## Domains',
-  entity: '## Entities',
-  concept: '## Concepts',
-  source: '## Sources',
-  question: '## Questions',
-  comparison: '## Comparisons',
+/** Master-index section headings follow the mapped folder basename, computed per vault. */
+
+/**
+ * Capitalize a folder basename for an index section heading.
+ * @param {string} value - lowercase folder basename.
+ * @returns {string} the capitalized heading title.
+ */
+function capitalize(value) {
+  return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1)
 }
 
 /** Pages that are vault machinery, never linted as content (basenames, no extension). */
@@ -73,19 +74,37 @@ export function today() {
  * entry in one serialized write per file.
  */
 export class Vault {
-  /** @param {string} root - absolute path to the vault root (the directory holding `wiki/` and `.raw/`). */
-  constructor(root) {
+  /**
+   * @param {string} root - absolute path to the vault root (the directory holding `wiki/` and `.raw/`).
+   * @param {Record<string, string>} [typeFolders] - per-type folder overrides over {@link TYPE_FOLDERS}
+   *   (e.g. `{ domain: 'wiki/areas' }` for a vault whose top-level topics live in `areas/`).
+   */
+  constructor(root, typeFolders = {}) {
     if (typeof root !== 'string' || root.length === 0 || !isAbsolute(root)) {
       throw new Error(`wiki-tools: vaultPath must be an absolute directory path (got ${JSON.stringify(root)})`)
     }
     this.root = root
+    this.typeFolders = { ...TYPE_FOLDERS }
+    for (const [type, folder] of Object.entries(typeFolders)) {
+      if (!(type in this.typeFolders)) {
+        throw new Error(`wiki-tools: typeFolders config names unknown type "${type}"`)
+      }
+      if (typeof folder !== 'string' || folder.length === 0 || folder.includes('..')) {
+        throw new Error(`wiki-tools: typeFolders.${type} must be a non-empty vault-relative folder path`)
+      }
+      this.typeFolders[type] = folder
+    }
+    /** Index section heading per type, following the effective folder layout. */
+    this.indexSections = Object.fromEntries(
+      Object.keys(TYPE_FOLDERS).map(type => [type, `## ${capitalize(basename(this.typeFolders[type]))}`]),
+    )
     /** Per-file write chains so concurrent tool calls serialize per target. */
     this.writeChains = new Map()
   }
 
   /** Absolute path of one routed page. @param {string} type - page type. @param {string} title - page title (also the filename). */
   pagePath(type, title) {
-    const folder = TYPE_FOLDERS[type]
+    const folder = this.typeFolders[type]
     if (folder === undefined) throw new Error(`wiki-tools: unknown page type "${type}"`)
     if (!/^[^/\\]+(\.md)?$/.test(title) || title.includes('\n')) {
       throw new Error(`wiki-tools: title must be a plain filename without path separators (got ${JSON.stringify(title)})`)
@@ -195,42 +214,44 @@ export class Vault {
   }
 
   /**
-   * Add or refresh one `- [[Title]]: summary` entry in the master index.
-   * Missing sections and files are created on first use.
+   * Add or refresh one `[[Title]]` entry in the master index. Missing sections
+   * and files are created on first use. Existing entries are matched regardless
+   * of separator (`: ` or ` — `) and rewritten in the section's dominant style,
+   * so vaults using em-dash indexes stay consistent.
    * @param {string} type - page type selecting the index section.
    * @param {string} title - page title.
    * @param {string} summary - one-line description.
    */
   async updateIndex(type, title, summary) {
-    const heading = INDEX_SECTIONS[type]
+    const heading = this.indexSections[type]
     if (heading === undefined) return
     const indexPath = join(this.root, 'wiki', 'index.md')
     let raw = await readFile(indexPath, 'utf8').catch(() => undefined)
     if (raw === undefined) {
       raw = '# Wiki Index\n\n'
-      for (const section of Object.values(INDEX_SECTIONS)) raw += `${section}\n\n`
+      for (const section of Object.values(this.indexSections)) raw += `${section}\n\n`
       await mkdir(join(indexPath, '..'), { recursive: true })
     }
-    const entry = `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`
     const lines = raw.split('\n')
     let headingLine = lines.findIndex(line => line === heading)
     if (headingLine < 0) {
-      lines.push('', heading, entry)
-      await writeFile(indexPath, lines.join('\n').replace(/\n{3,}/g, '\n\n'), 'utf8')
+      lines.push('', heading, `- [[${title}]]: ${summary.replace(/\n/g, ' ')}`)
+      await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
       return
     }
-    const linkPrefix = `- [[${title}]]`
-    let cursor = headingLine + 1
-    while (cursor < lines.length && lines[cursor] !== '' && !lines[cursor].startsWith('## ')) {
-      if (lines[cursor].startsWith(linkPrefix)) {
-        lines[cursor] = entry
-        await writeFile(indexPath, lines.join('\n'), 'utf8')
-        return
-      }
-      cursor += 1
+    let end = headingLine + 1
+    while (end < lines.length && lines[end] !== '' && !lines[end].startsWith('## ')) end += 1
+    const section = lines.slice(headingLine + 1, end)
+    const entryPattern = new RegExp(`^\\s*-?\\s*\\[\\[${escapeRegExp(title)}\\]\\]`)
+    const at = section.findIndex(line => entryPattern.test(line))
+    const separator = indexSeparator(section, at >= 0 ? section[at] : undefined)
+    const entry = `- [[${title}]]${separator} ${summary.replace(/\n/g, ' ')}`
+    if (at >= 0) {
+      lines[headingLine + 1 + at] = entry
+    } else {
+      lines.splice(end, 0, entry)
     }
-    lines.splice(cursor, 0, entry)
-    await writeFile(indexPath, lines.join('\n'), 'utf8')
+    await writeFile(indexPath, `${lines.join('\n')}\n`, 'utf8')
   }
 
   /**
@@ -295,6 +316,29 @@ function firstContentLine(content) {
   return '(no summary)'
 }
 
+/**
+ * Escape regex metacharacters so a title containing `(`, `)`, `+`, etc. matches literally.
+ * @param {string} value - raw title.
+ * @returns {string} regex-safe text.
+ */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Pick the index separator for one entry: reuse the matched line's style, else
+ * the section's dominant style (`: ` or ` — `), else the canonical colon.
+ * @param {string[]} section - existing entry lines of the index section.
+ * @param {string | undefined} matched - the line being refreshed, when present.
+ * @returns {string} the separator text before the summary.
+ */
+function indexSeparator(section, matched) {
+  if (matched !== undefined && matched.includes(' — ')) return ' —'
+  const dashes = section.filter(line => line.includes(' — ')).length
+  const colons = section.filter(line => /: /.test(line)).length
+  return dashes > colons ? ' —' : ':'
+}
+
 /**
  * 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.1.0",
+  "version": "0.2.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",