dsh-plugin-wiki-tools 0.12.0 → 0.14.0

package/index.js

@@ -106,7 +106,9 @@ export function createTools(vault, options = {}) {
       + 'CONFIGURED VAULT (run wiki_query to see its absolute root), not the session workspace. '
       + 'The content is the '
       + 'markdown body only — frontmatter is managed. With source_path, records the source hash in '
-      + 'the ingest manifest and reports already_ingested for unchanged content unless force is set.',
+      + 'the ingest manifest and reports already_ingested for unchanged content unless force is set. '
+      + 'The result lists unresolved wikilinks in the written page (targets that match no page or alias) '
+      + 'so dead links are fixed at write time, not at the next lint.',
     parameters: {
       title: {
         type: 'string',
@@ -168,6 +170,9 @@ export function createTools(vault, options = {}) {
           ? `wiki_write: skipped ${args.title} — source hash unchanged (pass force: true to re-ingest)`
           : typeof value === 'object' && value !== null && 'path' in value
             ? `wiki_write: ${value.created ? 'created' : 'updated'} ${value.path}`
+              + (Array.isArray(value.unresolvedLinks) && value.unresolvedLinks.length > 0
+                ? `\nwiki_write: note — ${value.unresolvedLinks.length} unresolved wikilink(s) in this page: ${value.unresolvedLinks.slice(0, 8).join(', ')}${value.unresolvedLinks.length > 8 ? ', …' : ''}. Create those pages or fix the targets; until then lint reports them as dead links.`
+                : '')
             : `wiki_write: skipped ${args.title} (source unchanged)`,
       }],
     },

package/lib/lint.js

@@ -6,7 +6,7 @@
  * @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.

package/lib/vault.js

@@ -346,7 +346,18 @@ export class Vault {
           pagesUpdated: existing === undefined ? [] : [cleanTitle],
         })
       }
-      return { path, created: existing === undefined, title: cleanTitle }
+      // 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'))
+      const names = new Set(pagesNow.map(page => page.name))
+      const aliases = buildAliasMap(pagesNow)
+      const unresolvedLinks = [...new Set(extractWikilinks(content))]
+        .filter(target => resolveLinkTarget(target, names, aliases) === undefined)
+      return {
+        path, created: existing === undefined, title: cleanTitle,
+        ...(unresolvedLinks.length > 0 ? { unresolvedLinks } : {}),
+      }
     }))
   }
 
@@ -406,6 +417,9 @@ export class Vault {
       const pages = await collectMarkdown(join(this.root, 'wiki'))
       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)) {
+        throw new Error(`wiki-tools: "${title}" is vault machinery (index, log, hot cache, overview, sub-index, or lint report); renames would break conventions — fix the pages linking to it instead`)
+      }
       if (pages.some(page => page.name !== title && page.name.toLowerCase() === cleanNew.toLowerCase())) {
         throw new Error(`wiki-tools: filename "${cleanNew}.md" already exists; wikilinks need unique filenames`)
       }
@@ -425,7 +439,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)
@@ -829,7 +845,12 @@ export function extractWikilinks(content) {
  * @returns {boolean} whether the page is machinery.
  */
 export function isMachineryPage(name) {
-  return META_FILENAMES.has(name.toLowerCase())
+  const lowered = name.toLowerCase()
+  return META_FILENAMES.has(lowered)
     || name.startsWith('_')
-    || /^lint-report-/.test(name)
+    || lowered.startsWith('_')
+    // Case-insensitive with a real boundary: reports have been hand-retitled
+    // to "Lint Report …" in real sessions, and those are still machinery —
+    // but "Lint Reporter Profile" is content.
+    || /^lint[- _]?report([- _].+)?$/i.test(name)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-wiki-tools",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "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",