kirograph 0.15.0 → 0.16.0

package/dist/docs/indexer.js

@@ -0,0 +1,340 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var indexer_exports = {};
+__export(indexer_exports, {
+  DocsIndexer: () => DocsIndexer
+});
+module.exports = __toCommonJS(indexer_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+var import_picomatch = __toESM(require("picomatch"));
+var import_section_id = require("./section-id");
+var import_formats = require("./formats/index");
+var import_linker = require("./linker");
+var import_vectors = require("./vectors");
+class DocsIndexer {
+  constructor(db, config, projectRoot) {
+    this.db = db;
+    this.config = config;
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Index all documentation files in the project.
+   * Skips files whose content hash hasn't changed (incremental).
+   */
+  async indexAll(opts) {
+    const start = Date.now();
+    const result = {
+      filesIndexed: 0,
+      sectionsCreated: 0,
+      sectionsUpdated: 0,
+      sectionsRemoved: 0,
+      codeRefsCreated: 0,
+      errors: [],
+      duration: 0
+    };
+    const files = this.scanDocFiles();
+    opts?.onProgress?.(`docs: found ${files.length} documentation files`);
+    for (const relPath of files) {
+      try {
+        const changed = await this.indexFile(relPath, opts?.force ?? false);
+        if (changed) {
+          result.filesIndexed++;
+          result.sectionsCreated += changed.created;
+          result.sectionsUpdated += changed.updated;
+          result.sectionsRemoved += changed.removed;
+          result.codeRefsCreated += changed.codeRefs;
+        }
+      } catch (err) {
+        result.errors.push(`${relPath}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    const removedFromDeleted = this.removeDeletedFiles(files);
+    result.sectionsRemoved += removedFromDeleted;
+    if (this.config.enableEmbeddings) {
+      try {
+        opts?.onProgress?.("docs: embedding sections");
+        const vectorMgr = new import_vectors.DocsVectorManager(this.config, this.db);
+        const allSections = this.db.all("SELECT * FROM doc_sections ORDER BY file_path, position");
+        const sections = allSections.map((row) => ({
+          id: row.id,
+          filePath: row.file_path,
+          title: row.title,
+          level: row.level,
+          parentId: row.parent_id ?? null,
+          summary: row.summary ?? null,
+          byteStart: row.byte_start,
+          byteEnd: row.byte_end,
+          contentHash: row.content_hash,
+          tags: row.tags ? JSON.parse(row.tags) : [],
+          position: row.position,
+          updatedAt: row.updated_at
+        }));
+        await vectorMgr.embedBatch(sections);
+      } catch {
+      }
+    }
+    result.duration = Date.now() - start;
+    return result;
+  }
+  /**
+   * Index a single file. Returns null if unchanged (hash match).
+   */
+  async indexFile(relPath, force = false) {
+    const absPath = path.join(this.projectRoot, relPath);
+    if (!fs.existsSync(absPath)) return null;
+    const stat = fs.statSync(absPath);
+    if (stat.size > this.config.docsMaxFileSize) return null;
+    const content = fs.readFileSync(absPath, "utf8");
+    const fileHash = crypto.createHash("sha256").update(content).digest("hex");
+    if (!force) {
+      const existing = this.db.get(
+        "SELECT content_hash FROM doc_sections WHERE file_path = ? LIMIT 1",
+        [relPath]
+      );
+      if (existing) {
+        const allSections = this.db.all(
+          "SELECT content_hash FROM doc_sections WHERE file_path = ?",
+          [relPath]
+        );
+        const firstSection = this.db.get(
+          "SELECT tags FROM doc_sections WHERE file_path = ? AND parent_id IS NULL LIMIT 1",
+          [relPath]
+        );
+        if (firstSection?.tags) {
+          try {
+            const tags = JSON.parse(firstSection.tags);
+            if (tags._fileHash === fileHash) return null;
+          } catch {
+          }
+        }
+      }
+    }
+    const parseResult = (0, import_formats.parseDocFile)(content, relPath);
+    if (!parseResult) return null;
+    const flatSections = this.flattenSections(parseResult.sections, relPath, fileHash);
+    const existingIds = new Set(
+      this.db.all("SELECT id FROM doc_sections WHERE file_path = ?", [relPath]).map((r) => r.id)
+    );
+    let created = 0;
+    let updated = 0;
+    let codeRefsCount = 0;
+    this.db.run("BEGIN");
+    try {
+      for (const section of flatSections) {
+        if (existingIds.has(section.id)) {
+          this.db.run(`
+            UPDATE doc_sections SET
+              title = ?, level = ?, parent_id = ?, summary = ?,
+              byte_start = ?, byte_end = ?, content_hash = ?,
+              tags = ?, position = ?, updated_at = ?
+            WHERE id = ?
+          `, [
+            section.title,
+            section.level,
+            section.parentId,
+            section.summary,
+            section.byteStart,
+            section.byteEnd,
+            section.contentHash,
+            JSON.stringify(section.tags),
+            section.position,
+            section.updatedAt,
+            section.id
+          ]);
+          existingIds.delete(section.id);
+          updated++;
+        } else {
+          this.db.run(`
+            INSERT INTO doc_sections (id, file_path, title, level, parent_id, summary, byte_start, byte_end, content_hash, tags, position, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `, [
+            section.id,
+            section.filePath,
+            section.title,
+            section.level,
+            section.parentId,
+            section.summary,
+            section.byteStart,
+            section.byteEnd,
+            section.contentHash,
+            JSON.stringify(section.tags),
+            section.position,
+            section.updatedAt
+          ]);
+          created++;
+        }
+        this.db.run("INSERT OR REPLACE INTO doc_sections_fts (id, title, summary) VALUES (?, ?, ?)", [
+          section.id,
+          section.title,
+          section.summary ?? ""
+        ]);
+      }
+      for (const staleId of existingIds) {
+        this.db.run("DELETE FROM doc_sections WHERE id = ?", [staleId]);
+        this.db.run("DELETE FROM doc_sections_fts WHERE id = ?", [staleId]);
+        this.db.run("DELETE FROM doc_code_refs WHERE section_id = ?", [staleId]);
+      }
+      if (this.config.docsLinkCode) {
+        for (const section of flatSections) {
+          const sectionContent = Buffer.from(content, "utf8").slice(section.byteStart, section.byteEnd).toString("utf8");
+          const refs = (0, import_linker.linkSection)(section.id, sectionContent, this.db);
+          this.db.run("DELETE FROM doc_code_refs WHERE section_id = ?", [section.id]);
+          for (const ref of refs) {
+            this.db.run(
+              "INSERT OR REPLACE INTO doc_code_refs (section_id, qualified_name, ref_type, confidence) VALUES (?, ?, ?, ?)",
+              [ref.sectionId, ref.qualifiedName, ref.refType, ref.confidence]
+            );
+            codeRefsCount++;
+          }
+        }
+      }
+      this.db.run("COMMIT");
+    } catch (err) {
+      this.db.run("ROLLBACK");
+      throw err;
+    }
+    return { created, updated, removed: existingIds.size, codeRefs: codeRefsCount };
+  }
+  // ── Private ─────────────────────────────────────────────────────────────────
+  /**
+   * Scan the project for documentation files matching include/exclude patterns.
+   */
+  scanDocFiles() {
+    const includeMatchers = this.config.docsInclude.map((p) => (0, import_picomatch.default)(p));
+    const excludeMatchers = this.config.docsExclude.map((p) => (0, import_picomatch.default)(p));
+    const results = [];
+    const walk = (dir) => {
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        const rel = path.relative(this.projectRoot, full).replace(/\\/g, "/");
+        if (entry.isDirectory()) {
+          if (excludeMatchers.some((m) => m(rel + "/"))) continue;
+          walk(full);
+        } else if (entry.isFile()) {
+          if (excludeMatchers.some((m) => m(rel))) continue;
+          if (includeMatchers.some((m) => m(rel))) {
+            results.push(rel);
+          }
+        }
+      }
+    };
+    walk(this.projectRoot);
+    return results;
+  }
+  /**
+   * Flatten a parsed section tree into a flat array of DocSection objects.
+   */
+  flattenSections(sections, filePath, fileHash) {
+    const flat = [];
+    const now = Date.now();
+    const walk = (nodes, parentId, ancestorSlugs) => {
+      for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        const id = (0, import_section_id.generateSectionId)(filePath, ancestorSlugs, node.title, node.level);
+        const contentHash = crypto.createHash("sha256").update(node.content).digest("hex");
+        const summary = this.extractFirstSentence(node.content, node.title);
+        const tags = [];
+        if (parentId === null && i === 0) {
+          tags._fileHash = fileHash;
+        }
+        flat.push({
+          id,
+          filePath,
+          title: node.title,
+          level: node.level,
+          parentId,
+          summary,
+          byteStart: node.byteStart,
+          byteEnd: node.byteEnd,
+          contentHash,
+          tags: parentId === null && i === 0 ? [JSON.stringify({ _fileHash: fileHash })] : tags,
+          position: i,
+          updatedAt: now
+        });
+        if (node.children.length > 0) {
+          const currentSlug = (0, import_section_id.slugify)(node.title);
+          walk(node.children, id, [...ancestorSlugs, currentSlug]);
+        }
+      }
+    };
+    walk(sections, null, []);
+    return flat;
+  }
+  /**
+   * Extract the first meaningful sentence from section content.
+   * Skips the heading line itself.
+   */
+  extractFirstSentence(content, title) {
+    const lines = content.split("\n");
+    const bodyLines = lines.filter((l) => {
+      const trimmed = l.trim();
+      if (trimmed === "" || trimmed.startsWith("#") || trimmed.startsWith("```") || trimmed.startsWith("~~~")) return false;
+      if (/^[=-]+\s*$/.test(trimmed)) return false;
+      return true;
+    });
+    if (bodyLines.length === 0) return null;
+    const firstLine = bodyLines[0].trim();
+    const sentenceEnd = firstLine.search(/[.!?]\s|[.!?]$/);
+    if (sentenceEnd > 0) {
+      return firstLine.slice(0, sentenceEnd + 1).trim();
+    }
+    return firstLine.length > 200 ? firstLine.slice(0, 200) + "\u2026" : firstLine;
+  }
+  /**
+   * Remove sections for files that no longer exist on disk.
+   */
+  removeDeletedFiles(currentFiles) {
+    const currentSet = new Set(currentFiles);
+    const indexedFiles = this.db.all("SELECT DISTINCT file_path FROM doc_sections").map((r) => r.file_path);
+    let removed = 0;
+    for (const filePath of indexedFiles) {
+      if (!currentSet.has(filePath)) {
+        const count = this.db.get("SELECT COUNT(*) as cnt FROM doc_sections WHERE file_path = ?", [filePath])?.cnt ?? 0;
+        this.db.run("DELETE FROM doc_sections WHERE file_path = ?", [filePath]);
+        this.db.run("DELETE FROM doc_sections_fts WHERE id IN (SELECT id FROM doc_sections WHERE file_path = ?)", [filePath]);
+        this.db.run("DELETE FROM doc_code_refs WHERE section_id IN (SELECT id FROM doc_sections WHERE file_path = ?)", [filePath]);
+        removed += count;
+      }
+    }
+    return removed;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocsIndexer
+});
+//# sourceMappingURL=indexer.js.map

package/dist/docs/indexer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/indexer.ts"],
+  "sourcesContent": ["/**\n * Documentation Indexer\n *\n * Orchestrates: scan doc files \u2192 parse sections \u2192 persist to DB.\n * Supports incremental re-indexing via content hashes.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as crypto from 'crypto';\nimport picomatch from 'picomatch';\nimport type { KiroGraphConfig } from '../config';\nimport type { DocSection, ParsedSection, DocIndexResult } from './types';\nimport { generateSectionId, slugify } from './section-id';\nimport { parseDocFile } from './formats/index';\nimport { linkSection } from './linker';\nimport { DocsVectorManager } from './vectors';\n\n// \u2500\u2500 Public API \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport class DocsIndexer {\n  private readonly db: any; // raw sqlite db handle\n  private readonly config: KiroGraphConfig;\n  private readonly projectRoot: string;\n\n  constructor(db: any, config: KiroGraphConfig, projectRoot: string) {\n    this.db = db;\n    this.config = config;\n    this.projectRoot = projectRoot;\n  }\n\n  /**\n   * Index all documentation files in the project.\n   * Skips files whose content hash hasn't changed (incremental).\n   */\n  async indexAll(opts?: { force?: boolean; onProgress?: (msg: string) => void }): Promise<DocIndexResult> {\n    const start = Date.now();\n    const result: DocIndexResult = {\n      filesIndexed: 0, sectionsCreated: 0, sectionsUpdated: 0,\n      sectionsRemoved: 0, codeRefsCreated: 0, errors: [], duration: 0,\n    };\n\n    const files = this.scanDocFiles();\n    opts?.onProgress?.(`docs: found ${files.length} documentation files`);\n\n    for (const relPath of files) {\n      try {\n        const changed = await this.indexFile(relPath, opts?.force ?? false);\n        if (changed) {\n          result.filesIndexed++;\n          result.sectionsCreated += changed.created;\n          result.sectionsUpdated += changed.updated;\n          result.sectionsRemoved += changed.removed;\n          result.codeRefsCreated += changed.codeRefs;\n        }\n      } catch (err) {\n        result.errors.push(`${relPath}: ${err instanceof Error ? err.message : String(err)}`);\n      }\n    }\n\n    // Remove sections for files that no longer exist\n    const removedFromDeleted = this.removeDeletedFiles(files);\n    result.sectionsRemoved += removedFromDeleted;\n\n    // Embed all sections (if embeddings enabled)\n    if (this.config.enableEmbeddings) {\n      try {\n        opts?.onProgress?.('docs: embedding sections');\n        const vectorMgr = new DocsVectorManager(this.config, this.db);\n        const allSections = this.db.all('SELECT * FROM doc_sections ORDER BY file_path, position') as any[];\n        const sections: DocSection[] = allSections.map((row: any) => ({\n          id: row.id,\n          filePath: row.file_path,\n          title: row.title,\n          level: row.level,\n          parentId: row.parent_id ?? null,\n          summary: row.summary ?? null,\n          byteStart: row.byte_start,\n          byteEnd: row.byte_end,\n          contentHash: row.content_hash,\n          tags: row.tags ? JSON.parse(row.tags) : [],\n          position: row.position,\n          updatedAt: row.updated_at,\n        }));\n        await vectorMgr.embedBatch(sections);\n      } catch { /* embedding is non-critical */ }\n    }\n\n    result.duration = Date.now() - start;\n    return result;\n  }\n\n  /**\n   * Index a single file. Returns null if unchanged (hash match).\n   */\n  async indexFile(relPath: string, force = false): Promise<{ created: number; updated: number; removed: number; codeRefs: number } | null> {\n    const absPath = path.join(this.projectRoot, relPath);\n    if (!fs.existsSync(absPath)) return null;\n\n    const stat = fs.statSync(absPath);\n    if (stat.size > this.config.docsMaxFileSize) return null;\n\n    const content = fs.readFileSync(absPath, 'utf8');\n    const fileHash = crypto.createHash('sha256').update(content).digest('hex');\n\n    // Check if file has changed (skip if hash matches and not forced)\n    if (!force) {\n      const existing = this.db.get(\n        'SELECT content_hash FROM doc_sections WHERE file_path = ? LIMIT 1',\n        [relPath]\n      );\n      // If any section exists with same file and we can verify the file hasn't changed\n      if (existing) {\n        const allSections = this.db.all(\n          'SELECT content_hash FROM doc_sections WHERE file_path = ?',\n          [relPath]\n        );\n        // Use a file-level hash stored as a tag on the first section\n        const firstSection = this.db.get(\n          \"SELECT tags FROM doc_sections WHERE file_path = ? AND parent_id IS NULL LIMIT 1\",\n          [relPath]\n        );\n        if (firstSection?.tags) {\n          try {\n            const tags = JSON.parse(firstSection.tags);\n            if (tags._fileHash === fileHash) return null; // unchanged\n          } catch { /* proceed with re-index */ }\n        }\n      }\n    }\n\n    // Parse the file\n    const parseResult = parseDocFile(content, relPath);\n    if (!parseResult) return null;\n\n    // Flatten sections and generate IDs\n    const flatSections = this.flattenSections(parseResult.sections, relPath, fileHash);\n\n    // Get existing section IDs for this file\n    const existingIds = new Set<string>(\n      (this.db.all('SELECT id FROM doc_sections WHERE file_path = ?', [relPath]) as Array<{ id: string }>)\n        .map(r => r.id)\n    );\n\n    let created = 0;\n    let updated = 0;\n    let codeRefsCount = 0;\n\n    // Upsert sections in a transaction\n    this.db.run('BEGIN');\n    try {\n      for (const section of flatSections) {\n        if (existingIds.has(section.id)) {\n          // Update existing\n          this.db.run(`\n            UPDATE doc_sections SET\n              title = ?, level = ?, parent_id = ?, summary = ?,\n              byte_start = ?, byte_end = ?, content_hash = ?,\n              tags = ?, position = ?, updated_at = ?\n            WHERE id = ?\n          `, [\n            section.title, section.level, section.parentId, section.summary,\n            section.byteStart, section.byteEnd, section.contentHash,\n            JSON.stringify(section.tags), section.position, section.updatedAt,\n            section.id,\n          ]);\n          existingIds.delete(section.id);\n          updated++;\n        } else {\n          // Insert new\n          this.db.run(`\n            INSERT INTO doc_sections (id, file_path, title, level, parent_id, summary, byte_start, byte_end, content_hash, tags, position, updated_at)\n            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n          `, [\n            section.id, section.filePath, section.title, section.level,\n            section.parentId, section.summary, section.byteStart, section.byteEnd,\n            section.contentHash, JSON.stringify(section.tags), section.position, section.updatedAt,\n          ]);\n          created++;\n        }\n\n        // Update FTS\n        this.db.run('INSERT OR REPLACE INTO doc_sections_fts (id, title, summary) VALUES (?, ?, ?)', [\n          section.id, section.title, section.summary ?? '',\n        ]);\n      }\n\n      // Remove sections that no longer exist in the file\n      for (const staleId of existingIds) {\n        this.db.run('DELETE FROM doc_sections WHERE id = ?', [staleId]);\n        this.db.run('DELETE FROM doc_sections_fts WHERE id = ?', [staleId]);\n        this.db.run('DELETE FROM doc_code_refs WHERE section_id = ?', [staleId]);\n      }\n\n      // Run code linker if enabled\n      if (this.config.docsLinkCode) {\n        for (const section of flatSections) {\n          // Read section content for linking\n          const sectionContent = Buffer.from(content, 'utf8')\n            .slice(section.byteStart, section.byteEnd).toString('utf8');\n          const refs = linkSection(section.id, sectionContent, this.db);\n          // Clear old refs for this section and insert new ones\n          this.db.run('DELETE FROM doc_code_refs WHERE section_id = ?', [section.id]);\n          for (const ref of refs) {\n            this.db.run(\n              'INSERT OR REPLACE INTO doc_code_refs (section_id, qualified_name, ref_type, confidence) VALUES (?, ?, ?, ?)',\n              [ref.sectionId, ref.qualifiedName, ref.refType, ref.confidence],\n            );\n            codeRefsCount++;\n          }\n        }\n      }\n\n      this.db.run('COMMIT');\n    } catch (err) {\n      this.db.run('ROLLBACK');\n      throw err;\n    }\n\n    return { created, updated, removed: existingIds.size, codeRefs: codeRefsCount };\n  }\n\n  // \u2500\u2500 Private \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n  /**\n   * Scan the project for documentation files matching include/exclude patterns.\n   */\n  private scanDocFiles(): string[] {\n    const includeMatchers = this.config.docsInclude.map(p => picomatch(p));\n    const excludeMatchers = this.config.docsExclude.map(p => picomatch(p));\n    const results: string[] = [];\n\n    const walk = (dir: string) => {\n      let entries: fs.Dirent[];\n      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }\n\n      for (const entry of entries) {\n        const full = path.join(dir, entry.name);\n        const rel = path.relative(this.projectRoot, full).replace(/\\\\/g, '/');\n\n        if (entry.isDirectory()) {\n          // Skip excluded directories early\n          if (excludeMatchers.some(m => m(rel + '/'))) continue;\n          walk(full);\n        } else if (entry.isFile()) {\n          // Check exclude first\n          if (excludeMatchers.some(m => m(rel))) continue;\n          // Check include\n          if (includeMatchers.some(m => m(rel))) {\n            results.push(rel);\n          }\n        }\n      }\n    };\n\n    walk(this.projectRoot);\n    return results;\n  }\n\n  /**\n   * Flatten a parsed section tree into a flat array of DocSection objects.\n   */\n  private flattenSections(\n    sections: ParsedSection[],\n    filePath: string,\n    fileHash: string,\n  ): DocSection[] {\n    const flat: DocSection[] = [];\n    const now = Date.now();\n\n    const walk = (nodes: ParsedSection[], parentId: string | null, ancestorSlugs: string[]) => {\n      for (let i = 0; i < nodes.length; i++) {\n        const node = nodes[i];\n        const id = generateSectionId(filePath, ancestorSlugs, node.title, node.level);\n        const contentHash = crypto.createHash('sha256').update(node.content).digest('hex');\n        const summary = this.extractFirstSentence(node.content, node.title);\n\n        // Store file hash in tags of root-level sections for incremental detection\n        const tags: string[] = [];\n        if (parentId === null && i === 0) {\n          (tags as any)._fileHash = fileHash;\n        }\n\n        flat.push({\n          id,\n          filePath,\n          title: node.title,\n          level: node.level,\n          parentId,\n          summary,\n          byteStart: node.byteStart,\n          byteEnd: node.byteEnd,\n          contentHash,\n          tags: parentId === null && i === 0 ? [JSON.stringify({ _fileHash: fileHash })] : tags,\n          position: i,\n          updatedAt: now,\n        });\n\n        if (node.children.length > 0) {\n          const currentSlug = slugify(node.title);\n          walk(node.children, id, [...ancestorSlugs, currentSlug]);\n        }\n      }\n    };\n\n    walk(sections, null, []);\n    return flat;\n  }\n\n  /**\n   * Extract the first meaningful sentence from section content.\n   * Skips the heading line itself.\n   */\n  private extractFirstSentence(content: string, title: string): string | null {\n    // Remove the heading line\n    const lines = content.split('\\n');\n    const bodyLines = lines.filter(l => {\n      const trimmed = l.trim();\n      // Skip heading lines, empty lines, and code fence markers\n      if (trimmed === '' || trimmed.startsWith('#') || trimmed.startsWith('```') || trimmed.startsWith('~~~')) return false;\n      // Skip setext underlines\n      if (/^[=-]+\\s*$/.test(trimmed)) return false;\n      return true;\n    });\n\n    if (bodyLines.length === 0) return null;\n\n    // Take first non-empty line, truncate at sentence boundary\n    const firstLine = bodyLines[0].trim();\n    const sentenceEnd = firstLine.search(/[.!?]\\s|[.!?]$/);\n    if (sentenceEnd > 0) {\n      return firstLine.slice(0, sentenceEnd + 1).trim();\n    }\n\n    // No sentence boundary \u2014 take the whole first line (truncated)\n    return firstLine.length > 200 ? firstLine.slice(0, 200) + '\u2026' : firstLine;\n  }\n\n  /**\n   * Remove sections for files that no longer exist on disk.\n   */\n  private removeDeletedFiles(currentFiles: string[]): number {\n    const currentSet = new Set(currentFiles);\n    const indexedFiles = (this.db.all('SELECT DISTINCT file_path FROM doc_sections') as Array<{ file_path: string }>)\n      .map(r => r.file_path);\n\n    let removed = 0;\n    for (const filePath of indexedFiles) {\n      if (!currentSet.has(filePath)) {\n        const count = this.db.get('SELECT COUNT(*) as cnt FROM doc_sections WHERE file_path = ?', [filePath])?.cnt ?? 0;\n        this.db.run('DELETE FROM doc_sections WHERE file_path = ?', [filePath]);\n        this.db.run('DELETE FROM doc_sections_fts WHERE id IN (SELECT id FROM doc_sections WHERE file_path = ?)', [filePath]);\n        this.db.run('DELETE FROM doc_code_refs WHERE section_id IN (SELECT id FROM doc_sections WHERE file_path = ?)', [filePath]);\n        removed += count;\n      }\n    }\n\n    return removed;\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["picomatch"]
+}

package/dist/docs/linker.js

@@ -0,0 +1,151 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var linker_exports = {};
+__export(linker_exports, {
+  extractCandidateRefs: () => extractCandidateRefs,
+  linkSection: () => linkSection,
+  resolveCodeRefs: () => resolveCodeRefs
+});
+module.exports = __toCommonJS(linker_exports);
+const BACKTICK_RE = /`([^`\n]+)`/g;
+const IDENTIFIER_RE = /\b([A-Z][a-zA-Z0-9]+(?:\.[a-zA-Z][a-zA-Z0-9]*)?)\b/g;
+const SNAKE_CASE_RE = /\b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\b/g;
+const IMPORT_PATH_RE = /(?:from|import)\s+['"]([^'"]+)['"]/g;
+const IGNORE_WORDS = /* @__PURE__ */ new Set([
+  "TODO",
+  "NOTE",
+  "FIXME",
+  "HACK",
+  "WARNING",
+  "IMPORTANT",
+  "DEPRECATED",
+  "README",
+  "LICENSE",
+  "CHANGELOG",
+  "CONTRIBUTING",
+  "HTTP",
+  "HTTPS",
+  "JSON",
+  "HTML",
+  "CSS",
+  "SQL",
+  "API",
+  "REST",
+  "CRUD",
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+  "PATCH",
+  "HEAD",
+  "OPTIONS",
+  "String",
+  "Number",
+  "Boolean",
+  "Object",
+  "Array",
+  "Function",
+  "Promise",
+  "Error",
+  "Date",
+  "Map",
+  "Set",
+  "RegExp",
+  "Buffer",
+  "Symbol",
+  "True",
+  "False",
+  "None",
+  "Null",
+  "Undefined",
+  "This",
+  "Self",
+  "Super",
+  "Class",
+  "Interface",
+  "Type"
+]);
+function extractCandidateRefs(content) {
+  const candidates = /* @__PURE__ */ new Set();
+  let match;
+  BACKTICK_RE.lastIndex = 0;
+  while ((match = BACKTICK_RE.exec(content)) !== null) {
+    const ref = match[1].trim();
+    if (ref.includes(" ") || ref.startsWith("/") || ref.startsWith("http") || ref.startsWith("$")) continue;
+    if (ref.includes(".")) {
+      const parts = ref.split(".");
+      for (const part of parts) {
+        if (part.length >= 2 && !IGNORE_WORDS.has(part)) candidates.add(part);
+      }
+    }
+    if (ref.length >= 2 && !IGNORE_WORDS.has(ref)) candidates.add(ref);
+  }
+  IDENTIFIER_RE.lastIndex = 0;
+  while ((match = IDENTIFIER_RE.exec(content)) !== null) {
+    const ref = match[1];
+    if (!IGNORE_WORDS.has(ref) && ref.length >= 3) {
+      candidates.add(ref);
+    }
+  }
+  SNAKE_CASE_RE.lastIndex = 0;
+  while ((match = SNAKE_CASE_RE.exec(content)) !== null) {
+    const ref = match[1];
+    if (ref.length >= 4) candidates.add(ref);
+  }
+  return [...candidates];
+}
+function resolveCodeRefs(sectionId, candidates, db) {
+  if (candidates.length === 0) return [];
+  const refs = [];
+  const seen = /* @__PURE__ */ new Set();
+  const CHUNK_SIZE = 50;
+  for (let i = 0; i < candidates.length; i += CHUNK_SIZE) {
+    const chunk = candidates.slice(i, i + CHUNK_SIZE);
+    const placeholders = chunk.map(() => "?").join(",");
+    const rows = db.all(
+      `SELECT name, qualified_name FROM nodes WHERE name IN (${placeholders}) GROUP BY qualified_name`,
+      chunk
+    );
+    for (const row of rows) {
+      const key = `${sectionId}:${row.qualified_name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const refType = "mentions";
+      const confidence = chunk.includes(row.name) ? 0.8 : 0.6;
+      refs.push({
+        sectionId,
+        qualifiedName: row.qualified_name,
+        refType,
+        confidence
+      });
+    }
+  }
+  return refs;
+}
+function linkSection(sectionId, content, db) {
+  const candidates = extractCandidateRefs(content);
+  return resolveCodeRefs(sectionId, candidates, db);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  extractCandidateRefs,
+  linkSection,
+  resolveCodeRefs
+});
+//# sourceMappingURL=linker.js.map

package/dist/docs/linker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/linker.ts"],
+  "sourcesContent": ["/**\n * Code \u2194 Documentation Linker\n *\n * Detects references to code symbols within documentation sections.\n * Strategies:\n *   1. Backtick references: `functionName`, `ClassName.method`\n *   2. Import-style paths: from './auth/service'\n *   3. Identifier patterns: CamelCase, snake_case words that match indexed symbols\n */\n\nimport type { DocCodeRef, DocRefType } from './types';\n\n// \u2500\u2500 Patterns \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n// Backtick-wrapped code references\nconst BACKTICK_RE = /`([^`\\n]+)`/g;\n\n// Common identifier patterns (CamelCase, snake_case, SCREAMING_SNAKE)\nconst IDENTIFIER_RE = /\\b([A-Z][a-zA-Z0-9]+(?:\\.[a-zA-Z][a-zA-Z0-9]*)?)\\b/g;\nconst SNAKE_CASE_RE = /\\b([a-z][a-z0-9]*(?:_[a-z0-9]+)+)\\b/g;\n\n// Import-style paths\nconst IMPORT_PATH_RE = /(?:from|import)\\s+['\"]([^'\"]+)['\"]/g;\n\n// Words to ignore (too common to be meaningful symbol references)\nconst IGNORE_WORDS = new Set([\n  'TODO', 'NOTE', 'FIXME', 'HACK', 'WARNING', 'IMPORTANT', 'DEPRECATED',\n  'README', 'LICENSE', 'CHANGELOG', 'CONTRIBUTING',\n  'HTTP', 'HTTPS', 'JSON', 'HTML', 'CSS', 'SQL', 'API', 'REST', 'CRUD',\n  'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',\n  'String', 'Number', 'Boolean', 'Object', 'Array', 'Function', 'Promise',\n  'Error', 'Date', 'Map', 'Set', 'RegExp', 'Buffer', 'Symbol',\n  'True', 'False', 'None', 'Null', 'Undefined',\n  'This', 'Self', 'Super', 'Class', 'Interface', 'Type',\n]);\n\n/**\n * Extract candidate symbol references from documentation content.\n * Returns unique candidate names that should be looked up against the graph.\n */\nexport function extractCandidateRefs(content: string): string[] {\n  const candidates = new Set<string>();\n\n  // 1. Backtick references (highest confidence)\n  let match: RegExpExecArray | null;\n  BACKTICK_RE.lastIndex = 0;\n  while ((match = BACKTICK_RE.exec(content)) !== null) {\n    const ref = match[1].trim();\n    // Skip if it looks like a command, path, or URL\n    if (ref.includes(' ') || ref.startsWith('/') || ref.startsWith('http') || ref.startsWith('$')) continue;\n    // Handle Class.method notation\n    if (ref.includes('.')) {\n      const parts = ref.split('.');\n      for (const part of parts) {\n        if (part.length >= 2 && !IGNORE_WORDS.has(part)) candidates.add(part);\n      }\n    }\n    if (ref.length >= 2 && !IGNORE_WORDS.has(ref)) candidates.add(ref);\n  }\n\n  // 2. CamelCase identifiers (medium confidence)\n  IDENTIFIER_RE.lastIndex = 0;\n  while ((match = IDENTIFIER_RE.exec(content)) !== null) {\n    const ref = match[1];\n    if (!IGNORE_WORDS.has(ref) && ref.length >= 3) {\n      candidates.add(ref);\n    }\n  }\n\n  // 3. snake_case identifiers (medium confidence)\n  SNAKE_CASE_RE.lastIndex = 0;\n  while ((match = SNAKE_CASE_RE.exec(content)) !== null) {\n    const ref = match[1];\n    if (ref.length >= 4) candidates.add(ref);\n  }\n\n  return [...candidates];\n}\n\n/**\n * Resolve candidate references against the code graph.\n * Returns DocCodeRef entries for symbols that actually exist in the index.\n *\n * @param sectionId - The doc section ID\n * @param candidates - Candidate symbol names extracted from the section\n * @param db - Raw SQLite database handle\n */\nexport function resolveCodeRefs(\n  sectionId: string,\n  candidates: string[],\n  db: any,\n): DocCodeRef[] {\n  if (candidates.length === 0) return [];\n\n  const refs: DocCodeRef[] = [];\n  const seen = new Set<string>();\n\n  // Batch lookup: find nodes matching any candidate name\n  // Use a chunked approach to avoid SQLite variable limits\n  const CHUNK_SIZE = 50;\n  for (let i = 0; i < candidates.length; i += CHUNK_SIZE) {\n    const chunk = candidates.slice(i, i + CHUNK_SIZE);\n    const placeholders = chunk.map(() => '?').join(',');\n    const rows = db.all(\n      `SELECT name, qualified_name FROM nodes WHERE name IN (${placeholders}) GROUP BY qualified_name`,\n      chunk,\n    ) as Array<{ name: string; qualified_name: string }>;\n\n    for (const row of rows) {\n      const key = `${sectionId}:${row.qualified_name}`;\n      if (seen.has(key)) continue;\n      seen.add(key);\n\n      // Determine ref type based on context\n      const refType: DocRefType = 'mentions';\n      const confidence = chunk.includes(row.name) ? 0.8 : 0.6;\n\n      refs.push({\n        sectionId,\n        qualifiedName: row.qualified_name,\n        refType,\n        confidence,\n      });\n    }\n  }\n\n  return refs;\n}\n\n/**\n * Run the full linking pipeline for a section.\n * Extracts candidates from content, resolves against the graph, returns refs.\n */\nexport function linkSection(\n  sectionId: string,\n  content: string,\n  db: any,\n): DocCodeRef[] {\n  const candidates = extractCandidateRefs(content);\n  return resolveCodeRefs(sectionId, candidates, db);\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/docs/lint.js

@@ -0,0 +1,92 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var lint_exports = {};
+__export(lint_exports, {
+  docsLint: () => docsLint
+});
+module.exports = __toCommonJS(lint_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
+function docsLint(db, projectRoot) {
+  const result = {
+    brokenRefs: [],
+    staleSections: [],
+    ftsDesync: null,
+    orphanRefs: 0,
+    totalIssues: 0
+  };
+  const refs = db.all(`
+    SELECT r.section_id, r.qualified_name
+    FROM doc_code_refs r
+    LEFT JOIN nodes n ON n.qualified_name = r.qualified_name
+    WHERE n.id IS NULL
+  `);
+  result.brokenRefs = refs.map((r) => ({ sectionId: r.section_id, qualifiedName: r.qualified_name }));
+  const sections = db.all(`
+    SELECT id, file_path, byte_start, byte_end, content_hash
+    FROM doc_sections
+  `);
+  for (const section of sections) {
+    const absPath = path.join(projectRoot, section.file_path);
+    try {
+      if (!fs.existsSync(absPath)) {
+        result.staleSections.push({ id: section.id, filePath: section.file_path });
+        continue;
+      }
+      const buffer = fs.readFileSync(absPath);
+      const content = buffer.slice(section.byte_start, section.byte_end).toString("utf8");
+      const hash = crypto.createHash("sha256").update(content).digest("hex");
+      if (hash !== section.content_hash) {
+        result.staleSections.push({ id: section.id, filePath: section.file_path });
+      }
+    } catch {
+      result.staleSections.push({ id: section.id, filePath: section.file_path });
+    }
+  }
+  const sectionCount = db.get("SELECT COUNT(*) as cnt FROM doc_sections")?.cnt ?? 0;
+  const ftsCount = db.get("SELECT COUNT(*) as cnt FROM doc_sections_fts")?.cnt ?? 0;
+  if (sectionCount !== ftsCount) {
+    result.ftsDesync = { sections: sectionCount, ftsRows: ftsCount };
+  }
+  const orphans = db.get(`
+    SELECT COUNT(*) as cnt
+    FROM doc_code_refs r
+    LEFT JOIN doc_sections s ON s.id = r.section_id
+    WHERE s.id IS NULL
+  `)?.cnt ?? 0;
+  result.orphanRefs = orphans;
+  result.totalIssues = result.brokenRefs.length + result.staleSections.length + (result.ftsDesync ? 1 : 0) + result.orphanRefs;
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  docsLint
+});
+//# sourceMappingURL=lint.js.map