bluera-knowledge 0.10.1 → 0.11.1

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

@@ -0,0 +1,187 @@
+import { describe, it, expect } from 'vitest';
+import { ZilAdapter } from './zil-adapter.js';
+import type { LanguageAdapter } from '../language-adapter.js';
+
+describe('ZilAdapter', () => {
+  const adapter = new ZilAdapter();
+
+  describe('interface compliance', () => {
+    it('should implement LanguageAdapter interface', () => {
+      // Type check - this should compile without error
+      const _: LanguageAdapter = adapter;
+      expect(adapter.languageId).toBe('zil');
+      expect(adapter.extensions).toContain('.zil');
+      expect(adapter.displayName).toBeDefined();
+    });
+
+    it('should have correct extensions', () => {
+      expect(adapter.extensions).toEqual(['.zil', '.mud']);
+    });
+  });
+
+  describe('parse', () => {
+    it('should return CodeNode[] for routines', () => {
+      const code = '<ROUTINE V-LOOK () <TELL "You see nothing.">>';
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]).toMatchObject({
+        type: 'function',
+        name: 'V-LOOK',
+        exported: true,
+      });
+    });
+
+    it('should return CodeNode[] for objects', () => {
+      const code = '<OBJECT BRASS-LANTERN (DESC "brass lantern")>';
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]).toMatchObject({
+        type: 'const', // Objects map to const
+        name: 'BRASS-LANTERN',
+      });
+    });
+
+    it('should return CodeNode[] for globals', () => {
+      const code = '<GLOBAL SCORE 0>';
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]).toMatchObject({
+        type: 'const',
+        name: 'SCORE',
+      });
+    });
+
+    it('should include line numbers', () => {
+      const code = `
+<ROUTINE V-LOOK ()
+  <TELL "text">>
+`;
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.startLine).toBe(2);
+      expect(nodes[0]?.endLine).toBeGreaterThanOrEqual(3);
+    });
+
+    it('should include signature for routines', () => {
+      const code = '<ROUTINE V-TAKE (OBJ) <TELL "Taking">>';
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(1);
+      expect(nodes[0]?.signature).toContain('V-TAKE');
+      expect(nodes[0]?.signature).toContain('OBJ');
+    });
+
+    it('should parse multiple symbols', () => {
+      const code = `
+<CONSTANT M-BEG 1>
+<GLOBAL SCORE 0>
+<ROUTINE V-LOOK ()>
+<OBJECT LAMP>
+`;
+      const nodes = adapter.parse(code, 'test.zil');
+
+      expect(nodes).toHaveLength(4);
+    });
+  });
+
+  describe('extractImports', () => {
+    it('should return ImportInfo[] for INSERT-FILE', () => {
+      const code = '<INSERT-FILE "GMACROS" T>';
+      const imports = adapter.extractImports(code, 'test.zil');
+
+      expect(imports).toHaveLength(1);
+      expect(imports[0]).toMatchObject({
+        source: 'GMACROS',
+        specifiers: [],
+        isType: false,
+      });
+    });
+
+    it('should extract multiple imports', () => {
+      const code = `
+<INSERT-FILE "GMACROS" T>
+<INSERT-FILE "PARSER" T>
+`;
+      const imports = adapter.extractImports(code, 'test.zil');
+
+      expect(imports).toHaveLength(2);
+      expect(imports.map((i) => i.source)).toEqual(['GMACROS', 'PARSER']);
+    });
+
+    it('should return empty array when no imports', () => {
+      const code = '<ROUTINE V-LOOK ()>';
+      const imports = adapter.extractImports(code, 'test.zil');
+
+      expect(imports).toEqual([]);
+    });
+  });
+
+  describe('chunk', () => {
+    it('should chunk by top-level forms', () => {
+      const code = `<ROUTINE V-LOOK ()
+  <TELL "text">>
+
+<OBJECT LAMP
+  (DESC "lamp")>`;
+
+      const chunks = adapter.chunk?.(code, 'test.zil');
+
+      expect(chunks).toBeDefined();
+      expect(chunks).toHaveLength(2);
+    });
+
+    it('should include symbol metadata in chunks', () => {
+      const code = '<ROUTINE V-LOOK () <TELL "text">>';
+      const chunks = adapter.chunk?.(code, 'test.zil');
+
+      expect(chunks).toHaveLength(1);
+      expect(chunks?.[0]).toMatchObject({
+        symbolName: 'V-LOOK',
+        symbolKind: 'routine',
+      });
+    });
+
+    it('should preserve original content in chunks', () => {
+      const code = '<ROUTINE V-LOOK () <TELL "text">>';
+      const chunks = adapter.chunk?.(code, 'test.zil');
+
+      expect(chunks?.[0]?.content).toContain('ROUTINE');
+      expect(chunks?.[0]?.content).toContain('V-LOOK');
+    });
+  });
+
+  describe('analyzeCallRelationships', () => {
+    it('should return GraphEdge[] for calls', () => {
+      const code = '<ROUTINE V-LOOK () <V-DESCRIBE>>';
+      const edges = adapter.analyzeCallRelationships?.(code, 'test.zil');
+
+      expect(edges).toBeDefined();
+      expect(edges?.length).toBeGreaterThan(0);
+
+      const callEdge = edges?.find((e) => e.type === 'calls');
+      expect(callEdge).toBeDefined();
+      expect(callEdge?.to).toContain('V-DESCRIBE');
+    });
+
+    it('should not include special forms as calls', () => {
+      const code = '<ROUTINE TEST () <COND (<EQUAL? 1 1> <RTRUE>)>>';
+      const edges = adapter.analyzeCallRelationships?.(code, 'test.zil');
+
+      const callees = edges?.map((e) => e.to) ?? [];
+      expect(callees).not.toContain('COND');
+      expect(callees).not.toContain('EQUAL?');
+      expect(callees).not.toContain('RTRUE');
+    });
+
+    it('should set caller as from field', () => {
+      const code = '<ROUTINE V-LOOK () <MY-HELPER>>';
+      const edges = adapter.analyzeCallRelationships?.(code, 'test.zil');
+
+      expect(edges?.[0]?.from).toContain('V-LOOK');
+    });
+  });
+});

package/src/analysis/zil/zil-adapter.ts

@@ -0,0 +1,121 @@
+/**
+ * ZIL Language Adapter
+ *
+ * Implements LanguageAdapter for ZIL (Zork Implementation Language).
+ * Provides full graph support: parsing, imports, chunking, and call analysis.
+ */
+
+import { ZilParser } from './zil-parser.js';
+import type { CodeNode, ImportInfo } from '../ast-parser.js';
+import type { GraphEdge } from '../code-graph.js';
+import type { LanguageAdapter, ChunkResult } from '../language-adapter.js';
+
+/**
+ * Language adapter for ZIL (Zork Implementation Language)
+ */
+export class ZilAdapter implements LanguageAdapter {
+  readonly languageId = 'zil';
+  readonly extensions = ['.zil', '.mud'];
+  readonly displayName = 'ZIL (Zork Implementation Language)';
+
+  private readonly parser = new ZilParser();
+
+  /**
+   * Parse ZIL code and extract symbols as CodeNode[]
+   */
+  parse(content: string, _filePath: string): CodeNode[] {
+    const result = this.parser.parse(content);
+
+    return result.symbols.map((symbol) => {
+      const node: CodeNode = {
+        type: this.mapSymbolKindToNodeType(symbol.kind),
+        name: symbol.name,
+        exported: true, // ZIL doesn't have export concept, treat all as exported
+        startLine: symbol.startLine,
+        endLine: symbol.endLine,
+      };
+
+      if (symbol.signature !== undefined) {
+        node.signature = symbol.signature;
+      }
+
+      return node;
+    });
+  }
+
+  /**
+   * Extract imports from INSERT-FILE directives
+   */
+  extractImports(content: string, _filePath: string): ImportInfo[] {
+    const result = this.parser.parse(content);
+    return result.imports;
+  }
+
+  /**
+   * Chunk ZIL code by top-level forms
+   */
+  chunk(content: string, _filePath: string): ChunkResult[] {
+    const result = this.parser.parse(content);
+    const lines = content.split('\n');
+
+    return result.forms
+      .filter((form) => form.head !== '') // Skip empty forms
+      .map((form) => {
+        // Extract content from original source using line numbers
+        const chunkLines = lines.slice(form.startLine - 1, form.endLine);
+        const chunkContent = chunkLines.join('\n');
+
+        // Find symbol for this form if it's a definition
+        const symbol = result.symbols.find(
+          (s) => s.startLine === form.startLine && s.endLine === form.endLine
+        );
+
+        const chunk: ChunkResult = {
+          content: chunkContent,
+          startLine: form.startLine,
+          endLine: form.endLine,
+        };
+
+        if (symbol !== undefined) {
+          chunk.symbolName = symbol.name;
+          chunk.symbolKind = symbol.kind;
+        }
+
+        return chunk;
+      });
+  }
+
+  /**
+   * Analyze call relationships within ZIL code
+   */
+  analyzeCallRelationships(content: string, filePath: string): GraphEdge[] {
+    const result = this.parser.parse(content);
+
+    return result.calls.map((call) => ({
+      from: `${filePath}:${call.caller}`,
+      to: `${filePath}:${call.callee}`,
+      type: 'calls' as const,
+      confidence: 0.9, // High confidence for ZIL - calls are explicit
+    }));
+  }
+
+  /**
+   * Map ZIL symbol kinds to CodeNode types
+   */
+  private mapSymbolKindToNodeType(kind: string): CodeNode['type'] {
+    switch (kind) {
+      case 'routine':
+        return 'function';
+      case 'object':
+      case 'room':
+      case 'global':
+      case 'constant':
+        return 'const';
+      case 'syntax':
+      case 'verb':
+        return 'const';
+      default:
+        return 'const';
+    }
+  }
+}

package/src/analysis/zil/zil-lexer.test.ts

@@ -0,0 +1,222 @@
+import { describe, it, expect } from 'vitest';
+import { ZilLexer, TokenType, type Token } from './zil-lexer.js';
+
+describe('ZilLexer', () => {
+  const lexer = new ZilLexer();
+
+  describe('basic tokens', () => {
+    it('should tokenize angle brackets', () => {
+      const tokens = lexer.tokenize('<>');
+      expect(tokens).toHaveLength(2);
+      expect(tokens[0]).toMatchObject({ type: TokenType.LANGLE, value: '<' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.RANGLE, value: '>' });
+    });
+
+    it('should tokenize parentheses', () => {
+      const tokens = lexer.tokenize('()');
+      expect(tokens).toHaveLength(2);
+      expect(tokens[0]).toMatchObject({ type: TokenType.LPAREN, value: '(' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.RPAREN, value: ')' });
+    });
+
+    it('should tokenize atoms (symbols)', () => {
+      const tokens = lexer.tokenize('ROUTINE');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ROUTINE' });
+    });
+
+    it('should tokenize atoms with special characters', () => {
+      const tokens = lexer.tokenize('EQUAL? FSET? IN?');
+      expect(tokens).toHaveLength(3);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'EQUAL?' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.ATOM, value: 'FSET?' });
+      expect(tokens[2]).toMatchObject({ type: TokenType.ATOM, value: 'IN?' });
+    });
+
+    it('should tokenize atoms with hyphens', () => {
+      const tokens = lexer.tokenize('V-LOOK BRASS-LANTERN');
+      expect(tokens).toHaveLength(2);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'V-LOOK' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.ATOM, value: 'BRASS-LANTERN' });
+    });
+  });
+
+  describe('strings', () => {
+    it('should tokenize simple strings', () => {
+      const tokens = lexer.tokenize('"Hello, World!"');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.STRING, value: 'Hello, World!' });
+    });
+
+    it('should tokenize strings with escaped quotes', () => {
+      const tokens = lexer.tokenize('"He said \\"Hello\\""');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.STRING, value: 'He said "Hello"' });
+    });
+
+    it('should tokenize strings with escaped backslashes', () => {
+      const tokens = lexer.tokenize('"path\\\\to\\\\file"');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.STRING, value: 'path\\to\\file' });
+    });
+
+    it('should tokenize empty strings', () => {
+      const tokens = lexer.tokenize('""');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.STRING, value: '' });
+    });
+  });
+
+  describe('numbers', () => {
+    it('should tokenize positive integers', () => {
+      const tokens = lexer.tokenize('42');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.NUMBER, value: '42' });
+    });
+
+    it('should tokenize negative integers', () => {
+      const tokens = lexer.tokenize('-10');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.NUMBER, value: '-10' });
+    });
+
+    it('should tokenize zero', () => {
+      const tokens = lexer.tokenize('0');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.NUMBER, value: '0' });
+    });
+  });
+
+  describe('comments', () => {
+    it('should skip line comments starting with semicolon', () => {
+      const tokens = lexer.tokenize('; This is a comment\nATOM');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM' });
+    });
+
+    it('should handle inline comments', () => {
+      const tokens = lexer.tokenize('ATOM ; inline comment');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM' });
+    });
+
+    it('should handle multiple comment lines', () => {
+      const tokens = lexer.tokenize('; comment 1\n; comment 2\nATOM');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM' });
+    });
+  });
+
+  describe('whitespace', () => {
+    it('should skip whitespace between tokens', () => {
+      const tokens = lexer.tokenize('  ATOM1   ATOM2  ');
+      expect(tokens).toHaveLength(2);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM1' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM2' });
+    });
+
+    it('should handle tabs and newlines', () => {
+      const tokens = lexer.tokenize('ATOM1\t\nATOM2');
+      expect(tokens).toHaveLength(2);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM1' });
+      expect(tokens[1]).toMatchObject({ type: TokenType.ATOM, value: 'ATOM2' });
+    });
+  });
+
+  describe('complex expressions', () => {
+    it('should tokenize a simple routine', () => {
+      const code = '<ROUTINE V-LOOK ()>';
+      const tokens = lexer.tokenize(code);
+      expect(tokens).toHaveLength(6);
+      expect(tokens.map((t) => t.type)).toEqual([
+        TokenType.LANGLE,
+        TokenType.ATOM,
+        TokenType.ATOM,
+        TokenType.LPAREN,
+        TokenType.RPAREN,
+        TokenType.RANGLE,
+      ]);
+    });
+
+    it('should tokenize nested forms', () => {
+      const code = '<COND (<EQUAL? ,FOO 1> <TELL "One">)>';
+      const tokens = lexer.tokenize(code);
+
+      // Verify key tokens are present
+      const types = tokens.map((t) => t.type);
+      expect(types).toContain(TokenType.LANGLE);
+      expect(types).toContain(TokenType.ATOM);
+      expect(types).toContain(TokenType.STRING);
+      expect(types).toContain(TokenType.NUMBER);
+    });
+
+    it('should tokenize INSERT-FILE directive', () => {
+      const code = '<INSERT-FILE "GMACROS" T>';
+      const tokens = lexer.tokenize(code);
+      expect(tokens).toHaveLength(5);
+      expect(tokens[1]).toMatchObject({ type: TokenType.ATOM, value: 'INSERT-FILE' });
+      expect(tokens[2]).toMatchObject({ type: TokenType.STRING, value: 'GMACROS' });
+      expect(tokens[3]).toMatchObject({ type: TokenType.ATOM, value: 'T' });
+    });
+
+    it('should tokenize OBJECT definition', () => {
+      const code = '<OBJECT BRASS-LANTERN (DESC "brass lantern") (FLAGS LIGHTBIT)>';
+      const tokens = lexer.tokenize(code);
+
+      expect(tokens.find((t) => t.value === 'OBJECT')).toBeDefined();
+      expect(tokens.find((t) => t.value === 'BRASS-LANTERN')).toBeDefined();
+      expect(tokens.find((t) => t.value === 'brass lantern')).toBeDefined();
+    });
+  });
+
+  describe('line tracking', () => {
+    it('should track line numbers', () => {
+      const code = 'ATOM1\nATOM2\nATOM3';
+      const tokens = lexer.tokenize(code);
+
+      expect(tokens[0]?.line).toBe(1);
+      expect(tokens[1]?.line).toBe(2);
+      expect(tokens[2]?.line).toBe(3);
+    });
+
+    it('should track column numbers', () => {
+      const code = '  ATOM';
+      const tokens = lexer.tokenize(code);
+
+      expect(tokens[0]?.column).toBe(3); // 1-based, after 2 spaces
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty input', () => {
+      const tokens = lexer.tokenize('');
+      expect(tokens).toEqual([]);
+    });
+
+    it('should handle only whitespace', () => {
+      const tokens = lexer.tokenize('   \n\t  ');
+      expect(tokens).toEqual([]);
+    });
+
+    it('should handle only comments', () => {
+      const tokens = lexer.tokenize('; comment only');
+      expect(tokens).toEqual([]);
+    });
+
+    it('should throw on unterminated string', () => {
+      expect(() => lexer.tokenize('"unterminated')).toThrow('Unterminated string');
+    });
+
+    it('should handle comma prefix (global reference)', () => {
+      const tokens = lexer.tokenize(',FOO');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: ',FOO' });
+    });
+
+    it('should handle period prefix (local reference)', () => {
+      const tokens = lexer.tokenize('.BAR');
+      expect(tokens).toHaveLength(1);
+      expect(tokens[0]).toMatchObject({ type: TokenType.ATOM, value: '.BAR' });
+    });
+  });
+});