kirograph 0.14.1 → 0.16.0

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

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": "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",
+  "names": []
+}