bluera-knowledge 0.10.0 → 0.11.0

package/dist/mcp/server.js

@@ -1,8 +1,8 @@
 import {
   createMCPServer,
   runMCPServer
-} from "../chunk-CUHYSPRV.js";
-import "../chunk-DWAIT2OD.js";
+} from "../chunk-565OVW3C.js";
+import "../chunk-TRDMYKGC.js";
 import "../chunk-6FHWC36B.js";
 export {
   createMCPServer,

package/dist/workers/background-worker-cli.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   IntelligentCrawler
-} from "../chunk-ITH6FWQY.js";
+} from "../chunk-2WBITQWZ.js";
 import {
   JobService,
   createDocumentId,
   createServices,
   createStoreId
-} from "../chunk-DWAIT2OD.js";
+} from "../chunk-TRDMYKGC.js";
 import "../chunk-6FHWC36B.js";
 
 // src/workers/background-worker.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/src/analysis/adapter-registry.test.ts

@@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AdapterRegistry } from './adapter-registry.js';
+import type { LanguageAdapter } from './language-adapter.js';
+import type { CodeNode, ImportInfo } from './ast-parser.js';
+import type { GraphEdge } from './code-graph.js';
+
+/**
+ * Mock adapter for testing
+ */
+function createMockAdapter(overrides: Partial<LanguageAdapter> = {}): LanguageAdapter {
+  return {
+    languageId: 'test-lang',
+    extensions: ['.test'],
+    displayName: 'Test Language',
+    parse: (): CodeNode[] => [],
+    extractImports: (): ImportInfo[] => [],
+    ...overrides,
+  };
+}
+
+describe('AdapterRegistry', () => {
+  beforeEach(() => {
+    // Reset singleton for each test
+    AdapterRegistry.resetInstance();
+  });
+
+  describe('getInstance', () => {
+    it('should return the same instance on multiple calls', () => {
+      const instance1 = AdapterRegistry.getInstance();
+      const instance2 = AdapterRegistry.getInstance();
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe('register', () => {
+    it('should register an adapter', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter();
+
+      registry.register(adapter);
+
+      expect(registry.getByLanguageId('test-lang')).toBe(adapter);
+    });
+
+    it('should be idempotent when registering same languageId', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter1 = createMockAdapter();
+      const adapter2 = createMockAdapter();
+
+      registry.register(adapter1);
+      registry.register(adapter2); // Should not throw, just skip
+
+      // First adapter should still be registered
+      expect(registry.getByLanguageId('test-lang')).toBe(adapter1);
+      expect(registry.getAllAdapters()).toHaveLength(1);
+    });
+
+    it('should throw if extension is already registered by another adapter', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter1 = createMockAdapter({ languageId: 'lang1', extensions: ['.test'] });
+      const adapter2 = createMockAdapter({ languageId: 'lang2', extensions: ['.test'] });
+
+      registry.register(adapter1);
+
+      expect(() => registry.register(adapter2)).toThrow(
+        'Extension ".test" is already registered by adapter "lang1"'
+      );
+    });
+  });
+
+  describe('getByExtension', () => {
+    it('should return adapter by extension', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({ extensions: ['.zil', '.mud'] });
+
+      registry.register(adapter);
+
+      expect(registry.getByExtension('.zil')).toBe(adapter);
+      expect(registry.getByExtension('.mud')).toBe(adapter);
+    });
+
+    it('should return undefined for unregistered extension', () => {
+      const registry = AdapterRegistry.getInstance();
+
+      expect(registry.getByExtension('.unknown')).toBeUndefined();
+    });
+
+    it('should normalize extension with leading dot', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({ extensions: ['.zil'] });
+
+      registry.register(adapter);
+
+      // Both with and without dot should work
+      expect(registry.getByExtension('.zil')).toBe(adapter);
+      expect(registry.getByExtension('zil')).toBe(adapter);
+    });
+  });
+
+  describe('getByLanguageId', () => {
+    it('should return adapter by language ID', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({ languageId: 'zil' });
+
+      registry.register(adapter);
+
+      expect(registry.getByLanguageId('zil')).toBe(adapter);
+    });
+
+    it('should return undefined for unregistered language ID', () => {
+      const registry = AdapterRegistry.getInstance();
+
+      expect(registry.getByLanguageId('unknown')).toBeUndefined();
+    });
+  });
+
+  describe('getAllAdapters', () => {
+    it('should return empty array when no adapters registered', () => {
+      const registry = AdapterRegistry.getInstance();
+
+      expect(registry.getAllAdapters()).toEqual([]);
+    });
+
+    it('should return all registered adapters', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter1 = createMockAdapter({ languageId: 'lang1', extensions: ['.l1'] });
+      const adapter2 = createMockAdapter({ languageId: 'lang2', extensions: ['.l2'] });
+
+      registry.register(adapter1);
+      registry.register(adapter2);
+
+      const adapters = registry.getAllAdapters();
+      expect(adapters).toHaveLength(2);
+      expect(adapters).toContain(adapter1);
+      expect(adapters).toContain(adapter2);
+    });
+  });
+
+  describe('unregister', () => {
+    it('should unregister an adapter by language ID', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({ languageId: 'zil', extensions: ['.zil'] });
+
+      registry.register(adapter);
+      expect(registry.getByLanguageId('zil')).toBe(adapter);
+
+      const result = registry.unregister('zil');
+      expect(result).toBe(true);
+      expect(registry.getByLanguageId('zil')).toBeUndefined();
+      expect(registry.getByExtension('.zil')).toBeUndefined();
+    });
+
+    it('should return false when unregistering non-existent adapter', () => {
+      const registry = AdapterRegistry.getInstance();
+
+      const result = registry.unregister('nonexistent');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('hasExtension', () => {
+    it('should return true for registered extension', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({ extensions: ['.zil'] });
+
+      registry.register(adapter);
+
+      expect(registry.hasExtension('.zil')).toBe(true);
+    });
+
+    it('should return false for unregistered extension', () => {
+      const registry = AdapterRegistry.getInstance();
+
+      expect(registry.hasExtension('.unknown')).toBe(false);
+    });
+  });
+
+  describe('adapter with optional methods', () => {
+    it('should support adapters with chunk method', () => {
+      const registry = AdapterRegistry.getInstance();
+      const adapter = createMockAdapter({
+        chunk: () => [{ content: 'test', startLine: 1, endLine: 10 }],
+      });
+
+      registry.register(adapter);
+
+      const retrieved = registry.getByLanguageId('test-lang');
+      expect(retrieved?.chunk).toBeDefined();
+      expect(retrieved?.chunk?.('', '')).toEqual([{ content: 'test', startLine: 1, endLine: 10 }]);
+    });
+
+    it('should support adapters with analyzeCallRelationships method', () => {
+      const registry = AdapterRegistry.getInstance();
+      const mockEdge: GraphEdge = {
+        from: 'a',
+        to: 'b',
+        type: 'calls',
+        confidence: 1.0,
+      };
+      const adapter = createMockAdapter({
+        analyzeCallRelationships: () => [mockEdge],
+      });
+
+      registry.register(adapter);
+
+      const retrieved = registry.getByLanguageId('test-lang');
+      expect(retrieved?.analyzeCallRelationships).toBeDefined();
+      expect(retrieved?.analyzeCallRelationships?.('', '')).toEqual([mockEdge]);
+    });
+  });
+});

package/src/analysis/adapter-registry.ts

@@ -0,0 +1,155 @@
+/**
+ * Adapter Registry
+ *
+ * Singleton registry for language adapters. Provides lookup by extension
+ * or language ID.
+ *
+ * @example
+ * ```typescript
+ * // Register an adapter
+ * const registry = AdapterRegistry.getInstance();
+ * registry.register(zilAdapter);
+ *
+ * // Look up by extension
+ * const adapter = registry.getByExtension('.zil');
+ * if (adapter) {
+ *   const nodes = adapter.parse(content, filePath);
+ * }
+ * ```
+ */
+
+import type { LanguageAdapter } from './language-adapter.js';
+
+export class AdapterRegistry {
+  private static instance: AdapterRegistry | undefined;
+
+  /** Map from languageId to adapter */
+  private readonly adaptersByLanguageId = new Map<string, LanguageAdapter>();
+
+  /** Map from extension to adapter */
+  private readonly adaptersByExtension = new Map<string, LanguageAdapter>();
+
+  private constructor() {
+    // Private constructor for singleton
+  }
+
+  /**
+   * Get the singleton instance of the registry.
+   */
+  static getInstance(): AdapterRegistry {
+    AdapterRegistry.instance ??= new AdapterRegistry();
+    return AdapterRegistry.instance;
+  }
+
+  /**
+   * Reset the singleton instance (for testing).
+   */
+  static resetInstance(): void {
+    AdapterRegistry.instance = undefined;
+  }
+
+  /**
+   * Register a language adapter.
+   *
+   * @param adapter - The adapter to register
+   * @throws If a different adapter with the same extension is already registered
+   */
+  register(adapter: LanguageAdapter): void {
+    // Skip if already registered with same languageId (idempotent)
+    if (this.adaptersByLanguageId.has(adapter.languageId)) {
+      return;
+    }
+
+    // Check for extension conflicts with other adapters
+    for (const ext of adapter.extensions) {
+      const normalizedExt = this.normalizeExtension(ext);
+      const existingAdapter = this.adaptersByExtension.get(normalizedExt);
+      if (existingAdapter !== undefined) {
+        throw new Error(
+          `Extension "${normalizedExt}" is already registered by adapter "${existingAdapter.languageId}"`
+        );
+      }
+    }
+
+    // Register by languageId
+    this.adaptersByLanguageId.set(adapter.languageId, adapter);
+
+    // Register by each extension
+    for (const ext of adapter.extensions) {
+      const normalizedExt = this.normalizeExtension(ext);
+      this.adaptersByExtension.set(normalizedExt, adapter);
+    }
+  }
+
+  /**
+   * Unregister a language adapter by its language ID.
+   *
+   * @param languageId - The language ID to unregister
+   * @returns true if the adapter was found and removed, false otherwise
+   */
+  unregister(languageId: string): boolean {
+    const adapter = this.adaptersByLanguageId.get(languageId);
+    if (adapter === undefined) {
+      return false;
+    }
+
+    // Remove from languageId map
+    this.adaptersByLanguageId.delete(languageId);
+
+    // Remove from extension map
+    for (const ext of adapter.extensions) {
+      const normalizedExt = this.normalizeExtension(ext);
+      this.adaptersByExtension.delete(normalizedExt);
+    }
+
+    return true;
+  }
+
+  /**
+   * Get an adapter by file extension.
+   *
+   * @param ext - File extension (with or without leading dot)
+   * @returns The adapter if found, undefined otherwise
+   */
+  getByExtension(ext: string): LanguageAdapter | undefined {
+    const normalizedExt = this.normalizeExtension(ext);
+    return this.adaptersByExtension.get(normalizedExt);
+  }
+
+  /**
+   * Get an adapter by language ID.
+   *
+   * @param languageId - The unique language identifier
+   * @returns The adapter if found, undefined otherwise
+   */
+  getByLanguageId(languageId: string): LanguageAdapter | undefined {
+    return this.adaptersByLanguageId.get(languageId);
+  }
+
+  /**
+   * Get all registered adapters.
+   *
+   * @returns Array of all registered adapters
+   */
+  getAllAdapters(): LanguageAdapter[] {
+    return Array.from(this.adaptersByLanguageId.values());
+  }
+
+  /**
+   * Check if an extension is registered.
+   *
+   * @param ext - File extension (with or without leading dot)
+   * @returns true if the extension is registered
+   */
+  hasExtension(ext: string): boolean {
+    const normalizedExt = this.normalizeExtension(ext);
+    return this.adaptersByExtension.has(normalizedExt);
+  }
+
+  /**
+   * Normalize extension to always have a leading dot.
+   */
+  private normalizeExtension(ext: string): string {
+    return ext.startsWith('.') ? ext : `.${ext}`;
+  }
+}

package/src/analysis/language-adapter.ts

@@ -0,0 +1,127 @@
+/**
+ * Language Adapter Interface
+ *
+ * Defines the contract for custom language support in bluera-knowledge.
+ * Adapters provide language-specific parsing, import extraction, chunking,
+ * and call relationship analysis.
+ *
+ * Built-in adapters: ZIL (Zork Implementation Language)
+ * Users can create custom adapters for any language.
+ */
+
+import type { CodeNode, ImportInfo } from './ast-parser.js';
+import type { GraphEdge } from './code-graph.js';
+
+/**
+ * Result of chunking a file into logical units
+ */
+export interface ChunkResult {
+  /** The content of the chunk */
+  content: string;
+  /** Starting line number (1-based) */
+  startLine: number;
+  /** Ending line number (1-based) */
+  endLine: number;
+  /** Optional symbol name this chunk represents */
+  symbolName?: string;
+  /** Optional symbol kind (routine, object, class, etc.) */
+  symbolKind?: string;
+}
+
+/**
+ * Interface for language-specific parsing and analysis.
+ *
+ * Adapters enable full graph support for custom languages:
+ * - Smart chunking by language constructs
+ * - Symbol extraction (functions, classes, objects)
+ * - Import/include relationship tracking
+ * - Call graph analysis
+ *
+ * @example
+ * ```typescript
+ * const zilAdapter: LanguageAdapter = {
+ *   languageId: 'zil',
+ *   extensions: ['.zil', '.mud'],
+ *   displayName: 'ZIL (Zork Implementation Language)',
+ *
+ *   parse(content, filePath) {
+ *     // Extract routines, objects, rooms, globals
+ *     return [...];
+ *   },
+ *
+ *   extractImports(content, filePath) {
+ *     // Find INSERT-FILE directives
+ *     return [...];
+ *   },
+ *
+ *   chunk(content, filePath) {
+ *     // Split by top-level forms
+ *     return [...];
+ *   }
+ * };
+ * ```
+ */
+export interface LanguageAdapter {
+  /**
+   * Unique identifier for this language.
+   * Used for registry lookup and configuration.
+   * @example 'zil', 'cobol', 'fortran'
+   */
+  readonly languageId: string;
+
+  /**
+   * File extensions this adapter handles (with leading dot).
+   * @example ['.zil', '.mud'] or ['.cbl', '.cob']
+   */
+  readonly extensions: string[];
+
+  /**
+   * Human-readable name for the language.
+   * @example 'ZIL (Zork Implementation Language)'
+   */
+  readonly displayName: string;
+
+  /**
+   * Parse file content and extract code symbols.
+   *
+   * @param content - File content as string
+   * @param filePath - Path to the file (for error messages)
+   * @returns Array of code nodes (functions, classes, etc.)
+   */
+  parse(content: string, filePath: string): CodeNode[];
+
+  /**
+   * Extract import/include statements from file content.
+   *
+   * @param content - File content as string
+   * @param filePath - Path to the file (for resolving relative imports)
+   * @returns Array of import information
+   */
+  extractImports(content: string, filePath: string): ImportInfo[];
+
+  /**
+   * Optional: Split file into logical chunks for indexing.
+   *
+   * If not provided, the default chunking strategy is used.
+   * Custom chunking improves search quality by aligning chunks
+   * with language constructs (functions, classes, etc.).
+   *
+   * @param content - File content as string
+   * @param filePath - Path to the file
+   * @returns Array of chunk results
+   */
+  chunk?(content: string, filePath: string): ChunkResult[];
+
+  /**
+   * Optional: Analyze call relationships within a file.
+   *
+   * If not provided, the default regex-based call detection is used.
+   * Custom analysis can filter language-specific special forms
+   * and provide higher-confidence edges.
+   *
+   * @param content - File content as string
+   * @param filePath - Path to the file
+   * @returns Array of graph edges representing calls
+   */
+  analyzeCallRelationships?(content: string, filePath: string): GraphEdge[];
+}

package/src/analysis/parser-factory.test.ts

@@ -1,6 +1,9 @@
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ParserFactory } from './parser-factory.js';
 import type { PythonBridge, ParsePythonResult } from '../crawl/bridge.js';
+import { AdapterRegistry } from './adapter-registry.js';
+import type { LanguageAdapter } from './language-adapter.js';
+import type { CodeNode, ImportInfo } from './ast-parser.js';
 
 describe('ParserFactory', () => {
   describe('parseFile', () => {
@@ -129,4 +132,79 @@ describe('ParserFactory', () => {
       expect(nodes).toEqual([]);
     });
   });
+
+  describe('adapter integration', () => {
+    beforeEach(() => {
+      // Reset adapter registry before each test
+      AdapterRegistry.resetInstance();
+    });
+
+    it('should use registered adapter for unknown extension', async () => {
+      const mockNodes: CodeNode[] = [
+        {
+          type: 'function',
+          name: 'V-LOOK',
+          exported: true,
+          startLine: 1,
+          endLine: 5,
+          signature: 'ROUTINE V-LOOK ()',
+        },
+      ];
+
+      const mockAdapter: LanguageAdapter = {
+        languageId: 'zil',
+        extensions: ['.zil'],
+        displayName: 'ZIL',
+        parse: vi.fn().mockReturnValue(mockNodes),
+        extractImports: vi.fn().mockReturnValue([]),
+      };
+
+      const registry = AdapterRegistry.getInstance();
+      registry.register(mockAdapter);
+
+      const factory = new ParserFactory();
+      const code = '<ROUTINE V-LOOK () <TELL "You see nothing special.">>';
+      const nodes = await factory.parseFile('actions.zil', code);
+
+      expect(mockAdapter.parse).toHaveBeenCalledWith(code, 'actions.zil');
+      expect(nodes).toEqual(mockNodes);
+    });
+
+    it('should prefer built-in parser over adapter for supported extensions', async () => {
+      // Register an adapter that claims to handle .ts files
+      const mockAdapter: LanguageAdapter = {
+        languageId: 'fake-ts',
+        extensions: ['.ts'],
+        displayName: 'Fake TypeScript',
+        parse: vi.fn().mockReturnValue([]),
+        extractImports: vi.fn().mockReturnValue([]),
+      };
+
+      // This should throw because .ts is handled by built-in
+      // But we want built-in to take precedence, so adapter shouldn't even be called
+      // Actually, registration should work, but built-in should be used first
+
+      // For now, test that built-in works even if we could register
+      const factory = new ParserFactory();
+      const code = 'export function hello(): string { return "world"; }';
+      const nodes = await factory.parseFile('test.ts', code);
+
+      // Built-in parser should work
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]).toMatchObject({
+        type: 'function',
+        name: 'hello',
+      });
+
+      // Adapter should not have been called (it wasn't registered in this test)
+      expect(mockAdapter.parse).not.toHaveBeenCalled();
+    });
+
+    it('should return empty array when no adapter and unsupported extension', async () => {
+      const factory = new ParserFactory();
+      const nodes = await factory.parseFile('unknown.xyz', 'some content');
+
+      expect(nodes).toEqual([]);
+    });
+  });
 });

package/src/analysis/parser-factory.ts

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { AdapterRegistry } from './adapter-registry.js';
 import { ASTParser, type CodeNode } from './ast-parser.js';
 import { GoASTParser } from './go-ast-parser.js';
 import { PythonASTParser } from './python-ast-parser.js';
@@ -39,6 +40,13 @@ export class ParserFactory {
       return parser.parse(code, filePath);
     }
 
+    // Check for registered language adapters
+    const registry = AdapterRegistry.getInstance();
+    const adapter = registry.getByExtension(ext);
+    if (adapter !== undefined) {
+      return adapter.parse(code, filePath);
+    }
+
     return [];
   }
 }

package/src/analysis/zil/index.ts

@@ -0,0 +1,34 @@
+/**
+ * ZIL (Zork Implementation Language) Support
+ *
+ * Provides full graph support for ZIL source files:
+ * - Lexer: Tokenizes ZIL syntax
+ * - Parser: Extracts symbols, imports, and calls
+ * - Adapter: Implements LanguageAdapter interface
+ *
+ * @example
+ * ```typescript
+ * import { ZilAdapter } from './zil/index.js';
+ * import { AdapterRegistry } from './adapter-registry.js';
+ *
+ * // Register ZIL support
+ * const registry = AdapterRegistry.getInstance();
+ * registry.register(new ZilAdapter());
+ * ```
+ */
+
+export { ZilLexer, TokenType, type Token } from './zil-lexer.js';
+export {
+  ZilParser,
+  type ZilForm,
+  type ZilNode,
+  type ZilSymbol,
+  type ZilCall,
+} from './zil-parser.js';
+export { ZilAdapter } from './zil-adapter.js';
+export {
+  ZIL_SPECIAL_FORMS,
+  ZIL_DEFINITION_FORMS,
+  isSpecialForm,
+  isDefinitionForm,
+} from './zil-special-forms.js';