LSP/Index Engineer

// Use these as canonical schema definitions for graphd
interface GraphNode {
  id: string;        // "file:src/foo.ts" or "sym:foo#method"
  kind: 'file' | 'module' | 'class' | 'function' | 'variable' | 'type';
  file?: string;     // Parent file path
  range?: Range;     // LSP Range for symbol location
  detail?: string;   // Type signature or brief description
}

interface GraphEdge {
  id: string;        // "edge:uuid"
  source: string;    // Node ID
  target: string;    // Node ID
  type: 'contains' | 'imports' | 'extends' | 'implements' | 'calls' | 'references';
  weight?: number;   // For importance/frequency
}

# Install language servers
npm install -g typescript-language-server typescript
npm install -g intelephense        # PHP
npm install -g gopls               # Go
npm install -g rust-analyzer       # Rust
npm install -g pyright             # Python

# Verify a server starts and responds (TypeScript example)
echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"capabilities":{},"rootUri":null,"processId":null}}' \
  | typescript-language-server --stdio

class LSPOrchestrator {
  private clients = new Map<string, LanguageClient>();
  private capabilities = new Map<string, ServerCapabilities>();

  async initialize(projectRoot: string): Promise<void> {
    const servers = [
      { lang: 'typescript', command: 'typescript-language-server', args: ['--stdio'] },
      { lang: 'php',        command: 'intelephense',               args: ['--stdio'] },
    ];

    await Promise.all(servers.map(({ lang, command, args }) =>
      this.initializeClient(lang, new LanguageClient(lang, { command, args, rootPath: projectRoot }))
    ));
  }

  private async initializeClient(lang: string, client: LanguageClient): Promise<void> {
    const result = await client.sendRequest('initialize', {
      processId: process.pid,
      rootUri: `file://${client.rootPath}`,
      capabilities: {},
    });
    // ✅ Validation: store capabilities before any further requests
    this.capabilities.set(lang, result.capabilities);
    this.clients.set(lang, client);
    await client.sendNotification('initialized', {});
  }

  async getDefinition(uri: string, position: Position): Promise<Location[]> {
    const lang = this.detectLanguage(uri);
    const cap = this.capabilities.get(lang);
    if (!cap?.definitionProvider) return []; // capability check before request
    return this.clients.get(lang)!.sendRequest('textDocument/definition', {
      textDocument: { uri },
      position,
    });
  }
}

class GraphBuilder {
  async buildFromProject(root: string): Promise<Graph> {
    const graph = new Graph();

    // Phase 1 & 2: Collect files and create file nodes
    const files = await glob('**/*.{ts,tsx,js,jsx,php}', { cwd: root });
    for (const file of files) {
      graph.addNode({ id: `file:${file}`, kind: 'file', path: file });
    }
    // ✅ Validation: all file nodes must exist before symbol nodes are added

    // Phase 3: Extract symbols via LSP (parallel)
    await Promise.all(files.map(async (file) => {
      const symbols = await this.extractSymbols(file); // calls textDocument/documentSymbol
      for (const sym of symbols) {
        graph.addNode({ id: `sym:${sym.name}`, kind: sym.kind, file, range: sym.range });
        graph.addEdge({ source: `file:${file}`, target: `sym:${sym.name}`, type: 'contains' });
      }
    }));
    // ✅ Validation: assert every symbol node's `file` references a known file node

    // Phase 4: Resolve cross-file references and call edges
    await this.resolveReferences(graph); // calls textDocument/references per symbol
    // ✅ Validation: assert all edge source/target IDs exist in graph.nodes

    return graph;
  }
}

function assertGraphConsistency(graph: Graph): void {
  for (const edge of graph.edges.values()) {
    if (!graph.nodes.has(edge.source)) throw new Error(`Missing source node: ${edge.source}`);
    if (!graph.nodes.has(edge.target)) throw new Error(`Missing target node: ${edge.target}`);
  }
}

{"symId":"sym:AppController","def":{"uri":"file:///src/controllers/app.php","l":10,"c":6}}
{"symId":"sym:AppController","refs":[{"uri":"file:///src/routes.php","l":5,"c":10},{"uri":"file:///tests/app.test.php","l":15,"c":20}]}
{"symId":"sym:AppController","hover":{"contents":{"kind":"markdown","value":"```php\nclass AppController extends BaseController\n```\nMain application controller"}}}
{"symId":"sym:useState","def":{"uri":"file:///node_modules/react/index.d.ts","l":1234,"c":17}}
{"symId":"sym:useState","refs":[{"uri":"file:///src/App.tsx","l":3,"c":10},{"uri":"file:///src/components/Header.tsx","l":2,"c":10}]}