kirograph 0.15.0 → 0.16.0

package/dist/docs/lint.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/lint.ts"],
+  "sourcesContent": ["/**\n * Documentation Lint\n *\n * Health checks for the docs index:\n * 1. Broken code refs \u2014 qualified_names that no longer resolve to any node\n * 2. Stale sections \u2014 sections whose content_hash doesn't match the file on disk\n * 3. FTS desync \u2014 doc_sections_fts row count doesn't match doc_sections\n * 4. Orphan refs \u2014 doc_code_refs pointing to non-existent sections\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport * as crypto from 'crypto';\n\nexport interface LintResult {\n  brokenRefs: Array<{ sectionId: string; qualifiedName: string }>;\n  staleSections: Array<{ id: string; filePath: string }>;\n  ftsDesync: { sections: number; ftsRows: number } | null;\n  orphanRefs: number;\n  totalIssues: number;\n}\n\nexport function docsLint(db: any, projectRoot: string): LintResult {\n  const result: LintResult = {\n    brokenRefs: [],\n    staleSections: [],\n    ftsDesync: null,\n    orphanRefs: 0,\n    totalIssues: 0,\n  };\n\n  // 1. Broken code refs\n  const refs = db.all(`\n    SELECT r.section_id, r.qualified_name\n    FROM doc_code_refs r\n    LEFT JOIN nodes n ON n.qualified_name = r.qualified_name\n    WHERE n.id IS NULL\n  `) as Array<{ section_id: string; qualified_name: string }>;\n  result.brokenRefs = refs.map(r => ({ sectionId: r.section_id, qualifiedName: r.qualified_name }));\n\n  // 2. Stale sections (content hash mismatch)\n  const sections = db.all(`\n    SELECT id, file_path, byte_start, byte_end, content_hash\n    FROM doc_sections\n  `) as Array<{ id: string; file_path: string; byte_start: number; byte_end: number; content_hash: string }>;\n\n  for (const section of sections) {\n    const absPath = path.join(projectRoot, section.file_path);\n    try {\n      if (!fs.existsSync(absPath)) {\n        result.staleSections.push({ id: section.id, filePath: section.file_path });\n        continue;\n      }\n      const buffer = fs.readFileSync(absPath);\n      const content = buffer.slice(section.byte_start, section.byte_end).toString('utf8');\n      const hash = crypto.createHash('sha256').update(content).digest('hex');\n      if (hash !== section.content_hash) {\n        result.staleSections.push({ id: section.id, filePath: section.file_path });\n      }\n    } catch {\n      result.staleSections.push({ id: section.id, filePath: section.file_path });\n    }\n  }\n\n  // 3. FTS desync\n  const sectionCount = db.get('SELECT COUNT(*) as cnt FROM doc_sections')?.cnt ?? 0;\n  const ftsCount = db.get('SELECT COUNT(*) as cnt FROM doc_sections_fts')?.cnt ?? 0;\n  if (sectionCount !== ftsCount) {\n    result.ftsDesync = { sections: sectionCount, ftsRows: ftsCount };\n  }\n\n  // 4. Orphan refs (pointing to non-existent sections)\n  const orphans = db.get(`\n    SELECT COUNT(*) as cnt\n    FROM doc_code_refs r\n    LEFT JOIN doc_sections s ON s.id = r.section_id\n    WHERE s.id IS NULL\n  `)?.cnt ?? 0;\n  result.orphanRefs = orphans;\n\n  result.totalIssues = result.brokenRefs.length + result.staleSections.length +\n    (result.ftsDesync ? 1 : 0) + result.orphanRefs;\n\n  return result;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,SAAoB;AACpB,WAAsB;AACtB,aAAwB;AAUjB,SAAS,SAAS,IAAS,aAAiC;AACjE,QAAM,SAAqB;AAAA,IACzB,YAAY,CAAC;AAAA,IACb,eAAe,CAAC;AAAA,IAChB,WAAW;AAAA,IACX,YAAY;AAAA,IACZ,aAAa;AAAA,EACf;AAGA,QAAM,OAAO,GAAG,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA,GAKnB;AACD,SAAO,aAAa,KAAK,IAAI,QAAM,EAAE,WAAW,EAAE,YAAY,eAAe,EAAE,eAAe,EAAE;AAGhG,QAAM,WAAW,GAAG,IAAI;AAAA;AAAA;AAAA,GAGvB;AAED,aAAW,WAAW,UAAU;AAC9B,UAAM,UAAU,KAAK,KAAK,aAAa,QAAQ,SAAS;AACxD,QAAI;AACF,UAAI,CAAC,GAAG,WAAW,OAAO,GAAG;AAC3B,eAAO,cAAc,KAAK,EAAE,IAAI,QAAQ,IAAI,UAAU,QAAQ,UAAU,CAAC;AACzE;AAAA,MACF;AACA,YAAM,SAAS,GAAG,aAAa,OAAO;AACtC,YAAM,UAAU,OAAO,MAAM,QAAQ,YAAY,QAAQ,QAAQ,EAAE,SAAS,MAAM;AAClF,YAAM,OAAO,OAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AACrE,UAAI,SAAS,QAAQ,cAAc;AACjC,eAAO,cAAc,KAAK,EAAE,IAAI,QAAQ,IAAI,UAAU,QAAQ,UAAU,CAAC;AAAA,MAC3E;AAAA,IACF,QAAQ;AACN,aAAO,cAAc,KAAK,EAAE,IAAI,QAAQ,IAAI,UAAU,QAAQ,UAAU,CAAC;AAAA,IAC3E;AAAA,EACF;AAGA,QAAM,eAAe,GAAG,IAAI,0CAA0C,GAAG,OAAO;AAChF,QAAM,WAAW,GAAG,IAAI,8CAA8C,GAAG,OAAO;AAChF,MAAI,iBAAiB,UAAU;AAC7B,WAAO,YAAY,EAAE,UAAU,cAAc,SAAS,SAAS;AAAA,EACjE;AAGA,QAAM,UAAU,GAAG,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA,GAKtB,GAAG,OAAO;AACX,SAAO,aAAa;AAEpB,SAAO,cAAc,OAAO,WAAW,SAAS,OAAO,cAAc,UAClE,OAAO,YAAY,IAAI,KAAK,OAAO;AAEtC,SAAO;AACT;",
+  "names": []
+}

package/dist/docs/queries.js

@@ -0,0 +1,295 @@
+"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 queries_exports = {};
+__export(queries_exports, {
+  DocsQueries: () => DocsQueries
+});
+module.exports = __toCommonJS(queries_exports);
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var import_vectors = require("./vectors");
+class DocsQueries {
+  constructor(db, projectRoot, config) {
+    this.db = db;
+    this.projectRoot = projectRoot;
+    this.config = config ?? null;
+  }
+  // ── TOC ─────────────────────────────────────────────────────────────────────
+  /**
+   * Get table of contents for a file or the whole project.
+   */
+  getToc(opts) {
+    const where = opts?.file ? "WHERE file_path = ?" : "";
+    const params = opts?.file ? [opts.file] : [];
+    const rows = this.db.all(`
+      SELECT id, title, level, file_path, summary, parent_id
+      FROM doc_sections
+      ${where}
+      ORDER BY file_path, position
+    `, params);
+    if (!opts?.tree) {
+      return rows.map((r) => ({
+        id: r.id,
+        title: r.title,
+        level: r.level,
+        filePath: r.file_path,
+        summary: r.summary
+      }));
+    }
+    return this.buildTocTree(rows);
+  }
+  /**
+   * Get heading hierarchy for a single document.
+   */
+  getOutline(file) {
+    return this.getToc({ file, tree: true });
+  }
+  // ── Section Retrieval ───────────────────────────────────────────────────────
+  /**
+   * Get a section by ID, optionally with context (ancestor chain + child summaries).
+   */
+  getSection(id, opts) {
+    const row = this.db.get("SELECT * FROM doc_sections WHERE id = ?", [id]);
+    if (!row) return null;
+    const section = this.rowToSection(row);
+    const content = this.readSectionContent(section);
+    if (!opts?.context) {
+      return { section, content };
+    }
+    const ancestors = [];
+    let currentParent = section.parentId;
+    while (currentParent) {
+      const parent = this.db.get("SELECT id, title, level, parent_id FROM doc_sections WHERE id = ?", [currentParent]);
+      if (!parent) break;
+      ancestors.unshift({ id: parent.id, title: parent.title, level: parent.level });
+      currentParent = parent.parent_id;
+    }
+    const childRows = this.db.all(
+      "SELECT id, title, summary FROM doc_sections WHERE parent_id = ? ORDER BY position",
+      [id]
+    );
+    return { section, content, ancestors, children: childRows };
+  }
+  // ── Search ──────────────────────────────────────────────────────────────────
+  /**
+   * Search sections by query using FTS5 + optional vector search (hybrid).
+   */
+  async searchSections(query, opts) {
+    const limit = opts?.limit ?? 10;
+    const ftsResults = this.searchFTS(query, opts?.file, limit);
+    if (this.config?.enableEmbeddings) {
+      try {
+        const vectorMgr = new import_vectors.DocsVectorManager(this.config, this.db);
+        const vectorResults = await vectorMgr.search(query, limit);
+        if (vectorResults.length > 0) {
+          const alpha = 0.5;
+          const merged = /* @__PURE__ */ new Map();
+          for (const r of ftsResults) {
+            merged.set(r.section.id, { section: r.section, score: r.score * (1 - alpha), matchType: "fts" });
+          }
+          for (const vr of vectorResults) {
+            const existing = merged.get(vr.sectionId);
+            if (existing) {
+              existing.score += vr.score * alpha;
+              existing.matchType = "semantic";
+            } else {
+              const row = this.db.get("SELECT * FROM doc_sections WHERE id = ?", [vr.sectionId]);
+              if (row) {
+                if (opts?.file && row.file_path !== opts.file) continue;
+                merged.set(vr.sectionId, {
+                  section: this.rowToSection(row),
+                  score: vr.score * alpha,
+                  matchType: "semantic"
+                });
+              }
+            }
+          }
+          const sorted = [...merged.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+          return sorted;
+        }
+      } catch {
+      }
+    }
+    return ftsResults;
+  }
+  /**
+   * FTS-only search (used internally and as fallback).
+   */
+  searchFTS(query, file, limit) {
+    const sanitized = query.replace(/[",]/g, " ").replace(/\s+/g, " ").trim();
+    if (!sanitized) return [];
+    let sql;
+    let params;
+    if (file) {
+      sql = `
+        SELECT s.*, rank
+        FROM doc_sections_fts fts
+        JOIN doc_sections s ON s.id = fts.id
+        WHERE doc_sections_fts MATCH ? AND s.file_path = ?
+        ORDER BY rank
+        LIMIT ?
+      `;
+      params = [sanitized, file, limit];
+    } else {
+      sql = `
+        SELECT s.*, rank
+        FROM doc_sections_fts fts
+        JOIN doc_sections s ON s.id = fts.id
+        WHERE doc_sections_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      `;
+      params = [sanitized, limit];
+    }
+    try {
+      const rows = this.db.all(sql, params);
+      return rows.map((row) => ({
+        section: this.rowToSection(row),
+        score: Math.abs(row.rank ?? 0),
+        matchType: "fts"
+      }));
+    } catch {
+      return this.searchFallback(sanitized, file, limit);
+    }
+  }
+  // ── Code Refs ───────────────────────────────────────────────────────────────
+  /**
+   * Get code symbols referenced by a section, or doc sections that reference a symbol.
+   */
+  getRefs(opts) {
+    if (opts.sectionId) {
+      return this.db.all(`
+        SELECT r.*, s.title as section_title
+        FROM doc_code_refs r
+        JOIN doc_sections s ON s.id = r.section_id
+        WHERE r.section_id = ?
+        ORDER BY r.confidence DESC
+      `, [opts.sectionId]).map((r) => ({
+        sectionId: r.section_id,
+        qualifiedName: r.qualified_name,
+        refType: r.ref_type,
+        confidence: r.confidence,
+        sectionTitle: r.section_title
+      }));
+    }
+    if (opts.qualifiedName) {
+      return this.db.all(`
+        SELECT r.*, s.title as section_title
+        FROM doc_code_refs r
+        JOIN doc_sections s ON s.id = r.section_id
+        WHERE r.qualified_name = ?
+        ORDER BY r.confidence DESC
+      `, [opts.qualifiedName]).map((r) => ({
+        sectionId: r.section_id,
+        qualifiedName: r.qualified_name,
+        refType: r.ref_type,
+        confidence: r.confidence,
+        sectionTitle: r.section_title
+      }));
+    }
+    return [];
+  }
+  // ── Stats ───────────────────────────────────────────────────────────────────
+  getStats() {
+    const files = this.db.get("SELECT COUNT(DISTINCT file_path) as cnt FROM doc_sections")?.cnt ?? 0;
+    const sections = this.db.get("SELECT COUNT(*) as cnt FROM doc_sections")?.cnt ?? 0;
+    const codeRefs = this.db.get("SELECT COUNT(*) as cnt FROM doc_code_refs")?.cnt ?? 0;
+    return { files, sections, codeRefs };
+  }
+  // ── Private ─────────────────────────────────────────────────────────────────
+  rowToSection(row) {
+    return {
+      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
+    };
+  }
+  readSectionContent(section) {
+    const absPath = path.join(this.projectRoot, section.filePath);
+    try {
+      const buffer = fs.readFileSync(absPath);
+      return buffer.slice(section.byteStart, section.byteEnd).toString("utf8");
+    } catch {
+      return "(file not found on disk)";
+    }
+  }
+  buildTocTree(rows) {
+    const map = /* @__PURE__ */ new Map();
+    const roots = [];
+    for (const row of rows) {
+      const entry = {
+        id: row.id,
+        title: row.title,
+        level: row.level,
+        filePath: row.file_path,
+        summary: row.summary,
+        children: []
+      };
+      map.set(row.id, entry);
+      if (!row.parent_id || !map.has(row.parent_id)) {
+        roots.push(entry);
+      } else {
+        map.get(row.parent_id).children.push(entry);
+      }
+    }
+    return roots;
+  }
+  searchFallback(query, file, limit) {
+    const pattern = `%${query}%`;
+    let sql;
+    let params;
+    if (file) {
+      sql = "SELECT * FROM doc_sections WHERE file_path = ? AND (title LIKE ? OR summary LIKE ?) LIMIT ?";
+      params = [file, pattern, pattern, limit];
+    } else {
+      sql = "SELECT * FROM doc_sections WHERE title LIKE ? OR summary LIKE ? LIMIT ?";
+      params = [pattern, pattern, limit];
+    }
+    const rows = this.db.all(sql, params);
+    return rows.map((row) => ({
+      section: this.rowToSection(row),
+      score: 1,
+      matchType: "fts"
+    }));
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DocsQueries
+});
+//# sourceMappingURL=queries.js.map

package/dist/docs/queries.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/queries.ts"],
+  "sourcesContent": ["/**\n * Documentation Queries\n *\n * Read-side helpers for MCP tools and CLI commands.\n * All methods operate on the doc_sections and doc_code_refs tables.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport type { DocSection, DocTocEntry, DocSearchResult } from './types';\nimport type { KiroGraphConfig } from '../config';\nimport { parseSectionId } from './section-id';\nimport { DocsVectorManager } from './vectors';\n\nexport class DocsQueries {\n  private readonly db: any;\n  private readonly projectRoot: string;\n  private readonly config: KiroGraphConfig | null;\n\n  constructor(db: any, projectRoot: string, config?: KiroGraphConfig) {\n    this.db = db;\n    this.projectRoot = projectRoot;\n    this.config = config ?? null;\n  }\n\n  // \u2500\u2500 TOC \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\u2500\u2500\u2500\n\n  /**\n   * Get table of contents for a file or the whole project.\n   */\n  getToc(opts?: { file?: string; tree?: boolean }): DocTocEntry[] {\n    const where = opts?.file ? 'WHERE file_path = ?' : '';\n    const params = opts?.file ? [opts.file] : [];\n\n    const rows = this.db.all(`\n      SELECT id, title, level, file_path, summary, parent_id\n      FROM doc_sections\n      ${where}\n      ORDER BY file_path, position\n    `, params) as Array<{\n      id: string; title: string; level: number;\n      file_path: string; summary: string | null; parent_id: string | null;\n    }>;\n\n    if (!opts?.tree) {\n      // Flat list\n      return rows.map(r => ({\n        id: r.id,\n        title: r.title,\n        level: r.level,\n        filePath: r.file_path,\n        summary: r.summary,\n      }));\n    }\n\n    // Build tree\n    return this.buildTocTree(rows);\n  }\n\n  /**\n   * Get heading hierarchy for a single document.\n   */\n  getOutline(file: string): DocTocEntry[] {\n    return this.getToc({ file, tree: true });\n  }\n\n  // \u2500\u2500 Section Retrieval \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   * Get a section by ID, optionally with context (ancestor chain + child summaries).\n   */\n  getSection(id: string, opts?: { context?: boolean }): {\n    section: DocSection;\n    content: string;\n    ancestors?: Array<{ id: string; title: string; level: number }>;\n    children?: Array<{ id: string; title: string; summary: string | null }>;\n  } | null {\n    const row = this.db.get('SELECT * FROM doc_sections WHERE id = ?', [id]);\n    if (!row) return null;\n\n    const section = this.rowToSection(row);\n    const content = this.readSectionContent(section);\n\n    if (!opts?.context) {\n      return { section, content };\n    }\n\n    // Build ancestor chain\n    const ancestors: Array<{ id: string; title: string; level: number }> = [];\n    let currentParent = section.parentId;\n    while (currentParent) {\n      const parent = this.db.get('SELECT id, title, level, parent_id FROM doc_sections WHERE id = ?', [currentParent]);\n      if (!parent) break;\n      ancestors.unshift({ id: parent.id, title: parent.title, level: parent.level });\n      currentParent = parent.parent_id;\n    }\n\n    // Get child summaries\n    const childRows = this.db.all(\n      'SELECT id, title, summary FROM doc_sections WHERE parent_id = ? ORDER BY position',\n      [id]\n    ) as Array<{ id: string; title: string; summary: string | null }>;\n\n    return { section, content, ancestors, children: childRows };\n  }\n\n  // \u2500\u2500 Search \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  /**\n   * Search sections by query using FTS5 + optional vector search (hybrid).\n   */\n  async searchSections(query: string, opts?: { file?: string; limit?: number }): Promise<DocSearchResult[]> {\n    const limit = opts?.limit ?? 10;\n\n    // FTS search\n    const ftsResults = this.searchFTS(query, opts?.file, limit);\n\n    // Vector search (if embeddings enabled)\n    if (this.config?.enableEmbeddings) {\n      try {\n        const vectorMgr = new DocsVectorManager(this.config, this.db);\n        const vectorResults = await vectorMgr.search(query, limit);\n\n        if (vectorResults.length > 0) {\n          // Merge FTS + vector results with alpha blend\n          const alpha = 0.5; // 0 = pure FTS, 1 = pure vector\n          const merged = new Map<string, { section: DocSection; score: number; matchType: 'fts' | 'semantic' }>();\n\n          // Add FTS results\n          for (const r of ftsResults) {\n            merged.set(r.section.id, { section: r.section, score: r.score * (1 - alpha), matchType: 'fts' });\n          }\n\n          // Add/merge vector results\n          for (const vr of vectorResults) {\n            const existing = merged.get(vr.sectionId);\n            if (existing) {\n              existing.score += vr.score * alpha;\n              existing.matchType = 'semantic'; // promoted to semantic if both match\n            } else {\n              // Fetch section from DB\n              const row = this.db.get('SELECT * FROM doc_sections WHERE id = ?', [vr.sectionId]);\n              if (row) {\n                // Filter by file if specified\n                if (opts?.file && row.file_path !== opts.file) continue;\n                merged.set(vr.sectionId, {\n                  section: this.rowToSection(row),\n                  score: vr.score * alpha,\n                  matchType: 'semantic',\n                });\n              }\n            }\n          }\n\n          // Sort by merged score, return top N\n          const sorted = [...merged.values()].sort((a, b) => b.score - a.score).slice(0, limit);\n          return sorted;\n        }\n      } catch { /* vector search is non-critical, fall through to FTS-only */ }\n    }\n\n    return ftsResults;\n  }\n\n  /**\n   * FTS-only search (used internally and as fallback).\n   */\n  private searchFTS(query: string, file: string | undefined, limit: number): DocSearchResult[] {\n\n    // Sanitize query for FTS5\n    const sanitized = query\n      .replace(/[\",]/g, ' ')\n      .replace(/\\s+/g, ' ')\n      .trim();\n\n    if (!sanitized) return [];\n\n    let sql: string;\n    let params: any[];\n\n    if (file) {\n      sql = `\n        SELECT s.*, rank\n        FROM doc_sections_fts fts\n        JOIN doc_sections s ON s.id = fts.id\n        WHERE doc_sections_fts MATCH ? AND s.file_path = ?\n        ORDER BY rank\n        LIMIT ?\n      `;\n      params = [sanitized, file, limit];\n    } else {\n      sql = `\n        SELECT s.*, rank\n        FROM doc_sections_fts fts\n        JOIN doc_sections s ON s.id = fts.id\n        WHERE doc_sections_fts MATCH ?\n        ORDER BY rank\n        LIMIT ?\n      `;\n      params = [sanitized, limit];\n    }\n\n    try {\n      const rows = this.db.all(sql, params) as any[];\n      return rows.map(row => ({\n        section: this.rowToSection(row),\n        score: Math.abs(row.rank ?? 0),\n        matchType: 'fts' as const,\n      }));\n    } catch {\n      // FTS query syntax error \u2014 fall back to LIKE search\n      return this.searchFallback(sanitized, file, limit);\n    }\n  }\n\n  // \u2500\u2500 Code Refs \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   * Get code symbols referenced by a section, or doc sections that reference a symbol.\n   */\n  getRefs(opts: { sectionId?: string; qualifiedName?: string }): Array<{\n    sectionId: string;\n    qualifiedName: string;\n    refType: string;\n    confidence: number;\n    sectionTitle?: string;\n  }> {\n    if (opts.sectionId) {\n      return this.db.all(`\n        SELECT r.*, s.title as section_title\n        FROM doc_code_refs r\n        JOIN doc_sections s ON s.id = r.section_id\n        WHERE r.section_id = ?\n        ORDER BY r.confidence DESC\n      `, [opts.sectionId]).map((r: any) => ({\n        sectionId: r.section_id,\n        qualifiedName: r.qualified_name,\n        refType: r.ref_type,\n        confidence: r.confidence,\n        sectionTitle: r.section_title,\n      }));\n    }\n\n    if (opts.qualifiedName) {\n      return this.db.all(`\n        SELECT r.*, s.title as section_title\n        FROM doc_code_refs r\n        JOIN doc_sections s ON s.id = r.section_id\n        WHERE r.qualified_name = ?\n        ORDER BY r.confidence DESC\n      `, [opts.qualifiedName]).map((r: any) => ({\n        sectionId: r.section_id,\n        qualifiedName: r.qualified_name,\n        refType: r.ref_type,\n        confidence: r.confidence,\n        sectionTitle: r.section_title,\n      }));\n    }\n\n    return [];\n  }\n\n  // \u2500\u2500 Stats \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\u2500\n\n  getStats(): { files: number; sections: number; codeRefs: number } {\n    const files = this.db.get('SELECT COUNT(DISTINCT file_path) as cnt FROM doc_sections')?.cnt ?? 0;\n    const sections = this.db.get('SELECT COUNT(*) as cnt FROM doc_sections')?.cnt ?? 0;\n    const codeRefs = this.db.get('SELECT COUNT(*) as cnt FROM doc_code_refs')?.cnt ?? 0;\n    return { files, sections, codeRefs };\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  private rowToSection(row: any): DocSection {\n    return {\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  }\n\n  private readSectionContent(section: DocSection): string {\n    const absPath = path.join(this.projectRoot, section.filePath);\n    try {\n      const buffer = fs.readFileSync(absPath);\n      return buffer.slice(section.byteStart, section.byteEnd).toString('utf8');\n    } catch {\n      return '(file not found on disk)';\n    }\n  }\n\n  private buildTocTree(rows: Array<{\n    id: string; title: string; level: number;\n    file_path: string; summary: string | null; parent_id: string | null;\n  }>): DocTocEntry[] {\n    const map = new Map<string, DocTocEntry>();\n    const roots: DocTocEntry[] = [];\n\n    for (const row of rows) {\n      const entry: DocTocEntry = {\n        id: row.id,\n        title: row.title,\n        level: row.level,\n        filePath: row.file_path,\n        summary: row.summary,\n        children: [],\n      };\n      map.set(row.id, entry);\n\n      if (!row.parent_id || !map.has(row.parent_id)) {\n        roots.push(entry);\n      } else {\n        map.get(row.parent_id)!.children!.push(entry);\n      }\n    }\n\n    return roots;\n  }\n\n  private searchFallback(query: string, file: string | undefined, limit: number): DocSearchResult[] {\n    const pattern = `%${query}%`;\n    let sql: string;\n    let params: any[];\n\n    if (file) {\n      sql = 'SELECT * FROM doc_sections WHERE file_path = ? AND (title LIKE ? OR summary LIKE ?) LIMIT ?';\n      params = [file, pattern, pattern, limit];\n    } else {\n      sql = 'SELECT * FROM doc_sections WHERE title LIKE ? OR summary LIKE ? LIMIT ?';\n      params = [pattern, pattern, limit];\n    }\n\n    const rows = this.db.all(sql, params) as any[];\n    return rows.map(row => ({\n      section: this.rowToSection(row),\n      score: 1.0,\n      matchType: 'fts' as const,\n    }));\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,SAAoB;AACpB,WAAsB;AAItB,qBAAkC;AAE3B,MAAM,YAAY;AAAA,EAKvB,YAAY,IAAS,aAAqB,QAA0B;AAClE,SAAK,KAAK;AACV,SAAK,cAAc;AACnB,SAAK,SAAS,UAAU;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,MAAyD;AAC9D,UAAM,QAAQ,MAAM,OAAO,wBAAwB;AACnD,UAAM,SAAS,MAAM,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;AAE3C,UAAM,OAAO,KAAK,GAAG,IAAI;AAAA;AAAA;AAAA,QAGrB,KAAK;AAAA;AAAA,OAEN,MAAM;AAKT,QAAI,CAAC,MAAM,MAAM;AAEf,aAAO,KAAK,IAAI,QAAM;AAAA,QACpB,IAAI,EAAE;AAAA,QACN,OAAO,EAAE;AAAA,QACT,OAAO,EAAE;AAAA,QACT,UAAU,EAAE;AAAA,QACZ,SAAS,EAAE;AAAA,MACb,EAAE;AAAA,IACJ;AAGA,WAAO,KAAK,aAAa,IAAI;AAAA,EAC/B;AAAA;AAAA;AAAA;AAAA,EAKA,WAAW,MAA6B;AACtC,WAAO,KAAK,OAAO,EAAE,MAAM,MAAM,KAAK,CAAC;AAAA,EACzC;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,WAAW,IAAY,MAKd;AACP,UAAM,MAAM,KAAK,GAAG,IAAI,2CAA2C,CAAC,EAAE,CAAC;AACvE,QAAI,CAAC,IAAK,QAAO;AAEjB,UAAM,UAAU,KAAK,aAAa,GAAG;AACrC,UAAM,UAAU,KAAK,mBAAmB,OAAO;AAE/C,QAAI,CAAC,MAAM,SAAS;AAClB,aAAO,EAAE,SAAS,QAAQ;AAAA,IAC5B;AAGA,UAAM,YAAiE,CAAC;AACxE,QAAI,gBAAgB,QAAQ;AAC5B,WAAO,eAAe;AACpB,YAAM,SAAS,KAAK,GAAG,IAAI,qEAAqE,CAAC,aAAa,CAAC;AAC/G,UAAI,CAAC,OAAQ;AACb,gBAAU,QAAQ,EAAE,IAAI,OAAO,IAAI,OAAO,OAAO,OAAO,OAAO,OAAO,MAAM,CAAC;AAC7E,sBAAgB,OAAO;AAAA,IACzB;AAGA,UAAM,YAAY,KAAK,GAAG;AAAA,MACxB;AAAA,MACA,CAAC,EAAE;AAAA,IACL;AAEA,WAAO,EAAE,SAAS,SAAS,WAAW,UAAU,UAAU;AAAA,EAC5D;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,eAAe,OAAe,MAAsE;AACxG,UAAM,QAAQ,MAAM,SAAS;AAG7B,UAAM,aAAa,KAAK,UAAU,OAAO,MAAM,MAAM,KAAK;AAG1D,QAAI,KAAK,QAAQ,kBAAkB;AACjC,UAAI;AACF,cAAM,YAAY,IAAI,iCAAkB,KAAK,QAAQ,KAAK,EAAE;AAC5D,cAAM,gBAAgB,MAAM,UAAU,OAAO,OAAO,KAAK;AAEzD,YAAI,cAAc,SAAS,GAAG;AAE5B,gBAAM,QAAQ;AACd,gBAAM,SAAS,oBAAI,IAAmF;AAGtG,qBAAW,KAAK,YAAY;AAC1B,mBAAO,IAAI,EAAE,QAAQ,IAAI,EAAE,SAAS,EAAE,SAAS,OAAO,EAAE,SAAS,IAAI,QAAQ,WAAW,MAAM,CAAC;AAAA,UACjG;AAGA,qBAAW,MAAM,eAAe;AAC9B,kBAAM,WAAW,OAAO,IAAI,GAAG,SAAS;AACxC,gBAAI,UAAU;AACZ,uBAAS,SAAS,GAAG,QAAQ;AAC7B,uBAAS,YAAY;AAAA,YACvB,OAAO;AAEL,oBAAM,MAAM,KAAK,GAAG,IAAI,2CAA2C,CAAC,GAAG,SAAS,CAAC;AACjF,kBAAI,KAAK;AAEP,oBAAI,MAAM,QAAQ,IAAI,cAAc,KAAK,KAAM;AAC/C,uBAAO,IAAI,GAAG,WAAW;AAAA,kBACvB,SAAS,KAAK,aAAa,GAAG;AAAA,kBAC9B,OAAO,GAAG,QAAQ;AAAA,kBAClB,WAAW;AAAA,gBACb,CAAC;AAAA,cACH;AAAA,YACF;AAAA,UACF;AAGA,gBAAM,SAAS,CAAC,GAAG,OAAO,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK;AACpF,iBAAO;AAAA,QACT;AAAA,MACF,QAAQ;AAAA,MAAgE;AAAA,IAC1E;AAEA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA,EAKQ,UAAU,OAAe,MAA0B,OAAkC;AAG3F,UAAM,YAAY,MACf,QAAQ,SAAS,GAAG,EACpB,QAAQ,QAAQ,GAAG,EACnB,KAAK;AAER,QAAI,CAAC,UAAW,QAAO,CAAC;AAExB,QAAI;AACJ,QAAI;AAEJ,QAAI,MAAM;AACR,YAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQN,eAAS,CAAC,WAAW,MAAM,KAAK;AAAA,IAClC,OAAO;AACL,YAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAQN,eAAS,CAAC,WAAW,KAAK;AAAA,IAC5B;AAEA,QAAI;AACF,YAAM,OAAO,KAAK,GAAG,IAAI,KAAK,MAAM;AACpC,aAAO,KAAK,IAAI,UAAQ;AAAA,QACtB,SAAS,KAAK,aAAa,GAAG;AAAA,QAC9B,OAAO,KAAK,IAAI,IAAI,QAAQ,CAAC;AAAA,QAC7B,WAAW;AAAA,MACb,EAAE;AAAA,IACJ,QAAQ;AAEN,aAAO,KAAK,eAAe,WAAW,MAAM,KAAK;AAAA,IACnD;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,QAAQ,MAML;AACD,QAAI,KAAK,WAAW;AAClB,aAAO,KAAK,GAAG,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAMhB,CAAC,KAAK,SAAS,CAAC,EAAE,IAAI,CAAC,OAAY;AAAA,QACpC,WAAW,EAAE;AAAA,QACb,eAAe,EAAE;AAAA,QACjB,SAAS,EAAE;AAAA,QACX,YAAY,EAAE;AAAA,QACd,cAAc,EAAE;AAAA,MAClB,EAAE;AAAA,IACJ;AAEA,QAAI,KAAK,eAAe;AACtB,aAAO,KAAK,GAAG,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAMhB,CAAC,KAAK,aAAa,CAAC,EAAE,IAAI,CAAC,OAAY;AAAA,QACxC,WAAW,EAAE;AAAA,QACb,eAAe,EAAE;AAAA,QACjB,SAAS,EAAE;AAAA,QACX,YAAY,EAAE;AAAA,QACd,cAAc,EAAE;AAAA,MAClB,EAAE;AAAA,IACJ;AAEA,WAAO,CAAC;AAAA,EACV;AAAA;AAAA,EAIA,WAAkE;AAChE,UAAM,QAAQ,KAAK,GAAG,IAAI,2DAA2D,GAAG,OAAO;AAC/F,UAAM,WAAW,KAAK,GAAG,IAAI,0CAA0C,GAAG,OAAO;AACjF,UAAM,WAAW,KAAK,GAAG,IAAI,2CAA2C,GAAG,OAAO;AAClF,WAAO,EAAE,OAAO,UAAU,SAAS;AAAA,EACrC;AAAA;AAAA,EAIQ,aAAa,KAAsB;AACzC,WAAO;AAAA,MACL,IAAI,IAAI;AAAA,MACR,UAAU,IAAI;AAAA,MACd,OAAO,IAAI;AAAA,MACX,OAAO,IAAI;AAAA,MACX,UAAU,IAAI,aAAa;AAAA,MAC3B,SAAS,IAAI,WAAW;AAAA,MACxB,WAAW,IAAI;AAAA,MACf,SAAS,IAAI;AAAA,MACb,aAAa,IAAI;AAAA,MACjB,MAAM,IAAI,OAAO,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC;AAAA,MACzC,UAAU,IAAI;AAAA,MACd,WAAW,IAAI;AAAA,IACjB;AAAA,EACF;AAAA,EAEQ,mBAAmB,SAA6B;AACtD,UAAM,UAAU,KAAK,KAAK,KAAK,aAAa,QAAQ,QAAQ;AAC5D,QAAI;AACF,YAAM,SAAS,GAAG,aAAa,OAAO;AACtC,aAAO,OAAO,MAAM,QAAQ,WAAW,QAAQ,OAAO,EAAE,SAAS,MAAM;AAAA,IACzE,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEQ,aAAa,MAGF;AACjB,UAAM,MAAM,oBAAI,IAAyB;AACzC,UAAM,QAAuB,CAAC;AAE9B,eAAW,OAAO,MAAM;AACtB,YAAM,QAAqB;AAAA,QACzB,IAAI,IAAI;AAAA,QACR,OAAO,IAAI;AAAA,QACX,OAAO,IAAI;AAAA,QACX,UAAU,IAAI;AAAA,QACd,SAAS,IAAI;AAAA,QACb,UAAU,CAAC;AAAA,MACb;AACA,UAAI,IAAI,IAAI,IAAI,KAAK;AAErB,UAAI,CAAC,IAAI,aAAa,CAAC,IAAI,IAAI,IAAI,SAAS,GAAG;AAC7C,cAAM,KAAK,KAAK;AAAA,MAClB,OAAO;AACL,YAAI,IAAI,IAAI,SAAS,EAAG,SAAU,KAAK,KAAK;AAAA,MAC9C;AAAA,IACF;AAEA,WAAO;AAAA,EACT;AAAA,EAEQ,eAAe,OAAe,MAA0B,OAAkC;AAChG,UAAM,UAAU,IAAI,KAAK;AACzB,QAAI;AACJ,QAAI;AAEJ,QAAI,MAAM;AACR,YAAM;AACN,eAAS,CAAC,MAAM,SAAS,SAAS,KAAK;AAAA,IACzC,OAAO;AACL,YAAM;AACN,eAAS,CAAC,SAAS,SAAS,KAAK;AAAA,IACnC;AAEA,UAAM,OAAO,KAAK,GAAG,IAAI,KAAK,MAAM;AACpC,WAAO,KAAK,IAAI,UAAQ;AAAA,MACtB,SAAS,KAAK,aAAa,GAAG;AAAA,MAC9B,OAAO;AAAA,MACP,WAAW;AAAA,IACb,EAAE;AAAA,EACJ;AACF;",
+  "names": []
+}

package/dist/docs/section-id.js

@@ -0,0 +1,57 @@
+"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 section_id_exports = {};
+__export(section_id_exports, {
+  buildAncestorChain: () => buildAncestorChain,
+  generateSectionId: () => generateSectionId,
+  parseSectionId: () => parseSectionId,
+  slugify: () => slugify
+});
+module.exports = __toCommonJS(section_id_exports);
+function slugify(title) {
+  return title.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "") || "untitled";
+}
+function buildAncestorChain(parentSlugs, currentSlug) {
+  return [...parentSlugs, currentSlug].join("/");
+}
+function generateSectionId(filePath, ancestorSlugs, title, level) {
+  const slug = slugify(title);
+  const chain = buildAncestorChain(ancestorSlugs, slug);
+  return `${filePath}::${chain}#${level}`;
+}
+function parseSectionId(id) {
+  const doubleColonIdx = id.indexOf("::");
+  if (doubleColonIdx === -1) return null;
+  const filePath = id.slice(0, doubleColonIdx);
+  const rest = id.slice(doubleColonIdx + 2);
+  const hashIdx = rest.lastIndexOf("#");
+  if (hashIdx === -1) return null;
+  const ancestorChain = rest.slice(0, hashIdx);
+  const level = parseInt(rest.slice(hashIdx + 1), 10);
+  if (isNaN(level) || level < 0) return null;
+  return { filePath, ancestorChain, level };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildAncestorChain,
+  generateSectionId,
+  parseSectionId,
+  slugify
+});
+//# sourceMappingURL=section-id.js.map

package/dist/docs/section-id.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/section-id.ts"],
+  "sourcesContent": ["/**\n * Stable Section ID Generation\n *\n * Format: {file_path}::{ancestor-chain/slug}#{level}\n *\n * IDs remain stable across re-indexing when:\n * - file path doesn't change\n * - heading text doesn't change\n * - heading level doesn't change\n * - parent heading chain doesn't change\n */\n\n/**\n * Convert a heading title to a URL-safe slug.\n * Matches common Markdown anchor generation (GitHub-style).\n */\nexport function slugify(title: string): string {\n  return title\n    .toLowerCase()\n    .trim()\n    // Remove special characters except spaces and hyphens\n    .replace(/[^\\w\\s-]/g, '')\n    // Replace whitespace with hyphens\n    .replace(/\\s+/g, '-')\n    // Collapse multiple hyphens\n    .replace(/-+/g, '-')\n    // Trim leading/trailing hyphens\n    .replace(/^-+|-+$/g, '')\n    // Fallback for empty result\n    || 'untitled';\n}\n\n/**\n * Build the ancestor chain string from parent slugs.\n * Example: ['installation', 'prerequisites'] \u2192 'installation/prerequisites'\n */\nexport function buildAncestorChain(parentSlugs: string[], currentSlug: string): string {\n  return [...parentSlugs, currentSlug].join('/');\n}\n\n/**\n * Generate a stable section ID.\n *\n * @param filePath - Relative path to the doc file\n * @param ancestorSlugs - Slugified titles of all ancestor headings (root \u2192 parent)\n * @param title - The heading title of this section\n * @param level - The heading level (1\u20136)\n * @returns Stable section ID string\n *\n * @example\n * generateSectionId('docs/install.md', [], 'Installation', 1)\n * // \u2192 'docs/install.md::installation#1'\n *\n * generateSectionId('docs/install.md', ['installation'], 'Prerequisites', 2)\n * // \u2192 'docs/install.md::installation/prerequisites#2'\n */\nexport function generateSectionId(\n  filePath: string,\n  ancestorSlugs: string[],\n  title: string,\n  level: number,\n): string {\n  const slug = slugify(title);\n  const chain = buildAncestorChain(ancestorSlugs, slug);\n  return `${filePath}::${chain}#${level}`;\n}\n\n/**\n * Parse a section ID back into its components.\n * Returns null if the ID is malformed.\n */\nexport function parseSectionId(id: string): {\n  filePath: string;\n  ancestorChain: string;\n  level: number;\n} | null {\n  const doubleColonIdx = id.indexOf('::');\n  if (doubleColonIdx === -1) return null;\n\n  const filePath = id.slice(0, doubleColonIdx);\n  const rest = id.slice(doubleColonIdx + 2);\n\n  const hashIdx = rest.lastIndexOf('#');\n  if (hashIdx === -1) return null;\n\n  const ancestorChain = rest.slice(0, hashIdx);\n  const level = parseInt(rest.slice(hashIdx + 1), 10);\n\n  if (isNaN(level) || level < 0) return null;\n\n  return { filePath, ancestorChain, level };\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,SAAS,QAAQ,OAAuB;AAC7C,SAAO,MACJ,YAAY,EACZ,KAAK,EAEL,QAAQ,aAAa,EAAE,EAEvB,QAAQ,QAAQ,GAAG,EAEnB,QAAQ,OAAO,GAAG,EAElB,QAAQ,YAAY,EAAE,KAEpB;AACP;AAMO,SAAS,mBAAmB,aAAuB,aAA6B;AACrF,SAAO,CAAC,GAAG,aAAa,WAAW,EAAE,KAAK,GAAG;AAC/C;AAkBO,SAAS,kBACd,UACA,eACA,OACA,OACQ;AACR,QAAM,OAAO,QAAQ,KAAK;AAC1B,QAAM,QAAQ,mBAAmB,eAAe,IAAI;AACpD,SAAO,GAAG,QAAQ,KAAK,KAAK,IAAI,KAAK;AACvC;AAMO,SAAS,eAAe,IAItB;AACP,QAAM,iBAAiB,GAAG,QAAQ,IAAI;AACtC,MAAI,mBAAmB,GAAI,QAAO;AAElC,QAAM,WAAW,GAAG,MAAM,GAAG,cAAc;AAC3C,QAAM,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAExC,QAAM,UAAU,KAAK,YAAY,GAAG;AACpC,MAAI,YAAY,GAAI,QAAO;AAE3B,QAAM,gBAAgB,KAAK,MAAM,GAAG,OAAO;AAC3C,QAAM,QAAQ,SAAS,KAAK,MAAM,UAAU,CAAC,GAAG,EAAE;AAElD,MAAI,MAAM,KAAK,KAAK,QAAQ,EAAG,QAAO;AAEtC,SAAO,EAAE,UAAU,eAAe,MAAM;AAC1C;",
+  "names": []
+}

package/dist/docs/summarizer.js

@@ -0,0 +1,55 @@
+"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 summarizer_exports = {};
+__export(summarizer_exports, {
+  summarizeSection: () => summarizeSection
+});
+module.exports = __toCommonJS(summarizer_exports);
+function summarizeSection(content, title, strategy) {
+  if (strategy === "off") return null;
+  return extractFirstSentence(content, title);
+}
+function extractFirstSentence(content, title) {
+  const lines = content.split("\n");
+  const bodyLines = lines.filter((l) => {
+    const trimmed = l.trim();
+    if (trimmed === "") return false;
+    if (trimmed.startsWith("#") || trimmed.startsWith("=") || trimmed.startsWith("*")) {
+      if (/^[#=*]+\s/.test(trimmed)) return false;
+    }
+    if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) return false;
+    if (/^[=-]+\s*$/.test(trimmed)) return false;
+    if (/^<\/?(?:h[1-6]|div|section|article|nav|header|footer)[^>]*>$/i.test(trimmed)) return false;
+    if (trimmed.toLowerCase() === title.toLowerCase()) return false;
+    return true;
+  });
+  if (bodyLines.length === 0) return null;
+  const firstLine = bodyLines[0].trim();
+  const cleaned = firstLine.replace(/^[-*•]\s+/, "").replace(/^\d+\.\s+/, "");
+  const sentenceEnd = cleaned.search(/[.!?]\s|[.!?]$/);
+  if (sentenceEnd > 0 && sentenceEnd < 200) {
+    return cleaned.slice(0, sentenceEnd + 1).trim();
+  }
+  return cleaned.length > 200 ? cleaned.slice(0, 200) + "\u2026" : cleaned;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  summarizeSection
+});
+//# sourceMappingURL=summarizer.js.map

package/dist/docs/summarizer.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/summarizer.ts"],
+  "sourcesContent": ["/**\n * Documentation Section Summarizer\n *\n * Strategies:\n * - 'first-sentence': Extract the first meaningful sentence from section content\n * - 'embedding': Use the embedding model to score sentences by relevance to heading (future)\n * - 'off': No summary, return null\n */\n\n/**\n * Extract a summary from section content based on the configured strategy.\n */\nexport function summarizeSection(\n  content: string,\n  title: string,\n  strategy: 'embedding' | 'first-sentence' | 'off',\n): string | null {\n  if (strategy === 'off') return null;\n\n  // For now, both 'embedding' and 'first-sentence' use first-sentence extraction.\n  // The 'embedding' strategy will be enhanced when vector scoring is integrated.\n  return extractFirstSentence(content, title);\n}\n\n/**\n * Extract the first meaningful sentence from section content.\n * Skips the heading line itself, code blocks, and empty lines.\n */\nfunction extractFirstSentence(content: string, title: string): string | null {\n  const lines = content.split('\\n');\n  const bodyLines = lines.filter(l => {\n    const trimmed = l.trim();\n    if (trimmed === '') return false;\n    // Skip heading markers\n    if (trimmed.startsWith('#') || trimmed.startsWith('=') || trimmed.startsWith('*')) {\n      // But only if it looks like a heading (starts with marker + space)\n      if (/^[#=*]+\\s/.test(trimmed)) return false;\n    }\n    // Skip code fence markers\n    if (trimmed.startsWith('```') || trimmed.startsWith('~~~')) return false;\n    // Skip setext underlines\n    if (/^[=-]+\\s*$/.test(trimmed)) return false;\n    // Skip HTML tags that are likely structural\n    if (/^<\\/?(?:h[1-6]|div|section|article|nav|header|footer)[^>]*>$/i.test(trimmed)) return false;\n    // Skip lines that are just the title repeated\n    if (trimmed.toLowerCase() === title.toLowerCase()) 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\n  // Strip leading list markers (-, *, 1.)\n  const cleaned = firstLine.replace(/^[-*\u2022]\\s+/, '').replace(/^\\d+\\.\\s+/, '');\n\n  const sentenceEnd = cleaned.search(/[.!?]\\s|[.!?]$/);\n  if (sentenceEnd > 0 && sentenceEnd < 200) {\n    return cleaned.slice(0, sentenceEnd + 1).trim();\n  }\n\n  // No sentence boundary \u2014 take the whole first line (truncated)\n  return cleaned.length > 200 ? cleaned.slice(0, 200) + '\u2026' : cleaned;\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAYO,SAAS,iBACd,SACA,OACA,UACe;AACf,MAAI,aAAa,MAAO,QAAO;AAI/B,SAAO,qBAAqB,SAAS,KAAK;AAC5C;AAMA,SAAS,qBAAqB,SAAiB,OAA8B;AAC3E,QAAM,QAAQ,QAAQ,MAAM,IAAI;AAChC,QAAM,YAAY,MAAM,OAAO,OAAK;AAClC,UAAM,UAAU,EAAE,KAAK;AACvB,QAAI,YAAY,GAAI,QAAO;AAE3B,QAAI,QAAQ,WAAW,GAAG,KAAK,QAAQ,WAAW,GAAG,KAAK,QAAQ,WAAW,GAAG,GAAG;AAEjF,UAAI,YAAY,KAAK,OAAO,EAAG,QAAO;AAAA,IACxC;AAEA,QAAI,QAAQ,WAAW,KAAK,KAAK,QAAQ,WAAW,KAAK,EAAG,QAAO;AAEnE,QAAI,aAAa,KAAK,OAAO,EAAG,QAAO;AAEvC,QAAI,gEAAgE,KAAK,OAAO,EAAG,QAAO;AAE1F,QAAI,QAAQ,YAAY,MAAM,MAAM,YAAY,EAAG,QAAO;AAC1D,WAAO;AAAA,EACT,CAAC;AAED,MAAI,UAAU,WAAW,EAAG,QAAO;AAGnC,QAAM,YAAY,UAAU,CAAC,EAAE,KAAK;AAGpC,QAAM,UAAU,UAAU,QAAQ,aAAa,EAAE,EAAE,QAAQ,aAAa,EAAE;AAE1E,QAAM,cAAc,QAAQ,OAAO,gBAAgB;AACnD,MAAI,cAAc,KAAK,cAAc,KAAK;AACxC,WAAO,QAAQ,MAAM,GAAG,cAAc,CAAC,EAAE,KAAK;AAAA,EAChD;AAGA,SAAO,QAAQ,SAAS,MAAM,QAAQ,MAAM,GAAG,GAAG,IAAI,WAAM;AAC9D;",
+  "names": []
+}

package/dist/docs/types.js

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 types_exports = {};
+module.exports = __toCommonJS(types_exports);
+//# sourceMappingURL=types.js.map

package/dist/docs/types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/docs/types.ts"],
+  "sourcesContent": ["/**\n * KiroGraph Documentation Module \u2014 Type Definitions\n *\n * These types model the documentation layer: sections extracted from\n * doc files, cross-references to code symbols, and search results.\n * All populated only when enableDocs=true in config.\n */\n\n// \u2500\u2500 Section \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\u2500\n\nexport interface DocSection {\n  id: string;              // stable section ID (file_path::ancestor-chain/slug#level)\n  filePath: string;        // relative path to doc file\n  title: string;           // heading text\n  level: number;           // heading depth (1\u20136, 0 for root/document-level)\n  parentId: string | null; // parent section ID (null for top-level)\n  summary: string | null;  // one-line summary (extractive or first-sentence)\n  byteStart: number;       // byte offset in original file\n  byteEnd: number;         // byte offset end\n  contentHash: string;     // SHA-256 of section content (drift detection)\n  tags: string[];          // extracted tags/refs (code refs, links, etc.)\n  position: number;        // ordering among siblings\n  updatedAt: number;       // timestamp\n}\n\n// \u2500\u2500 Code Reference \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 type DocRefType = 'mentions' | 'documents' | 'example' | 'configures';\n\nexport interface DocCodeRef {\n  sectionId: string;\n  qualifiedName: string;   // stable across reindex\n  refType: DocRefType;\n  confidence: number;      // 0.0\u20131.0\n}\n\n// \u2500\u2500 Parser Output \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 interface ParsedSection {\n  title: string;\n  level: number;\n  byteStart: number;\n  byteEnd: number;\n  content: string;         // raw content of the section (for hashing + summarization)\n  children: ParsedSection[];\n}\n\nexport interface ParseResult {\n  sections: ParsedSection[];\n  format: string;          // 'markdown' | 'rst' | 'asciidoc' | 'rdoc' | 'org' | 'html' | 'plaintext' | 'openapi'\n}\n\n// \u2500\u2500 Format Parser Interface \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 interface DocFormatParser {\n  /** Unique name for this parser (e.g. 'markdown', 'rst') */\n  name: string;\n  /** File extensions this parser handles (e.g. ['.md', '.mdx']) */\n  extensions: string[];\n  /** Parse a file's content into a section hierarchy */\n  parse(content: string, filePath: string): ParseResult;\n}\n\n// \u2500\u2500 Search \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\u2500\u2500\n\nexport interface DocSearchResult {\n  section: DocSection;\n  score: number;\n  matchType: 'fts' | 'semantic' | 'exact';\n}\n\n// \u2500\u2500 Index Result \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 interface DocIndexResult {\n  filesIndexed: number;\n  sectionsCreated: number;\n  sectionsUpdated: number;\n  sectionsRemoved: number;\n  codeRefsCreated: number;\n  errors: string[];\n  duration: number;\n}\n\n// \u2500\u2500 TOC Entry \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\nexport interface DocTocEntry {\n  id: string;\n  title: string;\n  level: number;\n  filePath: string;\n  summary: string | null;\n  children?: DocTocEntry[];\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
+  "names": []
+}