@vpxa/kb 0.1.1

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

@@ -0,0 +1,47 @@
+/**
+ * Tree-sitter AST-based code chunker.
+ *
+ * Uses native tree-sitter bindings for precise declaration boundary detection.
+ * Falls back gracefully to regex-based CodeChunker if tree-sitter or grammars
+ * are not installed (they are optional dependencies).
+ */
+import type { ChunkMetadata, RawChunk } from '@kb/core';
+import type { IChunker } from './chunker.interface.js';
+/**
+ * Singleton runtime that loads tree-sitter parser + language grammars once.
+ * Call `TreeSitterRuntime.initialize()` at startup; if it returns null,
+ * tree-sitter is not available and the factory will fall back to CodeChunker.
+ */
+export declare class TreeSitterRuntime {
+    private static instance;
+    private parser;
+    private languages;
+    static initialize(): Promise<TreeSitterRuntime | null>;
+    static get(): TreeSitterRuntime | null;
+    private init;
+    /** Parse source code with the grammar for the given file extension. */
+    parse(content: string, ext: string): any | null;
+    /** Check if a grammar is loaded for the given file extension. */
+    hasLanguage(ext: string): boolean;
+}
+/**
+ * Initialize the tree-sitter runtime. Call once at startup.
+ * Returns true if tree-sitter is available, false otherwise.
+ */
+export declare function initializeTreeSitter(): Promise<boolean>;
+/**
+ * AST-based code chunker that uses tree-sitter for precise declaration
+ * boundary detection. Produces cleaner chunks than the regex-based CodeChunker.
+ */
+export declare class TreeSitterChunker implements IChunker {
+    private readonly maxChunkSize;
+    private readonly runtime;
+    private readonly regexFallback;
+    constructor(runtime: TreeSitterRuntime, options?: {
+        maxChunkSize?: number;
+    });
+    chunk(content: string, metadata: ChunkMetadata): RawChunk[];
+    private chunkFromAst;
+    private splitByLines;
+}
+//# sourceMappingURL=treesitter-chunker.d.ts.map

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

@@ -0,0 +1,234 @@
+import { extname } from "node:path";
+import { CHUNK_SIZES } from "@kb/core";
+import { CodeChunker } from "./code-chunker.js";
+const LANGUAGE_MODULES = {
+  ".ts": { package: "tree-sitter-typescript", subLanguage: "typescript" },
+  ".tsx": { package: "tree-sitter-typescript", subLanguage: "tsx" },
+  ".mts": { package: "tree-sitter-typescript", subLanguage: "typescript" },
+  ".cts": { package: "tree-sitter-typescript", subLanguage: "typescript" },
+  ".js": { package: "tree-sitter-javascript" },
+  ".jsx": { package: "tree-sitter-javascript" },
+  ".mjs": { package: "tree-sitter-javascript" },
+  ".cjs": { package: "tree-sitter-javascript" },
+  ".py": { package: "tree-sitter-python" },
+  ".go": { package: "tree-sitter-go" },
+  ".rs": { package: "tree-sitter-rust" },
+  ".java": { package: "tree-sitter-java" }
+};
+const DECLARATION_TYPES = /* @__PURE__ */ new Set([
+  // TypeScript / JavaScript
+  "function_declaration",
+  "class_declaration",
+  "interface_declaration",
+  "type_alias_declaration",
+  "enum_declaration",
+  "lexical_declaration",
+  "export_statement",
+  "variable_declaration",
+  "abstract_class_declaration",
+  // Python
+  "function_definition",
+  "class_definition",
+  "decorated_definition",
+  // Go
+  "function_declaration",
+  "method_declaration",
+  "type_declaration",
+  // Rust
+  "function_item",
+  "impl_item",
+  "struct_item",
+  "enum_item",
+  "trait_item",
+  "mod_item",
+  "type_item",
+  // Java
+  "class_declaration",
+  "interface_declaration",
+  "method_declaration",
+  "enum_declaration"
+]);
+class TreeSitterRuntime {
+  static instance = null;
+  // biome-ignore lint/suspicious/noExplicitAny: tree-sitter parser has no published types
+  parser = null;
+  // biome-ignore lint/suspicious/noExplicitAny: tree-sitter language has no published types
+  languages = /* @__PURE__ */ new Map();
+  static async initialize() {
+    if (TreeSitterRuntime.instance) return TreeSitterRuntime.instance;
+    const runtime = new TreeSitterRuntime();
+    if (await runtime.init()) {
+      TreeSitterRuntime.instance = runtime;
+      return runtime;
+    }
+    return null;
+  }
+  static get() {
+    return TreeSitterRuntime.instance;
+  }
+  async init() {
+    try {
+      const parserMod = await import("tree-sitter");
+      const ParserClass = parserMod.default ?? parserMod;
+      this.parser = new ParserClass();
+      for (const [ext, config] of Object.entries(LANGUAGE_MODULES)) {
+        try {
+          const mod = await import(config.package);
+          const resolved = mod.default ?? mod;
+          const lang = config.subLanguage ? resolved[config.subLanguage] : resolved;
+          if (lang) this.languages.set(ext, lang);
+        } catch {
+        }
+      }
+      const loaded = this.languages.size > 0;
+      if (loaded) {
+        console.error(
+          `[KB] Tree-sitter initialized with ${this.languages.size} languages: ${[...this.languages.keys()].join(", ")}`
+        );
+      }
+      return loaded;
+    } catch {
+      return false;
+    }
+  }
+  /** Parse source code with the grammar for the given file extension. */
+  // biome-ignore lint/suspicious/noExplicitAny: tree-sitter tree has no published types
+  parse(content, ext) {
+    const lang = this.languages.get(ext);
+    if (!lang) return null;
+    this.parser.setLanguage(lang);
+    return this.parser.parse(content);
+  }
+  /** Check if a grammar is loaded for the given file extension. */
+  hasLanguage(ext) {
+    return this.languages.has(ext);
+  }
+}
+async function initializeTreeSitter() {
+  const runtime = await TreeSitterRuntime.initialize();
+  return runtime !== null;
+}
+class TreeSitterChunker {
+  maxChunkSize;
+  runtime;
+  regexFallback;
+  constructor(runtime, options) {
+    this.runtime = runtime;
+    this.maxChunkSize = options?.maxChunkSize ?? CHUNK_SIZES.code.max;
+    this.regexFallback = new CodeChunker(options);
+  }
+  chunk(content, metadata) {
+    const ext = extname(metadata.sourcePath).toLowerCase();
+    const tree = this.runtime.parse(content, ext);
+    if (!tree) {
+      return this.regexFallback.chunk(content, metadata);
+    }
+    try {
+      return this.chunkFromAst(tree, content, metadata);
+    } catch {
+      return this.regexFallback.chunk(content, metadata);
+    }
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: tree-sitter tree has no published types
+  chunkFromAst(tree, content, metadata) {
+    const rootNode = tree.rootNode;
+    const chunks = [];
+    const declarations = [];
+    for (let i = 0; i < rootNode.childCount; i++) {
+      const child = rootNode.child(i);
+      if (!child) continue;
+      if (DECLARATION_TYPES.has(child.type)) {
+        let startByte = child.startPosition ? child.startIndex : child.startByte ?? 0;
+        let startRow = child.startPosition?.row ?? 0;
+        let prev = child.previousSibling;
+        while (prev && (prev.type === "comment" || prev.type === "line_comment" || prev.type === "block_comment" || prev.type === "decorator")) {
+          startByte = prev.startIndex ?? prev.startByte ?? startByte;
+          startRow = prev.startPosition?.row ?? startRow;
+          prev = prev.previousSibling;
+        }
+        declarations.push({
+          startByte,
+          endByte: child.endIndex ?? child.endByte ?? content.length,
+          startRow,
+          endRow: child.endPosition?.row ?? content.split("\n").length - 1
+        });
+      }
+    }
+    if (declarations.length === 0) {
+      return this.regexFallback.chunk(content, metadata);
+    }
+    if (declarations[0].startByte > 0) {
+      const preamble = content.slice(0, declarations[0].startByte).trim();
+      if (preamble.length > 0) {
+        chunks.push({
+          text: `// File: ${metadata.sourcePath}
+${preamble}`,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: 0,
+          totalChunks: 0,
+          startLine: 1,
+          endLine: declarations[0].startRow + 1
+        });
+      }
+    }
+    for (const decl of declarations) {
+      let text = content.slice(decl.startByte, decl.endByte).trim();
+      const header = `// File: ${metadata.sourcePath}
+`;
+      text = header + text;
+      if (text.length > this.maxChunkSize) {
+        const subChunks = this.splitByLines(text, this.maxChunkSize);
+        let currentLine = decl.startRow + 1;
+        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 {
+        chunks.push({
+          text,
+          sourcePath: metadata.sourcePath,
+          contentType: metadata.contentType,
+          chunkIndex: chunks.length,
+          totalChunks: 0,
+          startLine: decl.startRow + 1,
+          endLine: decl.endRow + 1
+        });
+      }
+    }
+    return chunks.map((c, i) => ({ ...c, chunkIndex: i, totalChunks: chunks.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;
+  }
+}
+export {
+  TreeSitterChunker,
+  TreeSitterRuntime,
+  initializeTreeSitter
+};
+//# sourceMappingURL=treesitter-chunker.js.map

package/packages/cli/dist/commands/analyze.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../types.js';
+export declare const analyzeCommands: Command[];
+//# sourceMappingURL=analyze.d.ts.map

package/packages/cli/dist/commands/analyze.js

@@ -0,0 +1,112 @@
+import { resolve } from "node:path";
+const analyzeCommands = [
+  {
+    name: "analyze",
+    description: "Run analyzer output for a path",
+    usage: "kb analyze <type> <path>",
+    run: async (args) => {
+      const type = args.shift()?.trim() ?? "";
+      const targetPath = args.shift()?.trim() ?? "";
+      if (!type || !targetPath) {
+        console.error("Usage: kb analyze <type> <path>");
+        console.error(
+          "Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram"
+        );
+        process.exit(1);
+      }
+      const {
+        BlastRadiusAnalyzer,
+        DependencyAnalyzer,
+        DiagramGenerator,
+        EntryPointAnalyzer,
+        PatternAnalyzer,
+        StructureAnalyzer,
+        SymbolAnalyzer
+      } = await import("@kb/analyzers");
+      const absolutePath = resolve(targetPath);
+      let result;
+      switch (type) {
+        case "structure":
+          result = await new StructureAnalyzer().analyze(absolutePath, { format: "markdown" });
+          break;
+        case "deps":
+        case "dependencies":
+          result = await new DependencyAnalyzer().analyze(absolutePath, { format: "markdown" });
+          break;
+        case "symbols":
+          result = await new SymbolAnalyzer().analyze(absolutePath, { format: "markdown" });
+          break;
+        case "patterns":
+          result = await new PatternAnalyzer().analyze(absolutePath, { format: "markdown" });
+          break;
+        case "entry-points":
+          result = await new EntryPointAnalyzer().analyze(absolutePath, { format: "markdown" });
+          break;
+        case "blast-radius":
+          result = await new BlastRadiusAnalyzer().analyze(process.cwd(), {
+            files: [targetPath],
+            format: "markdown"
+          });
+          break;
+        case "diagram":
+          result = await new DiagramGenerator().analyze(absolutePath, {
+            diagramType: "architecture"
+          });
+          break;
+        default:
+          console.error(`Unknown analyze type: ${type}`);
+          console.error(
+            "Types: structure, deps, symbols, patterns, entry-points, blast-radius, diagram"
+          );
+          process.exit(1);
+      }
+      console.log(result.output);
+    }
+  },
+  {
+    name: "onboard",
+    description: "Run all analyses for first-time codebase onboarding",
+    usage: "kb onboard <path> [--generate] [--out-dir <dir>]",
+    run: async (args) => {
+      const { onboard } = await import("@kb/tools");
+      let targetPath = "";
+      let mode = "memory";
+      let outDir;
+      for (let i = 0; i < args.length; i++) {
+        const arg = args[i].trim();
+        if (arg === "--generate") {
+          mode = "generate";
+        } else if (arg === "--out-dir" && i + 1 < args.length) {
+          outDir = args[++i].trim();
+        } else if (!arg.startsWith("--")) {
+          targetPath = arg;
+        }
+      }
+      if (!targetPath) {
+        targetPath = process.cwd();
+      }
+      const absolutePath = resolve(targetPath);
+      console.log(`Onboarding: ${absolutePath} (mode: ${mode})`);
+      console.log("Running analyses...\n");
+      const result = await onboard({
+        path: absolutePath,
+        mode,
+        outDir
+      });
+      for (const step of result.steps) {
+        const icon = step.status === "success" ? "\u2713" : "\u2717";
+        const info = step.status === "success" ? `${step.durationMs}ms, ${step.output.length} chars` : step.error;
+        console.log(`  ${icon} ${step.name} \u2014 ${info}`);
+      }
+      console.log(`
+Total: ${result.totalDurationMs}ms`);
+      if (result.outDir) {
+        console.log(`Output written to: ${result.outDir}`);
+      }
+    }
+  }
+];
+export {
+  analyzeCommands
+};
+//# sourceMappingURL=analyze.js.map

package/packages/cli/dist/commands/context-cmds.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../types.js';
+export declare const contextCommands: Command[];
+//# sourceMappingURL=context-cmds.d.ts.map

package/packages/cli/dist/commands/context-cmds.js

@@ -0,0 +1,155 @@
+import { resolve } from "node:path";
+import {
+  checkpointLatest,
+  checkpointList,
+  checkpointLoad,
+  checkpointSave,
+  diffParse,
+  fileSummary,
+  gitContext,
+  parseOutput
+} from "@kb/tools";
+import {
+  extractBoolFlag,
+  extractNumFlag,
+  extractStrFlag,
+  parseRecordString,
+  printCheckpoint,
+  printDiffFiles,
+  printFileSummary,
+  printGitContext,
+  printParsedOutput,
+  readStdin
+} from "../helpers.js";
+const contextCommands = [
+  {
+    name: "parse-output",
+    description: "Parse build or tool output from stdin",
+    usage: "kb parse-output [--tool tsc|vitest|biome|git-status]",
+    run: async (args) => {
+      const tool = extractStrFlag(args, "--tool", "").trim() || void 0;
+      const input = await readStdin();
+      if (!input.trim()) {
+        console.error("Usage: kb parse-output [--tool tsc|vitest|biome|git-status]");
+        process.exit(1);
+      }
+      printParsedOutput(parseOutput(input, tool));
+    }
+  },
+  {
+    name: "git",
+    description: "Show git branch, status, recent commits, and optional diff stats",
+    usage: "kb git [--cwd path] [--commit-count N] [--diff]",
+    run: async (args) => {
+      const cwd = extractStrFlag(args, "--cwd", "").trim() || void 0;
+      const commitCount = extractNumFlag(args, "--commit-count", 5);
+      const includeDiff = extractBoolFlag(args, "--diff");
+      const result = await gitContext({ cwd, commitCount, includeDiff });
+      printGitContext(result);
+    }
+  },
+  {
+    name: "diff",
+    description: "Parse unified diff text from stdin into structured file changes",
+    usage: "git diff | kb diff",
+    run: async () => {
+      const input = await readStdin();
+      if (!input.trim()) {
+        console.error("Usage: git diff | kb diff");
+        process.exit(1);
+      }
+      printDiffFiles(diffParse({ diff: input }));
+    }
+  },
+  {
+    name: "summarize",
+    description: "Show a structural summary of a file",
+    usage: "kb summarize <path>",
+    run: async (args) => {
+      const targetPath = args.shift()?.trim();
+      if (!targetPath) {
+        console.error("Usage: kb summarize <path>");
+        process.exit(1);
+      }
+      const summary = await fileSummary({ path: resolve(targetPath) });
+      printFileSummary(summary);
+    }
+  },
+  {
+    name: "checkpoint",
+    description: "Save and restore lightweight session checkpoints",
+    usage: "kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]",
+    run: async (args) => {
+      const action = args.shift()?.trim();
+      if (!action) {
+        console.error(
+          "Usage: kb checkpoint <save|load|list|latest> [label-or-id] [--data json] [--notes text]"
+        );
+        process.exit(1);
+      }
+      switch (action) {
+        case "save": {
+          const label = args.shift()?.trim();
+          const dataFlag = extractStrFlag(args, "--data", "");
+          const notes = extractStrFlag(args, "--notes", "").trim() || void 0;
+          const stdinData = dataFlag.trim() ? "" : await readStdin();
+          if (!label) {
+            console.error("Usage: kb checkpoint save <label> [--data json] [--notes text]");
+            process.exit(1);
+          }
+          const checkpoint = checkpointSave(label, parseRecordString(dataFlag || stdinData), {
+            notes
+          });
+          printCheckpoint(checkpoint);
+          return;
+        }
+        case "load": {
+          const id = args.shift()?.trim();
+          if (!id) {
+            console.error("Usage: kb checkpoint load <id>");
+            process.exit(1);
+          }
+          const checkpoint = checkpointLoad(id);
+          if (!checkpoint) {
+            console.log(`No checkpoint found: ${id}`);
+            return;
+          }
+          printCheckpoint(checkpoint);
+          return;
+        }
+        case "list": {
+          const checkpoints = checkpointList();
+          if (checkpoints.length === 0) {
+            console.log("No checkpoints saved.");
+            return;
+          }
+          console.log(`Checkpoints (${checkpoints.length})`);
+          console.log("\u2500".repeat(60));
+          for (const checkpoint of checkpoints) {
+            console.log(`${checkpoint.id}`);
+            console.log(`  Label: ${checkpoint.label}`);
+            console.log(`  Created: ${checkpoint.createdAt}`);
+          }
+          return;
+        }
+        case "latest": {
+          const checkpoint = checkpointLatest();
+          if (!checkpoint) {
+            console.log("No checkpoints saved.");
+            return;
+          }
+          printCheckpoint(checkpoint);
+          return;
+        }
+        default:
+          console.error(`Unknown checkpoint action: ${action}`);
+          console.error("Actions: save, load, list, latest");
+          process.exit(1);
+      }
+    }
+  }
+];
+export {
+  contextCommands
+};
+//# sourceMappingURL=context-cmds.js.map

package/packages/cli/dist/commands/environment.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../types.js';
+export declare const environmentCommands: Command[];
+//# sourceMappingURL=environment.d.ts.map