@vpxa/kb 0.1.1

package/packages/analyzers/dist/diagram-generator.js

@@ -0,0 +1,86 @@
+import { DependencyAnalyzer } from "./dependency-analyzer.js";
+import { StructureAnalyzer } from "./structure-analyzer.js";
+class DiagramGenerator {
+  name = "diagrams";
+  structureAnalyzer = new StructureAnalyzer();
+  dependencyAnalyzer = new DependencyAnalyzer();
+  async analyze(rootPath, options = {}) {
+    const { diagramType = "architecture" } = options;
+    const startTime = Date.now();
+    let output;
+    switch (diagramType) {
+      case "dependencies":
+        output = await this.generateDependencyDiagram(rootPath);
+        break;
+      default:
+        output = await this.generateArchitectureDiagram(rootPath);
+        break;
+    }
+    return {
+      output,
+      data: { diagramType },
+      meta: {
+        analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        scope: rootPath,
+        fileCount: 0,
+        durationMs: Date.now() - startTime
+      }
+    };
+  }
+  async generateArchitectureDiagram(rootPath) {
+    const structResult = await this.structureAnalyzer.analyze(rootPath, {
+      format: "json",
+      maxDepth: 4
+    });
+    const tree = structResult.data.tree;
+    const depResult = await this.dependencyAnalyzer.analyze(rootPath, { format: "json" });
+    const depData = depResult.data;
+    const lines = ["```mermaid", "graph TB"];
+    const topDirs = (tree.children ?? []).filter((c) => c.type === "directory").slice(0, 15);
+    for (const dir of topDirs) {
+      const id = dir.name.replace(/[^a-zA-Z0-9]/g, "_");
+      const subDirs = (dir.children ?? []).filter((c) => c.type === "directory");
+      if (subDirs.length > 0) {
+        lines.push(`  subgraph ${id}["${dir.name}/"]`);
+        for (const sub of subDirs.slice(0, 12)) {
+          const subId = `${id}_${sub.name.replace(/[^a-zA-Z0-9]/g, "_")}`;
+          const fileCount = Array.isArray(sub.children) ? sub.children.length : 0;
+          lines.push(`    ${subId}["${sub.name}/ (${fileCount})"]`);
+        }
+        lines.push("  end");
+      } else {
+        const childCount = Array.isArray(dir.children) ? dir.children.length : 0;
+        lines.push(`  ${id}["${dir.name}/ (${childCount} files)"]`);
+      }
+    }
+    const addedEdges = /* @__PURE__ */ new Set();
+    if (depData.internal) {
+      for (const [file, imports] of Object.entries(depData.internal)) {
+        const fromDir = file.split("/")[0]?.replace(/[^a-zA-Z0-9]/g, "_");
+        for (const imp of imports) {
+          if (imp.startsWith(".")) continue;
+          const toDir = imp.split("/")[0]?.replace(/[^a-zA-Z0-9]/g, "_");
+          if (fromDir && toDir && fromDir !== toDir) {
+            const edgeKey = `${fromDir}->${toDir}`;
+            if (!addedEdges.has(edgeKey)) {
+              addedEdges.add(edgeKey);
+              lines.push(`  ${fromDir} --> ${toDir}`);
+            }
+          }
+        }
+      }
+    }
+    lines.push("```");
+    return lines.join("\n");
+  }
+  async generateDependencyDiagram(rootPath) {
+    const depResult = await this.dependencyAnalyzer.analyze(rootPath, { format: "mermaid" });
+    return `\`\`\`mermaid
+${depResult.output}
+\`\`\``;
+  }
+}
+export {
+  DiagramGenerator
+};
+//# sourceMappingURL=diagram-generator.js.map

package/packages/analyzers/dist/entry-point-analyzer.d.ts

@@ -0,0 +1,19 @@
+import type { AnalysisResult, AnalyzerOptions, IAnalyzer } from './types.js';
+export declare class EntryPointAnalyzer implements IAnalyzer<AnalyzerOptions> {
+    readonly name = "entry-points";
+    analyze(rootPath: string, _options?: AnalyzerOptions): Promise<AnalysisResult>;
+    private fromPackageJson;
+    private fromHandlerExports;
+    /** Extract a meaningful name from the file path for non-JS entry points */
+    private inferNameFromFile;
+    /**
+     * Derive a contextual name from the directory path for generic handler/main files.
+     * E.g., "services/channels/email/delivery/src/handler.ts" → "email-delivery"
+     */
+    private deriveContextualName;
+    private inferEntryType;
+    private detectTrigger;
+    private collectFiles;
+    private formatMarkdown;
+}
+//# sourceMappingURL=entry-point-analyzer.d.ts.map

package/packages/analyzers/dist/entry-point-analyzer.js

@@ -0,0 +1,239 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { extname, join, relative } from "node:path";
+const DEFAULT_EXCLUDES = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+  ".turbo",
+  ".cache",
+  "cdk.out",
+  "__pycache__",
+  ".venv",
+  "target",
+  "bin",
+  "obj",
+  ".gradle",
+  "venv",
+  "env"
+]);
+const TEST_DIR_SEGMENTS = /* @__PURE__ */ new Set(["test", "tests", "__tests__", "spec", "specs", "test-utils"]);
+const HANDLER_PATTERNS = [
+  // ── JS/TS ──
+  // Lambda: export const handler = ... (with optional type annotation)
+  /export\s+const\s+(handler|main)\s*(?::[^=]*)?\s*=/,
+  // Lambda: export async function handler
+  /export\s+(?:async\s+)?function\s+(handler|main)\s*\(/,
+  // Named handler exports: export const emailHandler = ... (with optional type annotation)
+  /export\s+const\s+(\w+Handler)\s*(?::[^=]*)?\s*=/,
+  // Express/Hono app: export default app
+  /export\s+default\s+app/,
+  // ── Python ──
+  // Flask/FastAPI app
+  /^app\s*=\s*(?:Flask|FastAPI)\s*\(/m,
+  // Django: urlpatterns
+  /^urlpatterns\s*=\s*\[/m,
+  // Python main guard
+  /^if\s+__name__\s*==\s*['"]__main__['"]:/m,
+  // ── Java ──
+  // Spring Boot main class
+  /public\s+static\s+void\s+main\s*\(\s*String/,
+  // Spring Boot Application annotation
+  /@SpringBootApplication/,
+  // ── Go ──
+  /^func\s+main\s*\(\s*\)/m
+];
+const TRIGGER_PATTERNS = [
+  { regex: /SqsEventSource|SQSEvent|sqs/i, trigger: "SQS" },
+  { regex: /SnsEventSource|SNSEvent|sns/i, trigger: "SNS" },
+  { regex: /ApiGateway|APIGatewayEvent|httpApi|restApi/i, trigger: "API Gateway" },
+  { regex: /ScheduleExpression|EventBridgeRule|schedule/i, trigger: "EventBridge Schedule" },
+  { regex: /S3EventSource|S3Event|s3/i, trigger: "S3" },
+  { regex: /DynamoEventSource|DynamoDBStream/i, trigger: "DynamoDB Stream" },
+  // Multi-language triggers
+  { regex: /@RequestMapping|@GetMapping|@PostMapping/i, trigger: "HTTP Endpoint" },
+  { regex: /http\.ListenAndServe|gin\.Default|echo\.New/i, trigger: "HTTP Server" },
+  { regex: /app\.route\(|@app\.get|@app\.post|@router\./i, trigger: "HTTP Route" }
+];
+class EntryPointAnalyzer {
+  name = "entry-points";
+  async analyze(rootPath, _options = {}) {
+    const startTime = Date.now();
+    const entryPoints = [];
+    const pkgEntries = await this.fromPackageJson(rootPath);
+    entryPoints.push(...pkgEntries);
+    const handlerEntries = await this.fromHandlerExports(rootPath);
+    entryPoints.push(...handlerEntries);
+    const output = this.formatMarkdown(entryPoints, rootPath);
+    return {
+      output,
+      data: { entryPoints, total: entryPoints.length },
+      meta: {
+        analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        scope: rootPath,
+        fileCount: entryPoints.length,
+        durationMs: Date.now() - startTime
+      }
+    };
+  }
+  async fromPackageJson(rootPath) {
+    const entries = [];
+    try {
+      const pkgPath = join(rootPath, "package.json");
+      await access(pkgPath);
+      const pkg = JSON.parse(await readFile(pkgPath, "utf-8"));
+      if (pkg.main) {
+        entries.push({
+          name: "main",
+          type: "main",
+          filePath: pkg.main
+        });
+      }
+      if (pkg.bin) {
+        const bins = typeof pkg.bin === "string" ? { [pkg.name ?? "cli"]: pkg.bin } : pkg.bin;
+        for (const [name, path] of Object.entries(bins)) {
+          entries.push({ name, type: "cli", filePath: path });
+        }
+      }
+      if (pkg.scripts?.start) {
+        entries.push({
+          name: "start",
+          type: "server",
+          filePath: pkg.scripts.start,
+          trigger: "npm start"
+        });
+      }
+    } catch {
+    }
+    return entries;
+  }
+  async fromHandlerExports(rootPath) {
+    const entries = [];
+    const files = await this.collectFiles(rootPath);
+    for (const filePath of files) {
+      try {
+        const content = await readFile(filePath, "utf-8");
+        const relPath = relative(rootPath, filePath).replace(/\\/g, "/");
+        const pathSegments = relPath.split("/");
+        if (pathSegments.some((seg) => TEST_DIR_SEGMENTS.has(seg))) continue;
+        for (const pattern of HANDLER_PATTERNS) {
+          const match = content.match(pattern);
+          if (match) {
+            let name = match[1] ?? this.inferNameFromFile(relPath);
+            if (name === "handler" || name === "main") {
+              name = this.deriveContextualName(relPath) ?? name;
+            }
+            const isSpringBoot = /@SpringBootApplication/.test(content);
+            const trigger = isSpringBoot ? "HTTP Server" : this.detectTrigger(content);
+            entries.push({
+              name,
+              type: this.inferEntryType(match[1] ?? name, relPath),
+              filePath: relPath,
+              trigger
+            });
+            break;
+          }
+        }
+      } catch {
+      }
+    }
+    return entries;
+  }
+  /** Extract a meaningful name from the file path for non-JS entry points */
+  inferNameFromFile(relPath) {
+    const base = relPath.split(/[/\\]/).pop() ?? "default";
+    return base.replace(/\.\w+$/, "");
+  }
+  /**
+   * Derive a contextual name from the directory path for generic handler/main files.
+   * E.g., "services/channels/email/delivery/src/handler.ts" → "email-delivery"
+   */
+  deriveContextualName(relPath) {
+    const parts = relPath.split("/").filter((p) => p !== "src" && p !== "lib");
+    parts.pop();
+    if (parts.length === 0) return void 0;
+    const meaningful = parts.filter(
+      (p) => !["services", "functions", "lambdas", "handlers", "packages", "apps"].includes(p)
+    );
+    if (meaningful.length === 0) return void 0;
+    const last = meaningful.slice(-2);
+    if (last.length === 2 && last[1].startsWith(last[0])) {
+      return last[1];
+    }
+    return last.join("-");
+  }
+  inferEntryType(name, relPath) {
+    if (name === "handler" || name === "main") return "lambda-handler";
+    if (relPath.includes("handler")) return "lambda-handler";
+    if (/functions[/]/.test(relPath)) return "lambda-handler";
+    if (name.endsWith("Handler")) return "lambda-handler";
+    if (relPath.endsWith(".py") || relPath.endsWith(".go") || relPath.endsWith(".java")) {
+      return "main";
+    }
+    return "main";
+  }
+  detectTrigger(content) {
+    for (const tp of TRIGGER_PATTERNS) {
+      if (tp.regex.test(content)) return tp.trigger;
+    }
+    return void 0;
+  }
+  async collectFiles(rootPath) {
+    const files = [];
+    const codeExts = /* @__PURE__ */ new Set([
+      ".ts",
+      ".tsx",
+      ".js",
+      ".jsx",
+      ".java",
+      ".py",
+      ".go",
+      ".cs",
+      ".kt",
+      ".rb",
+      ".rs",
+      ".php",
+      ".swift"
+    ]);
+    const walk = async (dir, depth) => {
+      if (depth > 10) return;
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (DEFAULT_EXCLUDES.has(entry.name)) continue;
+        if (entry.name.startsWith(".")) continue;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(fullPath, depth + 1);
+        } else if (codeExts.has(extname(entry.name))) {
+          files.push(fullPath);
+        }
+      }
+    };
+    await walk(rootPath, 0);
+    return files;
+  }
+  formatMarkdown(entryPoints, rootPath) {
+    const lines = [];
+    lines.push(`## Entry Points: ${rootPath}
+`);
+    lines.push(
+      `**${entryPoints.length} entry ${entryPoints.length === 1 ? "point" : "points"}** found
+`
+    );
+    if (entryPoints.length === 0) {
+      lines.push("No entry points detected.");
+      return lines.join("\n");
+    }
+    lines.push("| Name | Type | File | Trigger |");
+    lines.push("|------|------|------|---------|");
+    for (const ep of entryPoints) {
+      lines.push(`| ${ep.name} | ${ep.type} | ${ep.filePath} | ${ep.trigger ?? "\u2014"} |`);
+    }
+    return lines.join("\n");
+  }
+}
+export {
+  EntryPointAnalyzer
+};
+//# sourceMappingURL=entry-point-analyzer.js.map

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

@@ -0,0 +1,14 @@
+export type { BlastRadiusOptions } from './blast-radius-analyzer.js';
+export { BlastRadiusAnalyzer } from './blast-radius-analyzer.js';
+export { DependencyAnalyzer } from './dependency-analyzer.js';
+export { DiagramGenerator } from './diagram-generator.js';
+export { EntryPointAnalyzer } from './entry-point-analyzer.js';
+export type { Analyzers } from './knowledge-producer.js';
+export { KnowledgeProducer } from './knowledge-producer.js';
+export { PatternAnalyzer } from './pattern-analyzer.js';
+export { extractRegexCallGraph } from './regex-call-graph.js';
+export { StructureAnalyzer } from './structure-analyzer.js';
+export { SymbolAnalyzer } from './symbol-analyzer.js';
+export { extractTsCallGraph } from './ts-call-graph.js';
+export type { AnalysisResult, AnalyzerOptions, DependencyAnalyzerOptions, DiagramOptions, EntryPoint, ExistingKnowledge, ExtractionBaselines, IAnalyzer, ImportInfo, PatternMatch, ProjectStats, StructureAnalyzerOptions, SymbolAnalyzerOptions, SymbolInfo, TreeNode, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/analyzers/dist/index.js

@@ -0,0 +1,23 @@
+import { BlastRadiusAnalyzer } from "./blast-radius-analyzer.js";
+import { DependencyAnalyzer } from "./dependency-analyzer.js";
+import { DiagramGenerator } from "./diagram-generator.js";
+import { EntryPointAnalyzer } from "./entry-point-analyzer.js";
+import { KnowledgeProducer } from "./knowledge-producer.js";
+import { PatternAnalyzer } from "./pattern-analyzer.js";
+import { extractRegexCallGraph } from "./regex-call-graph.js";
+import { StructureAnalyzer } from "./structure-analyzer.js";
+import { SymbolAnalyzer } from "./symbol-analyzer.js";
+import { extractTsCallGraph } from "./ts-call-graph.js";
+export {
+  BlastRadiusAnalyzer,
+  DependencyAnalyzer,
+  DiagramGenerator,
+  EntryPointAnalyzer,
+  KnowledgeProducer,
+  PatternAnalyzer,
+  StructureAnalyzer,
+  SymbolAnalyzer,
+  extractRegexCallGraph,
+  extractTsCallGraph
+};
+//# sourceMappingURL=index.js.map

package/packages/analyzers/dist/knowledge-producer.d.ts

@@ -0,0 +1,32 @@
+import type { DependencyAnalyzer } from './dependency-analyzer.js';
+import type { DiagramGenerator } from './diagram-generator.js';
+import type { EntryPointAnalyzer } from './entry-point-analyzer.js';
+import type { PatternAnalyzer } from './pattern-analyzer.js';
+import type { StructureAnalyzer } from './structure-analyzer.js';
+import type { SymbolAnalyzer } from './symbol-analyzer.js';
+import type { ExtractionBaselines } from './types.js';
+export interface Analyzers {
+    structure: StructureAnalyzer;
+    dependencies: DependencyAnalyzer;
+    symbols: SymbolAnalyzer;
+    patterns: PatternAnalyzer;
+    entryPoints: EntryPointAnalyzer;
+    diagrams: DiagramGenerator;
+}
+/**
+ * Orchestrates Tier 1 deterministic extraction and prepares
+ * synthesis instructions for the LLM to produce knowledge.
+ */
+export declare class KnowledgeProducer {
+    private readonly analyzers;
+    constructor(analyzers: Analyzers);
+    /**
+     * Run Tier 1 deterministic extraction for specified aspects.
+     */
+    runExtraction(scope: string, aspects: string[]): Promise<ExtractionBaselines>;
+    /**
+     * Build synthesis instructions from baselines for the LLM.
+     */
+    buildSynthesisInstructions(baselines: ExtractionBaselines, _aspects: string[]): string;
+}
+//# sourceMappingURL=knowledge-producer.d.ts.map

package/packages/analyzers/dist/knowledge-producer.js

@@ -0,0 +1,113 @@
+const ASPECT_MAP = {
+  structure: "structure",
+  dependencies: "dependencies",
+  symbols: "symbols",
+  patterns: "patterns",
+  "entry-points": "entryPoints",
+  diagrams: "diagrams"
+};
+const ALL_ASPECTS = Object.keys(ASPECT_MAP);
+class KnowledgeProducer {
+  constructor(analyzers) {
+    this.analyzers = analyzers;
+  }
+  /**
+   * Run Tier 1 deterministic extraction for specified aspects.
+   */
+  async runExtraction(scope, aspects) {
+    const resolvedAspects = aspects.includes("all") ? ALL_ASPECTS : aspects;
+    const baselines = {};
+    const promises = [];
+    for (const aspect of resolvedAspects) {
+      const analyzerKey = ASPECT_MAP[aspect];
+      if (!analyzerKey) continue;
+      const analyzer = this.analyzers[analyzerKey];
+      if (!analyzer) continue;
+      if (aspect === "diagrams") {
+        promises.push({
+          key: "diagrams",
+          promise: analyzer.analyze(scope, { diagramType: "architecture" })
+        });
+      } else {
+        promises.push({
+          key: aspect,
+          promise: analyzer.analyze(scope)
+        });
+      }
+    }
+    const results = await Promise.allSettled(
+      promises.map(async (p) => ({ key: p.key, result: await p.promise }))
+    );
+    for (const settled of results) {
+      if (settled.status !== "fulfilled") continue;
+      const { key, result } = settled.value;
+      if (key === "diagrams") {
+        baselines.diagrams = [result];
+      } else {
+        baselines[key] = result;
+      }
+    }
+    return baselines;
+  }
+  /**
+   * Build synthesis instructions from baselines for the LLM.
+   */
+  buildSynthesisInstructions(baselines, _aspects) {
+    const sections = [];
+    sections.push("## Knowledge Production Results\n");
+    sections.push("### Extraction Baselines (auto-generated)\n");
+    if (baselines.structure) {
+      sections.push("#### File Structure\n");
+      sections.push(baselines.structure.output);
+      sections.push("");
+    }
+    if (baselines.dependencies) {
+      sections.push("#### Dependencies\n");
+      sections.push(baselines.dependencies.output);
+      sections.push("");
+    }
+    if (baselines.symbols) {
+      sections.push("#### Symbols\n");
+      sections.push(baselines.symbols.output);
+      sections.push("");
+    }
+    if (baselines.patterns) {
+      sections.push("#### Detected Patterns\n");
+      sections.push(baselines.patterns.output);
+      sections.push("");
+    }
+    if (baselines.entryPoints) {
+      sections.push("#### Entry Points\n");
+      sections.push(baselines.entryPoints.output);
+      sections.push("");
+    }
+    if (baselines.diagrams && baselines.diagrams.length > 0) {
+      sections.push("#### Architecture Diagram\n");
+      for (const d of baselines.diagrams) {
+        sections.push(d.output);
+      }
+      sections.push("");
+    }
+    sections.push("### Your Task: Synthesize Knowledge\n");
+    sections.push("Based on the baselines above and your reading of the source files, produce");
+    sections.push("the following knowledge documents using `kb_remember`:\n");
+    sections.push(
+      "1. **Domain Overview** (category: `architecture`)\n   - What this service does, boundary with other services\n   - Key entities and their lifecycle\n"
+    );
+    sections.push(
+      "2. **Architecture Summary** (category: `architecture`)\n   - Layer structure, dependency flow\n   - Key design decisions\n"
+    );
+    sections.push(
+      "3. **Pattern Usage** (category: `patterns`)\n   - Which patterns are used and why\n   - Where to find examples\n"
+    );
+    sections.push(
+      "4. **Conventions** (category: `conventions`)\n   - Naming conventions observed\n   - File organization rules\n   - Testing patterns\n"
+    );
+    sections.push("Store each as a separate `kb_remember` call with descriptive titles.\n");
+    return sections.join("\n");
+  }
+}
+export {
+  KnowledgeProducer
+};
+//# sourceMappingURL=knowledge-producer.js.map

package/packages/analyzers/dist/pattern-analyzer.d.ts

@@ -0,0 +1,12 @@
+import type { AnalysisResult, AnalyzerOptions, IAnalyzer } from './types.js';
+export declare class PatternAnalyzer implements IAnalyzer<AnalyzerOptions> {
+    readonly name = "patterns";
+    analyze(rootPath: string, _options?: AnalyzerOptions): Promise<AnalysisResult>;
+    private collectDirectories;
+    private collectCodeFiles;
+    private detectDirectoryPatterns;
+    private detectCodePatterns;
+    private detectConfigPatterns;
+    private formatMarkdown;
+}
+//# sourceMappingURL=pattern-analyzer.d.ts.map