@vpxa/kb 0.1.1

package/packages/analyzers/dist/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Analyzer interfaces and result types.
+ */
+export interface AnalysisResult {
+    /** Formatted output (Markdown, JSON, or Mermaid) */
+    output: string;
+    /** Structured data for programmatic access */
+    data: Record<string, unknown>;
+    /** Analysis metadata */
+    meta: {
+        analyzedAt: string;
+        scope: string;
+        fileCount: number;
+        durationMs: number;
+    };
+}
+export interface AnalyzerOptions {
+    format?: 'json' | 'markdown' | 'mermaid';
+    [key: string]: unknown;
+}
+export interface IAnalyzer<TOpts extends AnalyzerOptions = AnalyzerOptions> {
+    readonly name: string;
+    analyze(rootPath: string, options?: TOpts): Promise<AnalysisResult>;
+}
+export interface StructureAnalyzerOptions extends AnalyzerOptions {
+    format?: 'json' | 'markdown';
+    maxDepth?: number;
+    /** When true, only include source code and config files (no docs, images, fonts, etc.) */
+    sourceOnly?: boolean;
+}
+export interface DependencyAnalyzerOptions extends AnalyzerOptions {
+    format?: 'json' | 'markdown' | 'mermaid';
+    maxNodes?: number;
+}
+export interface SymbolAnalyzerOptions extends AnalyzerOptions {
+    filter?: string;
+    format?: 'json' | 'markdown';
+}
+export interface DiagramOptions extends AnalyzerOptions {
+    diagramType?: 'architecture' | 'dependencies';
+    scope?: string;
+}
+export interface TreeNode {
+    name: string;
+    type: 'file' | 'directory';
+    purpose?: string;
+    language?: string;
+    size?: number;
+    children?: TreeNode[];
+}
+export interface ProjectStats {
+    totalFiles: number;
+    totalSize: number;
+    languages: Record<string, number>;
+}
+export interface ImportInfo {
+    source: string;
+    specifiers: string[];
+    filePath: string;
+    isExternal: boolean;
+    /** Confidence level based on import resolution method */
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface SymbolInfo {
+    name: string;
+    kind: 'function' | 'class' | 'interface' | 'type' | 'const' | 'enum' | 'variable' | 'method';
+    exported: boolean;
+    filePath: string;
+    line: number;
+    /** Full signature for functions/methods (parameter list + return type) */
+    signature?: string;
+}
+export interface PatternMatch {
+    pattern: string;
+    description: string;
+    locations: string[];
+    confidence: 'high' | 'medium' | 'low';
+}
+export interface EntryPoint {
+    name: string;
+    type: 'lambda-handler' | 'main' | 'bin' | 'server' | 'cli';
+    filePath: string;
+    trigger?: string;
+}
+export interface ExtractionBaselines {
+    structure?: AnalysisResult;
+    dependencies?: AnalysisResult;
+    symbols?: AnalysisResult;
+    patterns?: AnalysisResult;
+    entryPoints?: AnalysisResult;
+    diagrams?: AnalysisResult[];
+}
+export interface ExistingKnowledge {
+    categories: string[];
+    lastProduced: Record<string, string>;
+    documentCount: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/packages/analyzers/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/packages/chunker/dist/call-graph-extractor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Call-graph extractor using tree-sitter AST.
+ *
+ * Extracts function-level call sites from parsed code, producing
+ * caller→callee edges for blast-radius and dependency analysis.
+ */
+export interface CallEdge {
+    /** File containing the call */
+    callerFile: string;
+    /** Function/method making the call (or '<module>' for top-level) */
+    callerName: string;
+    /** Name of the function/method being called */
+    calleeName: string;
+    /** 1-based line number of the call site */
+    line: number;
+}
+/**
+ * Extract call edges from a source file using tree-sitter AST.
+ * Returns null if tree-sitter is unavailable or doesn't support the language.
+ */
+export declare function extractCallEdges(content: string, filePath: string): CallEdge[] | null;
+//# sourceMappingURL=call-graph-extractor.d.ts.map

package/packages/chunker/dist/call-graph-extractor.js

@@ -0,0 +1,90 @@
+import { extname } from "node:path";
+import { TreeSitterRuntime } from "./treesitter-chunker.js";
+const FUNCTION_NODE_TYPES = /* @__PURE__ */ new Set([
+  // TS/JS
+  "function_declaration",
+  "method_definition",
+  "arrow_function",
+  // Python
+  "function_definition",
+  // Go
+  "function_declaration",
+  "method_declaration",
+  // Rust
+  "function_item",
+  // Java
+  "method_declaration",
+  "constructor_declaration"
+]);
+const CALL_NODE_TYPES = /* @__PURE__ */ new Set([
+  "call_expression",
+  // TS/JS/Go/Rust
+  "new_expression",
+  // TS/JS (new Foo())
+  "call"
+  // Python
+]);
+function extractCallEdges(content, filePath) {
+  const runtime = TreeSitterRuntime.get();
+  if (!runtime) return null;
+  const ext = extname(filePath).toLowerCase();
+  if (!runtime.hasLanguage(ext)) return null;
+  const tree = runtime.parse(content, ext);
+  if (!tree) return null;
+  const edges = [];
+  const rootNode = tree.rootNode;
+  walkNode(rootNode, filePath, "<module>", edges);
+  return edges;
+}
+function walkNode(node, filePath, currentScope, edges) {
+  if (!node) return;
+  let scope = currentScope;
+  if (FUNCTION_NODE_TYPES.has(node.type)) {
+    scope = extractFunctionName(node) ?? currentScope;
+  }
+  if (CALL_NODE_TYPES.has(node.type)) {
+    const callee = extractCalleeName(node);
+    if (callee) {
+      edges.push({
+        callerFile: filePath,
+        callerName: scope,
+        calleeName: callee,
+        line: (node.startPosition?.row ?? 0) + 1
+      });
+    }
+  }
+  for (let i = 0; i < (node.childCount ?? 0); i++) {
+    const child = node.child(i);
+    if (child) walkNode(child, filePath, scope, edges);
+  }
+}
+function extractFunctionName(node) {
+  for (let i = 0; i < (node.childCount ?? 0); i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === "identifier" || child.type === "property_identifier" || child.type === "name") {
+      return child.text ?? null;
+    }
+  }
+  return null;
+}
+function extractCalleeName(node) {
+  const fn = node.childForFieldName?.("function") ?? node.child(0);
+  if (!fn) return null;
+  if (fn.type === "identifier" || fn.type === "name") {
+    return fn.text ?? null;
+  }
+  if (fn.type === "member_expression" || fn.type === "attribute") {
+    const property = fn.childForFieldName?.("property") ?? fn.childForFieldName?.("attribute");
+    return property?.text ?? null;
+  }
+  if (node.type === "new_expression") {
+    const ctor = node.child(1);
+    return ctor?.text ?? null;
+  }
+  return null;
+}
+export {
+  extractCallEdges
+};
+//# sourceMappingURL=call-graph-extractor.js.map

package/packages/chunker/dist/chunker-factory.d.ts

@@ -0,0 +1,7 @@
+import type { IChunker } from './chunker.interface.js';
+/**
+ * Create the appropriate chunker for a file extension.
+ * Prefers tree-sitter AST-based chunking when available; falls back to regex-based.
+ */
+export declare function createChunker(fileExtension: string): IChunker;
+//# sourceMappingURL=chunker-factory.d.ts.map

package/packages/chunker/dist/chunker-factory.js

@@ -0,0 +1,36 @@
+import { CodeChunker } from "./code-chunker.js";
+import { GenericChunker } from "./generic-chunker.js";
+import { MarkdownChunker } from "./markdown-chunker.js";
+import { TreeSitterChunker, TreeSitterRuntime } from "./treesitter-chunker.js";
+function createChunker(fileExtension) {
+  const ext = fileExtension.toLowerCase();
+  switch (ext) {
+    case ".md":
+    case ".mdx":
+      return new MarkdownChunker();
+    case ".ts":
+    case ".tsx":
+    case ".mts":
+    case ".cts":
+    case ".js":
+    case ".jsx":
+    case ".mjs":
+    case ".cjs":
+    case ".py":
+    case ".go":
+    case ".rs":
+    case ".java": {
+      const runtime = TreeSitterRuntime.get();
+      if (runtime?.hasLanguage(ext)) {
+        return new TreeSitterChunker(runtime);
+      }
+      return new CodeChunker();
+    }
+    default:
+      return new GenericChunker();
+  }
+}
+export {
+  createChunker
+};
+//# sourceMappingURL=chunker-factory.js.map

package/packages/chunker/dist/chunker.interface.d.ts

@@ -0,0 +1,10 @@
+import type { ChunkMetadata, RawChunk } from '@kb/core';
+/**
+ * Interface for content chunkers.
+ * Each chunker splits a specific content type into searchable chunks.
+ */
+export interface IChunker {
+    /** Split content into chunks */
+    chunk(content: string, metadata: ChunkMetadata): RawChunk[];
+}
+//# sourceMappingURL=chunker.interface.d.ts.map

package/packages/chunker/dist/chunker.interface.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunker.interface.js.map

package/packages/chunker/dist/code-chunker.d.ts

@@ -0,0 +1,14 @@
+import type { ChunkMetadata, RawChunk } from '@kb/core';
+import type { IChunker } from './chunker.interface.js';
+export declare class CodeChunker implements IChunker {
+    private readonly maxChunkSize;
+    constructor(options?: {
+        maxChunkSize?: number;
+    });
+    chunk(content: string, metadata: ChunkMetadata): RawChunk[];
+    private findDeclarationBoundaries;
+    private fallbackChunk;
+    private splitByLines;
+    private getLineNumber;
+}
+//# sourceMappingURL=code-chunker.d.ts.map

package/packages/chunker/dist/code-chunker.js

@@ -0,0 +1,134 @@
+import { CHUNK_SIZES } from "@kb/core";
+class CodeChunker {
+  maxChunkSize;
+  constructor(options) {
+    this.maxChunkSize = options?.maxChunkSize ?? CHUNK_SIZES.code.max;
+  }
+  chunk(content, metadata) {
+    const boundaries = this.findDeclarationBoundaries(content);
+    if (boundaries.length === 0) {
+      return this.fallbackChunk(content, metadata);
+    }
+    const chunks = [];
+    for (let i = 0; i < boundaries.length; i++) {
+      const start = boundaries[i].offset;
+      const end = i + 1 < boundaries.length ? boundaries[i + 1].offset : content.length;
+      let text = content.slice(start, end).trim();
+      const header = `// File: ${metadata.sourcePath}
+`;
+      text = header + text;
+      if (text.length > this.maxChunkSize) {
+        const subChunks = this.splitByLines(text, this.maxChunkSize);
+        let currentLine = this.getLineNumber(content, start);
+        for (const sub of subChunks) {
+          const subLines = sub.split("\n").length;
+          chunks.push({
+            text: sub,
+            sourcePath: metadata.sourcePath,
+            contentType: metadata.contentType,
+            chunkIndex: chunks.length,
+            totalChunks: 0,
+            startLine: currentLine,
+            endLine: currentLine + subLines - 1
+          });
+          currentLine += subLines;
+        }
+      } else {
+        const startLine = this.getLineNumber(content, start);
+        chunks.push({
+          text,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: chunks.length,
+          totalChunks: 0,
+          startLine,
+          endLine: startLine + text.split("\n").length - 1
+        });
+      }
+    }
+    if (boundaries[0].offset > 0) {
+      const preamble = content.slice(0, boundaries[0].offset).trim();
+      if (preamble.length > 0) {
+        chunks.unshift({
+          text: `// File: ${metadata.sourcePath}
+${preamble}`,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: 0,
+          totalChunks: 0,
+          startLine: 1,
+          endLine: this.getLineNumber(content, boundaries[0].offset) - 1
+        });
+      }
+    }
+    return chunks.map((c, i) => ({ ...c, chunkIndex: i, totalChunks: chunks.length }));
+  }
+  findDeclarationBoundaries(content) {
+    const pattern = /^(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|const|enum|abstract\s+class)\s+(\w+)/gm;
+    const boundaries = [];
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      const lineStart = content.lastIndexOf("\n", match.index - 1) + 1;
+      let actualStart = lineStart;
+      const beforeContent = content.slice(0, lineStart);
+      const beforeLines = beforeContent.split("\n");
+      let j = beforeLines.length - 1;
+      while (j >= 0) {
+        const line = beforeLines[j].trim();
+        if (line === "" || line.startsWith("//") || line.startsWith("*") || line.startsWith("/*") || line.startsWith("*/") || line.startsWith("@")) {
+          j--;
+        } else {
+          break;
+        }
+      }
+      if (j < beforeLines.length - 1) {
+        actualStart = beforeLines.slice(0, j + 1).join("\n").length + 1;
+      }
+      boundaries.push({
+        offset: actualStart,
+        name: match[1]
+      });
+    }
+    return boundaries;
+  }
+  fallbackChunk(content, metadata) {
+    const header = `// File: ${metadata.sourcePath}
+`;
+    return [
+      {
+        text: header + content,
+        sourcePath: metadata.sourcePath,
+        contentType: metadata.contentType,
+        chunkIndex: 0,
+        totalChunks: 1,
+        startLine: 1,
+        endLine: content.split("\n").length
+      }
+    ];
+  }
+  splitByLines(text, maxSize) {
+    const lines = text.split("\n");
+    const result = [];
+    let current = [];
+    let currentSize = 0;
+    for (const line of lines) {
+      if (currentSize + line.length + 1 > maxSize && current.length > 0) {
+        result.push(current.join("\n"));
+        current = [line];
+        currentSize = line.length;
+      } else {
+        current.push(line);
+        currentSize += line.length + 1;
+      }
+    }
+    if (current.length > 0) result.push(current.join("\n"));
+    return result;
+  }
+  getLineNumber(content, offset) {
+    return content.slice(0, offset).split("\n").length;
+  }
+}
+export {
+  CodeChunker
+};
+//# sourceMappingURL=code-chunker.js.map

package/packages/chunker/dist/generic-chunker.d.ts

@@ -0,0 +1,12 @@
+import type { ChunkMetadata, RawChunk } from '@kb/core';
+import type { IChunker } from './chunker.interface.js';
+export declare class GenericChunker implements IChunker {
+    private readonly maxChunkSize;
+    private readonly overlap;
+    constructor(options?: {
+        maxChunkSize?: number;
+        overlap?: number;
+    });
+    chunk(content: string, metadata: ChunkMetadata): RawChunk[];
+}
+//# sourceMappingURL=generic-chunker.d.ts.map

package/packages/chunker/dist/generic-chunker.js

@@ -0,0 +1,72 @@
+import { CHUNK_SIZES } from "@kb/core";
+class GenericChunker {
+  maxChunkSize;
+  overlap;
+  constructor(options) {
+    this.maxChunkSize = options?.maxChunkSize ?? CHUNK_SIZES.default.max;
+    this.overlap = options?.overlap ?? CHUNK_SIZES.default.overlap;
+  }
+  chunk(content, metadata) {
+    if (content.length <= this.maxChunkSize) {
+      return [
+        {
+          text: content,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: 0,
+          totalChunks: 1,
+          startLine: 1,
+          endLine: content.split("\n").length
+        }
+      ];
+    }
+    const lines = content.split("\n");
+    const chunks = [];
+    let currentLines = [];
+    let currentSize = 0;
+    let startLine = 1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (currentSize + line.length + 1 > this.maxChunkSize && currentLines.length > 0) {
+        chunks.push({
+          text: currentLines.join("\n"),
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: chunks.length,
+          totalChunks: 0,
+          startLine,
+          endLine: startLine + currentLines.length - 1
+        });
+        const overlapLines = [];
+        let overlapSize = 0;
+        for (let j = currentLines.length - 1; j >= 0; j--) {
+          if (overlapSize + currentLines[j].length + 1 > this.overlap) break;
+          overlapLines.unshift(currentLines[j]);
+          overlapSize += currentLines[j].length + 1;
+        }
+        startLine = startLine + currentLines.length - overlapLines.length;
+        currentLines = [...overlapLines, line];
+        currentSize = overlapSize + line.length + 1;
+      } else {
+        currentLines.push(line);
+        currentSize += line.length + 1;
+      }
+    }
+    if (currentLines.length > 0) {
+      chunks.push({
+        text: currentLines.join("\n"),
+        sourcePath: metadata.sourcePath,
+        contentType: metadata.contentType,
+        chunkIndex: chunks.length,
+        totalChunks: 0,
+        startLine,
+        endLine: startLine + currentLines.length - 1
+      });
+    }
+    return chunks.map((c, i) => ({ ...c, chunkIndex: i, totalChunks: chunks.length }));
+  }
+}
+export {
+  GenericChunker
+};
+//# sourceMappingURL=generic-chunker.js.map

package/packages/chunker/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type CallEdge, extractCallEdges } from './call-graph-extractor.js';
+export type { IChunker } from './chunker.interface.js';
+export { createChunker } from './chunker-factory.js';
+export { CodeChunker } from './code-chunker.js';
+export { GenericChunker } from './generic-chunker.js';
+export { MarkdownChunker } from './markdown-chunker.js';
+export { initializeTreeSitter, TreeSitterChunker, TreeSitterRuntime, } from './treesitter-chunker.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/chunker/dist/index.js

@@ -0,0 +1,21 @@
+import { extractCallEdges } from "./call-graph-extractor.js";
+import { createChunker } from "./chunker-factory.js";
+import { CodeChunker } from "./code-chunker.js";
+import { GenericChunker } from "./generic-chunker.js";
+import { MarkdownChunker } from "./markdown-chunker.js";
+import {
+  initializeTreeSitter,
+  TreeSitterChunker,
+  TreeSitterRuntime
+} from "./treesitter-chunker.js";
+export {
+  CodeChunker,
+  GenericChunker,
+  MarkdownChunker,
+  TreeSitterChunker,
+  TreeSitterRuntime,
+  createChunker,
+  extractCallEdges,
+  initializeTreeSitter
+};
+//# sourceMappingURL=index.js.map

package/packages/chunker/dist/markdown-chunker.d.ts

@@ -0,0 +1,14 @@
+import type { ChunkMetadata, RawChunk } from '@kb/core';
+import type { IChunker } from './chunker.interface.js';
+export declare class MarkdownChunker implements IChunker {
+    private readonly maxChunkSize;
+    private readonly minChunkSize;
+    constructor(options?: {
+        maxChunkSize?: number;
+        minChunkSize?: number;
+    });
+    chunk(content: string, metadata: ChunkMetadata): RawChunk[];
+    private splitByHeadings;
+    private splitByParagraphs;
+}
+//# sourceMappingURL=markdown-chunker.d.ts.map

package/packages/chunker/dist/markdown-chunker.js

@@ -0,0 +1,122 @@
+import { CHUNK_SIZES } from "@kb/core";
+class MarkdownChunker {
+  maxChunkSize;
+  minChunkSize;
+  constructor(options) {
+    this.maxChunkSize = options?.maxChunkSize ?? CHUNK_SIZES.markdown.max;
+    this.minChunkSize = options?.minChunkSize ?? CHUNK_SIZES.markdown.min;
+  }
+  chunk(content, metadata) {
+    const sections = this.splitByHeadings(content);
+    const chunks = [];
+    for (const section of sections) {
+      if (section.text.trim().length < this.minChunkSize) {
+        if (chunks.length > 0) {
+          const prev = chunks[chunks.length - 1];
+          prev.text += `
+
+${section.text}`;
+          prev.endLine = section.endLine;
+          continue;
+        }
+      }
+      if (section.text.length > this.maxChunkSize) {
+        const subTexts = this.splitByParagraphs(section.text, this.maxChunkSize);
+        let currentLine = section.startLine;
+        for (const sub of subTexts) {
+          const subLines = sub.split("\n").length;
+          chunks.push({
+            text: sub,
+            sourcePath: metadata.sourcePath,
+            contentType: metadata.contentType,
+            headingPath: section.headingPath,
+            chunkIndex: chunks.length,
+            totalChunks: 0,
+            // will be set below
+            startLine: currentLine,
+            endLine: currentLine + subLines - 1
+          });
+          currentLine += subLines;
+        }
+      } else {
+        chunks.push({
+          text: section.text,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          headingPath: section.headingPath,
+          chunkIndex: chunks.length,
+          totalChunks: 0,
+          startLine: section.startLine,
+          endLine: section.endLine
+        });
+      }
+    }
+    return chunks.map((c, i) => ({ ...c, chunkIndex: i, totalChunks: chunks.length }));
+  }
+  splitByHeadings(content) {
+    const lines = content.split("\n");
+    const sections = [];
+    let currentSection = null;
+    const headingStack = [];
+    let inFencedCodeBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^```/.test(lines[i])) {
+        inFencedCodeBlock = !inFencedCodeBlock;
+      }
+      const match = !inFencedCodeBlock ? lines[i].match(/^(#{1,6})\s+(.+)/) : null;
+      if (match) {
+        if (currentSection) {
+          sections.push(currentSection);
+        }
+        const level = match[1].length;
+        const title = match[2].trim();
+        while (headingStack.length >= level) {
+          headingStack.pop();
+        }
+        headingStack.push(`${"#".repeat(level)} ${title}`);
+        currentSection = {
+          text: lines[i],
+          headingPath: headingStack.join(" > "),
+          startLine: i + 1,
+          endLine: i + 1
+        };
+      } else if (currentSection) {
+        currentSection.text += `
+${lines[i]}`;
+        currentSection.endLine = i + 1;
+      } else {
+        currentSection = {
+          text: lines[i],
+          headingPath: "(intro)",
+          startLine: i + 1,
+          endLine: i + 1
+        };
+      }
+    }
+    if (currentSection) sections.push(currentSection);
+    return sections;
+  }
+  splitByParagraphs(text, maxSize) {
+    const paragraphs = text.split(/\n\n+/);
+    const result = [];
+    let current = "";
+    for (const para of paragraphs) {
+      if (`${current}
+
+${para}`.length > maxSize && current.length > 0) {
+        result.push(current.trim());
+        current = para;
+      } else {
+        current = current ? `${current}
+
+${para}` : para;
+      }
+    }
+    if (current.trim()) result.push(current.trim());
+    return result;
+  }
+}
+export {
+  MarkdownChunker
+};
+//# sourceMappingURL=markdown-chunker.js.map