@optave/codegraph 3.6.0 → 3.8.0

package/src/extractors/solidity.ts

@@ -0,0 +1,398 @@
+import type {
+  Call,
+  ExtractorOutput,
+  SubDeclaration,
+  TreeSitterNode,
+  TreeSitterTree,
+} from '../types.js';
+import {
+  extractModifierVisibility,
+  findChild,
+  findParentNode,
+  nodeEndLine,
+  stripQuotes,
+} from './helpers.js';
+
+/**
+ * Extract symbols from Solidity files.
+ *
+ * Solidity's tree-sitter grammar covers contracts, interfaces, libraries,
+ * structs, enums, events, errors, functions, modifiers, and import paths.
+ */
+export function extractSoliditySymbols(tree: TreeSitterTree, _filePath: string): ExtractorOutput {
+  const ctx: ExtractorOutput = {
+    definitions: [],
+    calls: [],
+    imports: [],
+    classes: [],
+    exports: [],
+    typeMap: new Map(),
+  };
+
+  walkSolidityNode(tree.rootNode, ctx);
+  return ctx;
+}
+
+function walkSolidityNode(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  switch (node.type) {
+    case 'contract_declaration':
+      handleContractDecl(node, ctx, 'class');
+      break;
+    case 'interface_declaration':
+      handleContractDecl(node, ctx, 'interface');
+      break;
+    case 'library_declaration':
+      handleContractDecl(node, ctx, 'module');
+      break;
+    case 'struct_declaration':
+      handleStructDecl(node, ctx);
+      break;
+    case 'enum_declaration':
+      handleEnumDecl(node, ctx);
+      break;
+    case 'function_definition':
+      handleFunctionDef(node, ctx);
+      break;
+    case 'modifier_definition':
+      handleModifierDef(node, ctx);
+      break;
+    case 'event_definition':
+      handleEventDef(node, ctx);
+      break;
+    case 'error_declaration':
+      handleErrorDecl(node, ctx);
+      break;
+    case 'state_variable_declaration':
+      handleStateVarDecl(node, ctx);
+      break;
+    case 'import_directive':
+      handleImportDirective(node, ctx);
+      break;
+    case 'call_expression':
+    case 'function_call':
+      handleCallExpression(node, ctx);
+      break;
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) walkSolidityNode(child, ctx);
+  }
+}
+
+// ── Handlers ───────────────────────────────────────────────────────────────
+
+const SOL_PARENT_TYPES = [
+  'contract_declaration',
+  'interface_declaration',
+  'library_declaration',
+] as const;
+
+function handleContractDecl(
+  node: TreeSitterNode,
+  ctx: ExtractorOutput,
+  kind: 'class' | 'interface' | 'module',
+): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const name = nameNode.text;
+
+  const members: SubDeclaration[] = [];
+  const body = node.childForFieldName('body') || findChild(node, 'contract_body');
+  if (body) {
+    for (let i = 0; i < body.childCount; i++) {
+      const child = body.child(i);
+      if (!child) continue;
+      if (child.type === 'function_definition') {
+        const fnName = child.childForFieldName('name');
+        if (fnName) {
+          members.push({ name: fnName.text, kind: 'method', line: child.startPosition.row + 1 });
+        }
+      } else if (child.type === 'state_variable_declaration') {
+        const varName = child.childForFieldName('name');
+        if (varName) {
+          members.push({
+            name: varName.text,
+            kind: 'property',
+            line: child.startPosition.row + 1,
+            visibility: extractSolVisibility(child),
+          });
+        }
+      } else if (child.type === 'event_definition') {
+        const evName = child.childForFieldName('name');
+        if (evName) {
+          members.push({
+            name: evName.text,
+            kind: 'property',
+            decorators: ['event'],
+            line: child.startPosition.row + 1,
+          });
+        }
+      } else if (child.type === 'error_declaration') {
+        const errName = child.childForFieldName('name');
+        if (errName) {
+          members.push({
+            name: errName.text,
+            kind: 'property',
+            decorators: ['error'],
+            line: child.startPosition.row + 1,
+          });
+        }
+      } else if (child.type === 'modifier_definition') {
+        const modName = child.childForFieldName('name');
+        if (modName) {
+          members.push({
+            name: modName.text,
+            kind: 'method',
+            decorators: ['modifier'],
+            line: child.startPosition.row + 1,
+          });
+        }
+      }
+    }
+  }
+
+  ctx.definitions.push({
+    name,
+    kind,
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: members.length > 0 ? members : undefined,
+  });
+
+  // Inheritance
+  const inheritance = findChild(node, 'inheritance_specifier');
+  if (inheritance) {
+    for (let i = 0; i < inheritance.childCount; i++) {
+      const child = inheritance.child(i);
+      if (!child) continue;
+      if (child.type === 'user_defined_type' || child.type === 'identifier') {
+        ctx.classes.push({ name, extends: child.text, line: node.startPosition.row + 1 });
+      }
+    }
+  }
+}
+
+function handleStructDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+
+  const members: SubDeclaration[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && child.type === 'struct_member') {
+      const memberName = child.childForFieldName('name');
+      if (memberName) {
+        members.push({
+          name: memberName.text,
+          kind: 'property',
+          line: child.startPosition.row + 1,
+        });
+      }
+    }
+  }
+
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'struct',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: members.length > 0 ? members : undefined,
+  });
+}
+
+function handleEnumDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+
+  const members: SubDeclaration[] = [];
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && child.type === 'enum_value') {
+      members.push({ name: child.text, kind: 'constant', line: child.startPosition.row + 1 });
+    }
+  }
+
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'enum',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: members.length > 0 ? members : undefined,
+  });
+}
+
+function handleFunctionDef(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+  const kind = parent ? 'method' : 'function';
+
+  const params = extractSolParams(node);
+  ctx.definitions.push({
+    name: fullName,
+    kind,
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: params.length > 0 ? params : undefined,
+    visibility: extractSolVisibility(node),
+  });
+}
+
+function handleModifierDef(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'function',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    decorators: ['modifier'],
+  });
+}
+
+function handleEventDef(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'type',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    decorators: ['event'],
+  });
+}
+
+function handleErrorDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'type',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    decorators: ['error'],
+  });
+}
+
+function handleStateVarDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+  const parent = findParentNode(node, SOL_PARENT_TYPES);
+  const fullName = parent ? `${parent}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'variable',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    visibility: extractSolVisibility(node),
+  });
+}
+
+function handleImportDirective(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // import "path"; or import { X } from "path"; or import "path" as Alias;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === 'string' || child.type === 'string_literal') {
+      const source = stripQuotes(child.text);
+      const names: string[] = [];
+      // Look for imported symbols
+      for (let j = 0; j < node.childCount; j++) {
+        const sibling = node.child(j);
+        if (sibling && sibling.type === 'identifier') names.push(sibling.text);
+        if (sibling && sibling.type === 'import_declaration') {
+          const id = findChild(sibling, 'identifier');
+          if (id) names.push(id.text);
+        }
+      }
+      ctx.imports.push({
+        source,
+        names: names.length > 0 ? names : ['*'],
+        line: node.startPosition.row + 1,
+      });
+      return;
+    }
+    // source_import: handles `import * as X from "path"`
+    if (child.type === 'source_import' || child.type === 'import_clause') {
+      const strNode = findChild(child, 'string') || findChild(child, 'string_literal');
+      if (strNode) {
+        ctx.imports.push({
+          source: stripQuotes(strNode.text),
+          names: ['*'],
+          line: node.startPosition.row + 1,
+        });
+        return;
+      }
+    }
+  }
+}
+
+function handleCallExpression(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const funcNode = node.childForFieldName('function') || node.childForFieldName('callee');
+  if (!funcNode) return;
+
+  const call: Call = { name: '', line: node.startPosition.row + 1 };
+  if (funcNode.type === 'member_expression' || funcNode.type === 'member_access') {
+    const prop = funcNode.childForFieldName('property') || funcNode.childForFieldName('member');
+    const obj = funcNode.childForFieldName('object') || funcNode.childForFieldName('expression');
+    if (prop) call.name = prop.text;
+    if (obj) call.receiver = obj.text;
+  } else {
+    call.name = funcNode.text;
+  }
+  if (call.name) ctx.calls.push(call);
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function extractSolParams(funcNode: TreeSitterNode): SubDeclaration[] {
+  const params: SubDeclaration[] = [];
+  const paramList =
+    funcNode.childForFieldName('parameters') || findChild(funcNode, 'parameter_list');
+  if (!paramList) return params;
+
+  for (let i = 0; i < paramList.childCount; i++) {
+    const param = paramList.child(i);
+    if (!param || param.type !== 'parameter') continue;
+    const nameNode = param.childForFieldName('name');
+    if (nameNode) {
+      params.push({ name: nameNode.text, kind: 'parameter', line: param.startPosition.row + 1 });
+    }
+  }
+  return params;
+}
+
+function extractSolVisibility(
+  node: TreeSitterNode,
+): 'public' | 'private' | 'protected' | undefined {
+  // Solidity visibility is embedded as child keywords or visibility nodes
+  const vis = extractModifierVisibility(node);
+  if (vis) return vis;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    const t = child.text;
+    if (t === 'public' || t === 'external') return 'public';
+    if (t === 'private') return 'private';
+    if (t === 'internal') return 'protected';
+  }
+  return undefined;
+}

package/src/extractors/verilog.ts

@@ -0,0 +1,315 @@
+import type { ExtractorOutput, SubDeclaration, TreeSitterNode, TreeSitterTree } from '../types.js';
+import { findChild, nodeEndLine } from './helpers.js';
+
+/**
+ * Extract symbols from Verilog/SystemVerilog files.
+ *
+ * The tree-sitter-verilog grammar covers modules, interfaces, packages,
+ * tasks, functions, classes, always blocks, and instantiations.
+ */
+export function extractVerilogSymbols(tree: TreeSitterTree, _filePath: string): ExtractorOutput {
+  const ctx: ExtractorOutput = {
+    definitions: [],
+    calls: [],
+    imports: [],
+    classes: [],
+    exports: [],
+    typeMap: new Map(),
+  };
+
+  walkVerilogNode(tree.rootNode, ctx);
+  return ctx;
+}
+
+function walkVerilogNode(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  switch (node.type) {
+    case 'module_declaration':
+      handleModuleDecl(node, ctx);
+      break;
+    case 'interface_declaration':
+      handleInterfaceDecl(node, ctx);
+      break;
+    case 'package_declaration':
+      handlePackageDecl(node, ctx);
+      break;
+    case 'class_declaration':
+      handleClassDecl(node, ctx);
+      break;
+    case 'function_declaration':
+      handleFunctionDecl(node, ctx);
+      break;
+    case 'task_declaration':
+      handleTaskDecl(node, ctx);
+      break;
+    case 'module_instantiation':
+      handleModuleInstantiation(node, ctx);
+      break;
+    case 'package_import_declaration':
+      handlePackageImport(node, ctx);
+      break;
+    case 'include_compiler_directive':
+      handleIncludeDirective(node, ctx);
+      break;
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child) walkVerilogNode(child, ctx);
+  }
+}
+
+// ── Handlers ───────────────────────────────────────────────────────────────
+
+function handleModuleDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findModuleName(node);
+  if (!nameNode) return;
+
+  const ports = extractPorts(node);
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'module',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+    children: ports.length > 0 ? ports : undefined,
+  });
+}
+
+function handleInterfaceDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findDeclName(node);
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'interface',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handlePackageDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findDeclName(node);
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'module',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleClassDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = node.childForFieldName('name');
+  if (!nameNode) return;
+
+  ctx.definitions.push({
+    name: nameNode.text,
+    kind: 'class',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+
+  // Superclass via extends
+  const superclass = node.childForFieldName('superclass');
+  if (superclass) {
+    ctx.classes.push({
+      name: nameNode.text,
+      extends: superclass.text,
+      line: node.startPosition.row + 1,
+    });
+  }
+}
+
+function handleFunctionDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findFunctionOrTaskName(node, 'function_identifier');
+  if (!nameNode) return;
+
+  const parentModule = findVerilogParent(node);
+  const fullName = parentModule ? `${parentModule}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'function',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleTaskDecl(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  const nameNode = findFunctionOrTaskName(node, 'task_identifier');
+  if (!nameNode) return;
+
+  const parentModule = findVerilogParent(node);
+  const fullName = parentModule ? `${parentModule}.${nameNode.text}` : nameNode.text;
+
+  ctx.definitions.push({
+    name: fullName,
+    kind: 'function',
+    line: node.startPosition.row + 1,
+    endLine: nodeEndLine(node),
+  });
+}
+
+function handleModuleInstantiation(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // Module instantiations are like function calls: `ModuleName instance_name(...);`
+  const moduleType = node.childForFieldName('type') || node.child(0);
+  if (!moduleType) return;
+
+  ctx.calls.push({
+    name: moduleType.text,
+    line: node.startPosition.row + 1,
+  });
+}
+
+function handlePackageImport(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // import pkg::item; or import pkg::*;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === 'package_import_item') {
+      const text = child.text;
+      const parts = text.split('::');
+      const pkg = parts[0] ?? text;
+      const item = parts[1] ?? '*';
+      ctx.imports.push({
+        source: pkg,
+        names: [item],
+        line: node.startPosition.row + 1,
+      });
+    }
+  }
+}
+
+function handleIncludeDirective(node: TreeSitterNode, ctx: ExtractorOutput): void {
+  // `include "file.vh"
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'string_literal' || child.type === 'quoted_string')) {
+      const source = child.text.replace(/^["']|["']$/g, '');
+      ctx.imports.push({
+        source,
+        names: [source.split('/').pop() ?? source],
+        line: node.startPosition.row + 1,
+        cInclude: true,
+      });
+      return;
+    }
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function findModuleName(node: TreeSitterNode): TreeSitterNode | null {
+  // Try field name first, then look for module_header > identifier
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return nameNode;
+
+  const header = findChild(node, 'module_header');
+  if (header) {
+    const id = findChild(header, 'simple_identifier') || findChild(header, 'identifier');
+    if (id) return id;
+  }
+
+  // Direct child identifier after `module` keyword
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'simple_identifier' || child.type === 'identifier')) return child;
+  }
+  return null;
+}
+
+function findDeclName(node: TreeSitterNode): TreeSitterNode | null {
+  const nameNode = node.childForFieldName('name');
+  if (nameNode) return nameNode;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child && (child.type === 'simple_identifier' || child.type === 'identifier')) return child;
+  }
+  return null;
+}
+
+/**
+ * Find a function or task name by searching for the dedicated identifier node
+ * type (e.g. `function_identifier`, `task_identifier`) recursively through
+ * body declarations.  Falls back to `findDeclName` for grammars that use
+ * plain identifiers.
+ */
+function findFunctionOrTaskName(
+  node: TreeSitterNode,
+  identifierType: string,
+): TreeSitterNode | null {
+  // Try the standard approach first
+  const simple = findDeclName(node);
+  if (simple) return simple;
+
+  // Search children (including body declarations) for the dedicated identifier node
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    if (child.type === identifierType) return child;
+    // Look one level deeper into body declarations
+    for (let j = 0; j < child.childCount; j++) {
+      const grandchild = child.child(j);
+      if (grandchild && grandchild.type === identifierType) return grandchild;
+    }
+  }
+  return null;
+}
+
+function findVerilogParent(node: TreeSitterNode): string | null {
+  let current = node.parent;
+  while (current) {
+    if (
+      current.type === 'module_declaration' ||
+      current.type === 'interface_declaration' ||
+      current.type === 'package_declaration' ||
+      current.type === 'class_declaration'
+    ) {
+      const name = findDeclName(current) || findModuleName(current);
+      return name ? name.text : null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
+function extractPorts(moduleNode: TreeSitterNode): SubDeclaration[] {
+  const ports: SubDeclaration[] = [];
+
+  // Look for port declarations in the module header or body
+  const collectFromNode = (node: TreeSitterNode): void => {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+
+      if (
+        child.type === 'ansi_port_declaration' ||
+        child.type === 'port_declaration' ||
+        child.type === 'input_declaration' ||
+        child.type === 'output_declaration' ||
+        child.type === 'inout_declaration'
+      ) {
+        const nameNode =
+          child.childForFieldName('name') ||
+          findChild(child, 'simple_identifier') ||
+          findChild(child, 'identifier');
+        if (nameNode) {
+          ports.push({ name: nameNode.text, kind: 'property', line: child.startPosition.row + 1 });
+        }
+      }
+
+      // Recurse into port list containers
+      if (
+        child.type === 'list_of_port_declarations' ||
+        child.type === 'module_header' ||
+        child.type === 'port_declaration_list'
+      ) {
+        collectFromNode(child);
+      }
+    }
+  };
+
+  collectFromNode(moduleNode);
+  return ports;
+}