dsh-plugin-wiki-tools 0.2.1 → 0.4.0

package/index.js

@@ -76,9 +76,7 @@ export function createTools(vault, options = {}) {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: typeof value === 'object' && value !== null && 'results' in value
-          ? `wiki_query: ${value.results.length} of ${value.totalMatches} matching pages`
-          : 'wiki_query: returned hot cache and master index',
+        text: renderQueryResult(value),
       }],
     },
     async execute(args) {
@@ -181,9 +179,7 @@ export function createTools(vault, options = {}) {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: typeof value === 'object' && value !== null && 'summary' in value
-          ? `wiki_lint: ${value.summary.issues} issues across ${value.summary.pagesScanned} pages; report at ${value.reportPath ?? '(not written)'}`
-          : 'wiki_lint: failed',
+        text: renderLintResult(value),
       }],
     },
     async execute() {
@@ -195,6 +191,68 @@ export function createTools(vault, options = {}) {
   return [wikiQuery, wikiWrite, wikiLint]
 }
 
+/**
+ * Render a wiki_query result as the model-facing text. The render output is the
+ * ONLY content the model sees, so it carries the full payload — hot cache and
+ * index verbatim in quick mode, every result with path, snippets, and link
+ * context in standard mode — not a summary line.
+ * @param {unknown} value - the execute return value.
+ * @returns {string} the model-facing result text.
+ */
+function renderQueryResult(value) {
+  if (typeof value !== 'object' || value === null) return 'wiki_query: no result'
+  const result = value
+  if (result.mode === 'quick') {
+    const parts = []
+    if (typeof result.hot === 'string' && result.hot.length > 0) {
+      parts.push(`--- wiki/hot.md (recent context cache) ---\n${capText(result.hot, 6000)}`)
+    }
+    if (typeof result.index === 'string' && result.index.length > 0) {
+      parts.push(`--- wiki/index.md (master catalog) ---\n${capText(result.index, 8000)}`)
+    }
+    if (parts.length === 0) return 'wiki_query (quick): the vault has no hot.md or index.md yet'
+    return `wiki_query (quick): hot cache and master index follow. Read these before any page.\n\n${parts.join('\n\n')}`
+  }
+  if (!Array.isArray(result.results)) return 'wiki_query: no result'
+  const lines = [`wiki_query: ${result.results.length} of ${result.totalMatches} matching pages. Open a page with the fs read tool for full content.`]
+  for (const hit of result.results) {
+    lines.push(`\n### ${hit.name}`)
+    lines.push(`path: ${hit.path} · score ${hit.score} · inbound ${hit.inbound.length}${hit.inbound.length > 0 ? ` (${hit.inbound.slice(0, 5).join(', ')})` : ''} · outbound ${hit.outbound}`)
+    for (const snippet of hit.snippets) lines.push(`> ${snippet}`)
+  }
+  return capText(lines.join('\n'), 12000)
+}
+
+/**
+ * Render a wiki_lint result: every issue with page, severity, and suggestion.
+ * @param {unknown} value - the execute return value.
+ * @returns {string} the model-facing result text.
+ */
+function renderLintResult(value) {
+  if (typeof value !== 'object' || value === null || !('summary' in value)) return 'wiki_lint: failed'
+  const result = value
+  const lines = [
+    `wiki_lint: ${result.summary.issues} issues across ${result.summary.pagesScanned} pages.`,
+    `checks: ${Object.entries(result.summary.byCheck ?? {}).map(([check, count]) => `${check}×${count}`).join(', ') || 'none'}`,
+    `full report: ${typeof result.reportPath === 'string' ? result.reportPath : '(not written)'}`,
+  ]
+  for (const issue of (result.issues ?? []).slice(0, 60)) {
+    lines.push(`- [${issue.severity}] ${issue.check} · ${issue.page}: ${issue.detail} → ${issue.suggestion}`)
+  }
+  if ((result.issues ?? []).length > 60) lines.push(`… and ${result.issues.length - 60} more (see the report file)`)
+  return lines.join('\n')
+}
+
+/**
+ * Cap one text block, marking the cut.
+ * @param {string} text - full text.
+ * @param {number} max - maximum characters kept.
+ * @returns {string} the capped text.
+ */
+function capText(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max)}\n… (truncated at ${max} characters)`
+}
+
 /**
  * Validate the deployment config and register the three wiki tools.
  * @param {import('@deepseek-ai/cordis').Context} ctx - registrant context carrying the tool registry.

package/lib/lint.js

@@ -8,7 +8,7 @@
 
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { collectMarkdown, META_FILENAMES, splitFrontmatter, today } from './vault.js'
+import { collectMarkdown, isMachineryPage, splitFrontmatter, today } from './vault.js'
 
 /** Frontmatter fields every content page must carry. */
 const REQUIRED_FIELDS = ['type', 'status', 'created', 'updated', 'tags']
@@ -53,10 +53,9 @@ 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
+    if (isMachineryPage(page.name)) continue
     const key = page.name.toLowerCase()
     if (seen.has(key)) {
       add('duplicate-filename', 'error', page.name,
@@ -103,6 +102,7 @@ function checkDeadLinks(pages, add) {
   const names = new Set(pages.map(page => page.name))
   const inbound = new Map(pages.map(page => [page.name, []]))
   for (const page of pages) {
+    if (isMachineryPage(page.name)) continue
     for (const target of page.links) {
       if (names.has(target)) {
         inbound.get(target)?.push(page.name)
@@ -126,7 +126,7 @@ function checkDeadLinks(pages, add) {
 function checkOrphans(pages, inbound, indexed, add) {
   for (const page of pages) {
     const base = page.name.toLowerCase()
-    if (META_FILENAMES.has(base) || page.name.startsWith('_')) continue
+    if (isMachineryPage(page.name)) continue
     const links = inbound.get(page.name) ?? []
     const isIndexed = indexed.has(page.name)
     if (links.length === 0 && !isIndexed) {
@@ -145,7 +145,7 @@ function checkOrphans(pages, inbound, indexed, add) {
 function checkFrontmatterGaps(pages, add) {
   for (const page of pages) {
     const base = page.name.toLowerCase()
-    if (META_FILENAMES.has(base) || page.name.startsWith('_')) continue
+    if (isMachineryPage(page.name)) continue
     const missing = REQUIRED_FIELDS.filter(field => page.fields?.[field] === undefined)
     if (missing.length > 0) {
       add('frontmatter-gap', 'warn', page.name,
@@ -162,12 +162,25 @@ function checkFrontmatterGaps(pages, add) {
  */
 function checkEmptySections(pages, add) {
   for (const page of pages) {
-    if (META_FILENAMES.has(page.name.toLowerCase()) || page.name.startsWith('_')) continue
+    if (isMachineryPage(page.name)) continue
+    // Fence-aware scan: lines inside code fences are content (a section whose
+    // body is only code is not empty) and heading-like comment lines inside
+    // fences never open sections.
     const lines = [...page.content.split('\n'), '# __eof__ sentinel']
     let heading
     let headingLevel = 0
     let hasContent = false
+    let inFence = false
     for (const line of lines) {
+      if (line.startsWith('```')) {
+        inFence = !inFence
+        hasContent = true
+        continue
+      }
+      if (inFence) {
+        hasContent = true
+        continue
+      }
       const match = /^(#{1,6}) (.+)$/.exec(line)
       if (match !== null) {
         const nextLevel = match[1].length

package/lib/search.js

@@ -8,7 +8,7 @@
 
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
-import { collectMarkdown, META_FILENAMES } from './vault.js'
+import { collectMarkdown, isMachineryPage } from './vault.js'
 
 /**
  * Answer the quick mode: the hot cache and master index verbatim. The caller
@@ -40,9 +40,9 @@ export async function searchVault(root, { query, limit = 10 }) {
   const pages = await collectMarkdown(join(root, 'wiki'))
   // The link graph covers every file, but results exclude vault machinery:
   // the index matches nearly every term by construction and is already the
-  // quick-mode payload.
-  const searchable = pages.filter(page =>
-    !META_FILENAMES.has(page.name.toLowerCase()) && !page.name.startsWith('_'))
+  // quick-mode payload, and dated lint reports quote past wikilinks as records,
+  // not graph edges — so they neither appear as hits nor count as inbound.
+  const searchable = pages.filter(page => !isMachineryPage(page.name))
   const inbound = new Map(pages.map(page => [page.name, []]))
   for (const page of searchable) {
     // One inbound record per source page, however many times it links.

package/lib/vault.js

@@ -390,15 +390,33 @@ export async function collectMarkdown(directory) {
 
 /**
  * Extract wikilink targets from markdown, dropping aliases and heading anchors.
+ * Fenced code blocks and inline code spans are not links: examples written as
+ * `` `[[Target]]` `` must not join the graph.
  * @param {string} content - markdown body.
  * @returns {string[]} link targets in order of appearance.
  */
 export function extractWikilinks(content) {
   const links = []
-  const withoutFences = content.replace(/```[\s\S]*?```/g, '')
-  for (const match of withoutFences.matchAll(/\[\[([^\]]+)\]\]/g)) {
+  const withoutCode = content
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]*`/g, '')
+  for (const match of withoutCode.matchAll(/\[\[([^\]]+)\]\]/g)) {
     const target = match[1].split('|')[0].split('#')[0].trim()
     if (target.length > 0) links.push(target)
   }
   return links
 }
+
+/**
+ * Whether a page basename is vault machinery rather than content: the index,
+ * log, hot cache, overview, per-folder sub-indexes, and dated lint reports.
+ * Lint reports quote past issues verbatim, so their wikilinks are records, not
+ * graph edges.
+ * @param {string} name - page basename without extension.
+ * @returns {boolean} whether the page is machinery.
+ */
+export function isMachineryPage(name) {
+  return META_FILENAMES.has(name.toLowerCase())
+    || name.startsWith('_')
+    || /^lint-report-/.test(name)
+}

package/package.json

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