bluera-knowledge 0.10.1 → 0.11.0

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

@@ -0,0 +1,360 @@
+/**
+ * ZIL Parser
+ *
+ * Parses ZIL source code into an AST-like structure and extracts:
+ * - Symbols (ROUTINE, OBJECT, ROOM, GLOBAL, CONSTANT, SYNTAX)
+ * - Imports (INSERT-FILE)
+ * - Call relationships (filtering out special forms)
+ */
+
+import { ZilLexer, TokenType, type Token } from './zil-lexer.js';
+import { isSpecialForm, isDefinitionForm } from './zil-special-forms.js';
+import type { ImportInfo } from '../ast-parser.js';
+
+/**
+ * A ZIL form node (angle-bracket expression)
+ */
+export interface ZilForm {
+  /** The head/operator of the form (first atom after <) */
+  head: string;
+  /** Child nodes (atoms, strings, numbers, nested forms) */
+  children: ZilNode[];
+  /** Starting line number */
+  startLine: number;
+  /** Ending line number */
+  endLine: number;
+}
+
+/**
+ * A parenthesized group (used for args lists)
+ */
+export interface ZilGroup {
+  type: 'group';
+  children: ZilNode[];
+  startLine: number;
+  endLine: number;
+}
+
+/**
+ * A leaf node (atom, string, or number)
+ */
+export interface ZilLeaf {
+  type: 'atom' | 'string' | 'number';
+  value: string;
+  line: number;
+}
+
+export type ZilNode = ZilForm | ZilGroup | ZilLeaf;
+
+/**
+ * Extracted symbol from ZIL code
+ */
+export interface ZilSymbol {
+  name: string;
+  kind: 'routine' | 'object' | 'room' | 'global' | 'constant' | 'syntax' | 'verb';
+  startLine: number;
+  endLine: number;
+  signature?: string;
+}
+
+/**
+ * A function call extracted from ZIL code
+ */
+export interface ZilCall {
+  caller: string;
+  callee: string;
+  line: number;
+}
+
+/**
+ * Result of parsing a ZIL file
+ */
+export interface ZilParseResult {
+  forms: ZilForm[];
+  symbols: ZilSymbol[];
+  imports: ImportInfo[];
+  calls: ZilCall[];
+}
+
+/**
+ * Parser for ZIL source code
+ */
+export class ZilParser {
+  private readonly lexer = new ZilLexer();
+  private tokens: Token[] = [];
+  private pos = 0;
+
+  /**
+   * Parse ZIL source code
+   */
+  parse(input: string): ZilParseResult {
+    this.tokens = this.lexer.tokenize(input);
+    this.pos = 0;
+
+    const forms: ZilForm[] = [];
+    const symbols: ZilSymbol[] = [];
+    const imports: ImportInfo[] = [];
+    const calls: ZilCall[] = [];
+
+    // Parse all top-level forms
+    while (!this.isAtEnd()) {
+      if (this.check(TokenType.LANGLE)) {
+        const form = this.parseForm();
+        if (form !== undefined) {
+          forms.push(form);
+
+          // Extract symbols from definition forms
+          const symbol = this.extractSymbol(form);
+          if (symbol !== undefined) {
+            symbols.push(symbol);
+          }
+
+          // Extract imports from INSERT-FILE
+          const imp = this.extractImport(form);
+          if (imp !== undefined) {
+            imports.push(imp);
+          }
+
+          // Extract calls from routines
+          if (form.head.toUpperCase() === 'ROUTINE') {
+            const routineName = this.getRoutineName(form);
+            if (routineName !== undefined) {
+              this.extractCalls(form, routineName, calls);
+            }
+          }
+        }
+      } else {
+        // Skip non-form tokens at top level
+        this.advance();
+      }
+    }
+
+    return { forms, symbols, imports, calls };
+  }
+
+  private isAtEnd(): boolean {
+    return this.pos >= this.tokens.length;
+  }
+
+  private peek(): Token | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private check(type: TokenType): boolean {
+    if (this.isAtEnd()) return false;
+    return this.peek()?.type === type;
+  }
+
+  private advance(): Token | undefined {
+    if (!this.isAtEnd()) {
+      const token = this.tokens[this.pos];
+      this.pos++;
+      return token;
+    }
+    return undefined;
+  }
+
+  private parseForm(): ZilForm | undefined {
+    if (!this.check(TokenType.LANGLE)) return undefined;
+
+    const startToken = this.advance(); // consume <
+    const startLine = startToken?.line ?? 1;
+    let endLine = startLine;
+
+    // Get the head (first element)
+    let head = '';
+    if (this.check(TokenType.ATOM)) {
+      head = this.advance()?.value ?? '';
+    }
+
+    const children: ZilNode[] = [];
+
+    // Parse children until >
+    while (!this.isAtEnd() && !this.check(TokenType.RANGLE)) {
+      const child = this.parseNode();
+      if (child !== undefined) {
+        children.push(child);
+        endLine = this.getNodeEndLine(child);
+      } else {
+        // Skip unexpected tokens
+        this.advance();
+      }
+    }
+
+    if (this.check(TokenType.RANGLE)) {
+      const closeToken = this.advance();
+      endLine = closeToken?.line ?? endLine;
+    }
+
+    return { head, children, startLine, endLine };
+  }
+
+  private parseGroup(): ZilGroup | undefined {
+    if (!this.check(TokenType.LPAREN)) return undefined;
+
+    const startToken = this.advance(); // consume (
+    const startLine = startToken?.line ?? 1;
+    let endLine = startLine;
+
+    const children: ZilNode[] = [];
+
+    while (!this.isAtEnd() && !this.check(TokenType.RPAREN)) {
+      const child = this.parseNode();
+      if (child !== undefined) {
+        children.push(child);
+        endLine = this.getNodeEndLine(child);
+      } else {
+        this.advance();
+      }
+    }
+
+    if (this.check(TokenType.RPAREN)) {
+      const closeToken = this.advance();
+      endLine = closeToken?.line ?? endLine;
+    }
+
+    return { type: 'group', children, startLine, endLine };
+  }
+
+  private parseNode(): ZilNode | undefined {
+    const token = this.peek();
+    if (token === undefined) return undefined;
+
+    switch (token.type) {
+      case TokenType.LANGLE:
+        return this.parseForm();
+      case TokenType.LPAREN:
+        return this.parseGroup();
+      case TokenType.ATOM:
+        this.advance();
+        return { type: 'atom', value: token.value, line: token.line };
+      case TokenType.STRING:
+        this.advance();
+        return { type: 'string', value: token.value, line: token.line };
+      case TokenType.NUMBER:
+        this.advance();
+        return { type: 'number', value: token.value, line: token.line };
+      default:
+        return undefined;
+    }
+  }
+
+  private getNodeEndLine(node: ZilNode): number {
+    if ('endLine' in node) {
+      return node.endLine;
+    }
+    return node.line;
+  }
+
+  private extractSymbol(form: ZilForm): ZilSymbol | undefined {
+    const headUpper = form.head.toUpperCase();
+
+    if (!isDefinitionForm(headUpper)) {
+      return undefined;
+    }
+
+    // Get the name (first child that's an atom)
+    const nameNode = form.children.find((c): c is ZilLeaf => 'type' in c && c.type === 'atom');
+
+    if (nameNode === undefined) {
+      return undefined;
+    }
+
+    const kindMap: Record<string, ZilSymbol['kind']> = {
+      ROUTINE: 'routine',
+      OBJECT: 'object',
+      ROOM: 'room',
+      GLOBAL: 'global',
+      CONSTANT: 'constant',
+      SYNTAX: 'syntax',
+      VERB: 'verb',
+      DEFINE: 'routine',
+      DEFMAC: 'routine',
+    };
+
+    const kind = kindMap[headUpper];
+    if (kind === undefined) {
+      return undefined;
+    }
+
+    const result: ZilSymbol = {
+      name: nameNode.value,
+      kind,
+      startLine: form.startLine,
+      endLine: form.endLine,
+    };
+
+    if (headUpper === 'ROUTINE' || headUpper === 'DEFINE' || headUpper === 'DEFMAC') {
+      result.signature = this.extractRoutineSignature(form, nameNode.value);
+    }
+
+    return result;
+  }
+
+  private extractRoutineSignature(form: ZilForm, name: string): string {
+    // Find args group (first parenthesized group after name)
+    const argsGroup = form.children.find((c): c is ZilGroup => 'type' in c && c.type === 'group');
+
+    if (argsGroup === undefined) {
+      return `ROUTINE ${name} ()`;
+    }
+
+    const args = argsGroup.children
+      .filter((c): c is ZilLeaf => 'type' in c && c.type === 'atom')
+      .map((c) => c.value)
+      .join(' ');
+
+    return `ROUTINE ${name} (${args})`;
+  }
+
+  private extractImport(form: ZilForm): ImportInfo | undefined {
+    if (form.head.toUpperCase() !== 'INSERT-FILE') {
+      return undefined;
+    }
+
+    // Get the file name (first string child)
+    const fileNode = form.children.find((c): c is ZilLeaf => 'type' in c && c.type === 'string');
+
+    if (fileNode === undefined) {
+      return undefined;
+    }
+
+    return {
+      source: fileNode.value,
+      specifiers: [],
+      isType: false,
+    };
+  }
+
+  private getRoutineName(form: ZilForm): string | undefined {
+    const nameNode = form.children.find((c): c is ZilLeaf => 'type' in c && c.type === 'atom');
+    return nameNode?.value;
+  }
+
+  private extractCalls(node: ZilNode, caller: string, calls: ZilCall[]): void {
+    if ('head' in node) {
+      // It's a form
+      const headUpper = node.head.toUpperCase();
+
+      // If not a special form and not empty, it's a call
+      if (node.head !== '' && !isSpecialForm(headUpper)) {
+        calls.push({
+          caller,
+          callee: node.head,
+          line: node.startLine,
+        });
+      }
+
+      // Recurse into children
+      for (const child of node.children) {
+        this.extractCalls(child, caller, calls);
+      }
+    } else if ('type' in node && node.type === 'group') {
+      // Recurse into group children
+      for (const child of node.children) {
+        this.extractCalls(child, caller, calls);
+      }
+    }
+    // Leaf nodes don't contain calls
+  }
+}

package/src/analysis/zil/zil-special-forms.ts

@@ -0,0 +1,193 @@
+/**
+ * ZIL Special Forms and Builtins
+ *
+ * These are NOT treated as function calls when building the call graph.
+ * Special forms are control flow, assignment, and predicates.
+ * Builtins are runtime primitives.
+ */
+
+/**
+ * Special forms - language-level constructs, not function calls
+ */
+export const ZIL_SPECIAL_FORMS = new Set([
+  // Conditionals
+  'COND',
+  'AND',
+  'OR',
+  'NOT',
+  'IF',
+  'ELSE',
+
+  // Assignment
+  'SET',
+  'SETG',
+  'BIND',
+  'PROG',
+
+  // Loops
+  'REPEAT',
+  'DO',
+  'MAP',
+  'MAPF',
+  'MAPR',
+  'MAPRET',
+  'MAPLEAVE',
+
+  // Output
+  'TELL',
+  'PRINT',
+  'PRINTN',
+  'PRINTD',
+  'PRINTC',
+  'PRINTR',
+  'CRLF',
+
+  // Control flow
+  'RETURN',
+  'AGAIN',
+  'RTRUE',
+  'RFALSE',
+  'QUIT',
+
+  // Predicates (end with ?)
+  'EQUAL?',
+  'ZERO?',
+  'LESS?',
+  'GRTR?',
+  'FSET?',
+  'IN?',
+  'VERB?',
+  'PRSO?',
+  'PRSI?',
+  'HELD?',
+  'HERE?',
+  'ACCESSIBLE?',
+  'VISIBLE?',
+  'FIRST?',
+  'NEXT?',
+  'PROB?',
+  'RANDOM',
+
+  // Property/flag manipulation
+  'FSET',
+  'FCLEAR',
+  'GETP',
+  'PUTP',
+  'GETPT',
+  'PTSIZE',
+
+  // Object manipulation
+  'MOVE',
+  'REMOVE',
+  'LOC',
+  'FIRST',
+  'NEXT',
+
+  // Arithmetic
+  'ADD',
+  'SUB',
+  'MUL',
+  'DIV',
+  'MOD',
+  'BAND',
+  'BOR',
+  'BCOM',
+  'LSH',
+
+  // Table operations
+  'GET',
+  'PUT',
+  'GETB',
+  'PUTB',
+  'TABLE',
+  'ITABLE',
+  'LTABLE',
+  'PTABLE',
+
+  // Stack operations
+  'PUSH',
+  'POP',
+  'FSTACK',
+
+  // Input
+  'READ',
+  'INPUT',
+  'READLINE',
+
+  // Definition forms (handled separately for symbol extraction)
+  'ROUTINE',
+  'OBJECT',
+  'ROOM',
+  'GLOBAL',
+  'CONSTANT',
+  'SYNTAX',
+  'INSERT-FILE',
+
+  // Misc builtins
+  'VERSION?',
+  'ASCII',
+  'USL',
+  'APPLY',
+  'EVAL',
+  'FORM',
+  'REST',
+  'LENGTH',
+  'NTH',
+  'ZGET',
+  'ZPUT',
+  'ZWSTR',
+  'DIROUT',
+  'DIRIN',
+  'BUFOUT',
+  'HLIGHT',
+  'COLOR',
+  'FONT',
+  'SPLIT',
+  'SCREEN',
+  'WINGET',
+  'WINPUT',
+  'WINATTR',
+  'PICINF',
+  'DISPLAY',
+  'DCLEAR',
+  'SOUND',
+  'INTBL?',
+  'CATCH',
+  'THROW',
+  'LEGAL?',
+  'COPYT',
+  'VALUE',
+  'GASSIGNED?',
+  'ASSIGNED?',
+  'DEFINE',
+  'DEFMAC',
+]);
+
+/**
+ * Check if a form head is a special form or builtin
+ */
+export function isSpecialForm(name: string): boolean {
+  return ZIL_SPECIAL_FORMS.has(name.toUpperCase());
+}
+
+/**
+ * Definition forms that create symbols
+ */
+export const ZIL_DEFINITION_FORMS = new Set([
+  'ROUTINE',
+  'OBJECT',
+  'ROOM',
+  'GLOBAL',
+  'CONSTANT',
+  'SYNTAX',
+  'VERB',
+  'DEFINE',
+  'DEFMAC',
+]);
+
+/**
+ * Check if a form head is a definition form
+ */
+export function isDefinitionForm(name: string): boolean {
+  return ZIL_DEFINITION_FORMS.has(name.toUpperCase());
+}

package/src/index.ts

@@ -3,6 +3,8 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { Command } from 'commander';
+import { AdapterRegistry } from './analysis/adapter-registry.js';
+import { ZilAdapter } from './analysis/zil/index.js';
 import { createCrawlCommand } from './cli/commands/crawl.js';
 import { createIndexCommand } from './cli/commands/index-cmd.js';
 import { createMCPCommand } from './cli/commands/mcp.js';
@@ -19,6 +21,10 @@ import { createStoreCommand } from './cli/commands/store.js';
 import { createSyncCommand } from './cli/commands/sync.js';
 import { createProgram, getGlobalOptions } from './cli/program.js';
 
+// Register built-in language adapters
+const registry = AdapterRegistry.getInstance();
+registry.register(new ZilAdapter());
+
 // Default paths
 const DEFAULT_DATA_DIR = join(homedir(), '.bluera', 'bluera-knowledge', 'data');
 const DEFAULT_CONFIG = join(homedir(), '.bluera', 'bluera-knowledge', 'config.json');

package/src/mcp/server.ts

@@ -1,15 +1,23 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { AdapterRegistry } from '../analysis/adapter-registry.js';
+import { ZilAdapter } from '../analysis/zil/index.js';
+import { createLogger } from '../logging/index.js';
 import { createServices } from '../services/index.js';
 import { handleExecute } from './handlers/execute.handler.js';
 import { tools } from './handlers/index.js';
 import { ExecuteArgsSchema } from './schemas/index.js';
-import { createLogger } from '../logging/index.js';
 import type { MCPServerOptions } from './types.js';
 
 const logger = createLogger('mcp-server');
 
+// Register built-in language adapters
+const registry = AdapterRegistry.getInstance();
+if (!registry.hasExtension('.zil')) {
+  registry.register(new ZilAdapter());
+}
+
 // eslint-disable-next-line @typescript-eslint/no-deprecated
 export function createMCPServer(options: MCPServerOptions): Server {
   // eslint-disable-next-line @typescript-eslint/no-deprecated