CodeGraph Node and Edge Types: Complete Schema Reference

CodeGraph extracts 22 distinct node types (including file, class, function, route, and component) and 12 edge types (including contains, calls, extends, and imports) defined in src/types.ts to build a semantic knowledge graph of your codebase.

CodeGraph, developed by colbymchenry/codegraph, transforms source code repositories into queryable semantic knowledge graphs. Understanding the specific node and edge types the tool extracts is essential for writing accurate traversal queries and extending the extraction logic. This guide details every symbol kind and relationship type defined in the core type system, as implemented in the src/types.ts file.

Node Types (Symbol Kinds) in CodeGraph

CodeGraph represents code entities as typed nodes in the graph. The exhaustive enumeration of supported node kinds is defined as the runtime-constant NODE_KINDS array in src/types.ts (lines 18-41).

Complete List of Supported Node Kinds

The NODE_KINDS constant defines 22 distinct symbol types that CodeGraph can extract from any supported language:

export const NODE_KINDS = [
  'file',      // a source file
  'module',    // an ES module or similar container
  'class',     // class declaration
  'struct',    // Rust struct, C struct, etc.
  'interface', // TypeScript / Java interface
  'trait',     // Rust trait
  'protocol',  // Objective‑C / Swift protocol
  'function',  // top‑level function
  'method',    // class/struct method
  'property',  // class/struct field exposed as a property
  'field',     // low‑level struct field
  'variable',  // local or global variable
  'constant',  // const / enum member
  'enum',      // enum declaration
  'enum_member',
  'type_alias',
  'namespace',
  'parameter',
  'import',
  'export',
  'route',     // web routing entry (e.g., Express, Laravel)
  'component'  // UI component (React, Vue, Svelte, etc.)
] as const;

Each string literal represents a NodeKind that the extraction engine identifies during parsing. The 'route' and 'component' kinds are framework-specific extensions that capture web application structure, while 'trait' and 'protocol' handle language-specific abstraction mechanisms.

Edge Types (Relationship Kinds) in CodeGraph

Relationships between code symbols are stored as typed edges. The EdgeKind union type in src/types.ts (lines 48-60) serves as the single source of truth for all graph connections.

Relationship Types Defined in EdgeKind

CodeGraph records 12 distinct relationship types:

export type EdgeKind =
  | 'contains'        // parent → child (file contains class, class contains method)
  | 'calls'           // function/method invokes another
  | 'imports'         // file imports a symbol
  | 'exports'         // file exports a symbol
  | 'extends'         // class/interface extends another
  | 'implements'      // class implements an interface/trait
  | 'references'      // generic reference (type usage, variable access)
  | 'type_of'         // variable/parameter has a type
  | 'returns'         // function returns a type
  | 'instantiates'    // new X() creates an instance of a class
  | 'overrides'       // method overrides a parent method
  | 'decorates';      // decorator/annotation applied to a symbol

The 'contains' edge establishes hierarchical containment (e.g., a file containing a class, or a class containing methods). 'Calls' edges form the function call graph, while 'references' captures generic dependencies like variable reads or type usages.

How CodeGraph Uses These Types

These type definitions are not merely documentation; they drive the extraction pipeline, storage schema, and query API.

Extraction Pipeline

In src/extraction/index.ts, the Tree‑Sitter-based parser creates Node and Edge objects using only the kinds enumerated in src/types.ts. The extraction engine maps language‑specific AST nodes to these canonical types during the indexing phase.

Storage Schema

The SQLite database defined in src/db/schema.sql stores nodes and edges in tables with a kind column that aligns strictly with the NODE_KINDS and EdgeKind definitions. This ensures type safety across persistence and retrieval operations.

Query API

The graph traversal layer in src/graph/index.ts exposes methods like getAllNodes() and getOutgoingEdges() that rely on these type definitions. When querying, you filter results by passing specific EdgeKind values to retrieve precise relationship patterns.

Practical Usage Example

After indexing a project, you can inspect which node and edge types are present and query specific relationships:

import { CodeGraph } from 'codegraph';
import { NodeKind, EdgeKind } from './src/types';

// Initialize the graph
const cg = new CodeGraph();

// Enumerate all node kinds present in the indexed project
const nodeKinds = new Set<string>();
for (const node of cg.getAllNodes()) {
  nodeKinds.add(node.kind);
}
console.log('Node kinds in this project:', Array.from(nodeKinds));

// Find all 'calls' edges from a specific function
const fnNode = cg.getNodeByQualifiedName('src/utils.ts::calculateTotal');
const callEdges = cg.getOutgoingEdges(fnNode.id, ['calls'] as EdgeKind[]);
console.log(`"${fnNode.name}" calls ${callEdges.length} other symbols`);

This example demonstrates importing the core CodeGraph class, iterating over nodes to collect distinct kinds, and using getOutgoingEdges() with a filtered EdgeKind array to retrieve call relationships.

Summary

• CodeGraph defines 22 node types in the NODE_KINDS constant at src/types.ts, covering symbols from file and module to framework‑specific types like route and component.
• 12 edge types are defined in the EdgeKind union type, capturing relationships including contains, calls, extends, and decorates.
• The type system serves as the single source of truth for the src/extraction/index.ts pipeline, the src/db/schema.sql storage layer, and the src/graph/index.ts query API.
• Use getAllNodes() to iterate over symbols and getOutgoingEdges() with specific EdgeKind filters to traverse relationships in the graph.

Frequently Asked Questions

What is the difference between a 'property' and 'field' node type in CodeGraph?

According to the NODE_KINDS definition in src/types.ts, 'property' represents class or struct fields exposed as higher‑level properties (typically with getter/setter semantics), while 'field' refers to low‑level struct fields without abstraction overhead. The extraction engine in src/extraction/index.ts distinguishes these based on language‑specific AST patterns during parsing.

How does CodeGraph handle language-specific constructs like Rust traits or Swift protocols?

CodeGraph maps language‑specific constructs to canonical node types defined in src/types.ts. 'Trait' captures Rust traits, while 'protocol' handles Objective‑C and Swift protocols. Similarly, Rust and C structs are normalized to the 'struct' node kind. This abstraction allows the graph schema to remain consistent across multi‑language repositories while preserving semantic meaning through precise type labeling.

Where are the node and edge type definitions stored in the codebase?

The authoritative definitions reside in src/types.ts. Lines 18‑41 contain the NODE_KINDS array enumerating all node types, and lines 48‑60 define the EdgeKind union type for relationships. These definitions are referenced by src/extraction/index.ts (creation), src/db/schema.sql (storage), and src/graph/index.ts (querying).

How can I query specific relationship types using the CodeGraph API?

Use the getOutgoingEdges() method exposed in src/graph/index.ts, passing an array of specific EdgeKind values as the second argument. For example, passing ['calls'] filters edges to show only function invocations, while ['extends', 'implements'] retrieves inheritance hierarchies. The method signature accepts EdgeKind[] to type‑check valid relationship filters at compile time.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}