/** * CodeGraph Type Definitions * * Core types for the semantic knowledge graph system. */ // ============================================================================= // Union Types // ============================================================================= /** * Types of nodes in the knowledge graph. * * Defined as a runtime-iterable `as const` array so the same source * of truth backs both the TS type and any runtime validation * (e.g. the search query parser). */ export const NODE_KINDS = [ 'file', 'module', 'class', 'struct', 'interface', 'trait', 'protocol', 'function', 'method', 'property', 'field', 'variable', 'constant', 'enum', 'enum_member', 'type_alias', 'namespace', 'parameter', 'import', 'export', 'route', 'component', ] as const; export type NodeKind = (typeof NODE_KINDS)[number]; /** * Types of edges (relationships) between nodes */ export type EdgeKind = | 'contains' // Parent contains child (file→class, class→method) | 'calls' // Function/method calls another | 'imports' // File imports from another | 'exports' // File exports a symbol | 'extends' // Class/interface extends another | 'implements' // Class implements interface | 'references' // Generic reference to another symbol | 'type_of' // Variable/parameter has type | 'returns' // Function returns type | 'instantiates' // Creates instance of class | 'overrides' // Method overrides parent method | 'decorates'; // Decorator applied to symbol /** * Supported programming languages. See NODE_KINDS for why this is a * runtime-iterable const array. */ export const LANGUAGES = [ 'typescript', 'javascript', 'tsx', 'jsx', 'python', 'go', 'rust', 'java', 'c', 'cpp', 'csharp', 'php', 'ruby', 'swift', 'kotlin', 'dart', 'svelte', 'vue', 'liquid', 'pascal', 'scala', 'lua', 'luau', 'unknown', ] as const; export type Language = (typeof LANGUAGES)[number]; // ============================================================================= // Core Graph Types // ============================================================================= /** * A node in the knowledge graph representing a code symbol */ export interface Node { /** Unique identifier (hash of file path + qualified name) */ id: string; /** Type of code element */ kind: NodeKind; /** Simple name (e.g., "calculateTotal") */ name: string; /** Fully qualified name (e.g., "src/utils.ts::MathHelper.calculateTotal") */ qualifiedName: string; /** File path relative to project root */ filePath: string; /** Programming language */ language: Language; /** Starting line number (1-indexed) */ startLine: number; /** Ending line number (1-indexed) */ endLine: number; /** Starting column (0-indexed) */ startColumn: number; /** Ending column (0-indexed) */ endColumn: number; /** Documentation string if present */ docstring?: string; /** Function/method signature */ signature?: string; /** Visibility modifier */ visibility?: 'public' | 'private' | 'protected' | 'internal'; /** Whether symbol is exported */ isExported?: boolean; /** Whether symbol is async */ isAsync?: boolean; /** Whether symbol is static */ isStatic?: boolean; /** Whether symbol is abstract */ isAbstract?: boolean; /** Decorators/annotations applied */ decorators?: string[]; /** Generic type parameters */ typeParameters?: string[]; /** When the node was last updated */ updatedAt: number; } /** * An edge representing a relationship between two nodes */ export interface Edge { /** Source node ID */ source: string; /** Target node ID */ target: string; /** Type of relationship */ kind: EdgeKind; /** Additional context about the relationship */ metadata?: Record; /** Line number where relationship occurs (e.g., call site) */ line?: number; /** Column number where relationship occurs */ column?: number; /** How this edge was created */ provenance?: 'tree-sitter' | 'scip' | 'heuristic'; } /** * Metadata about a tracked file */ export interface FileRecord { /** File path relative to project root */ path: string; /** Content hash for change detection */ contentHash: string; /** Detected language */ language: Language; /** File size in bytes */ size: number; /** Last modification timestamp */ modifiedAt: number; /** When last indexed */ indexedAt: number; /** Number of nodes extracted */ nodeCount: number; /** Any extraction errors */ errors?: ExtractionError[]; } // ============================================================================= // Extraction Types // ============================================================================= /** * Result from parsing a source file */ export interface ExtractionResult { /** Extracted nodes */ nodes: Node[]; /** Extracted edges */ edges: Edge[]; /** References that couldn't be resolved yet */ unresolvedReferences: UnresolvedReference[]; /** Any errors during extraction */ errors: ExtractionError[]; /** Extraction duration in milliseconds */ durationMs: number; } /** * Error during code extraction */ export interface ExtractionError { /** Error message */ message: string; /** File path where the error occurred */ filePath?: string; /** Line number if available */ line?: number; /** Column number if available */ column?: number; /** Error severity */ severity: 'error' | 'warning'; /** Error code for categorization */ code?: string; } /** * A reference that couldn't be resolved during extraction */ export interface UnresolvedReference { /** ID of the node containing the reference */ fromNodeId: string; /** Name being referenced */ referenceName: string; /** Type of reference (call, type, import, etc.) */ referenceKind: EdgeKind; /** Location of the reference */ line: number; column: number; /** File path where reference occurs (denormalized for performance) */ filePath?: string; /** Language of the source file (denormalized for performance) */ language?: Language; /** Possible qualified names it might resolve to */ candidates?: string[]; } // ============================================================================= // Query Types // ============================================================================= /** * A subgraph containing a subset of the knowledge graph */ export interface Subgraph { /** Nodes in this subgraph */ nodes: Map; /** Edges in this subgraph */ edges: Edge[]; /** Root node IDs (entry points) */ roots: string[]; } /** * Options for graph traversal */ export interface TraversalOptions { /** Maximum depth to traverse (default: Infinity) */ maxDepth?: number; /** Edge types to follow (default: all) */ edgeKinds?: EdgeKind[]; /** Node types to include (default: all) */ nodeKinds?: NodeKind[]; /** Direction of traversal */ direction?: 'outgoing' | 'incoming' | 'both'; /** Maximum nodes to return */ limit?: number; /** Whether to include the starting node */ includeStart?: boolean; } /** * Options for searching the graph */ export interface SearchOptions { /** Node types to search */ kinds?: NodeKind[]; /** Languages to include */ languages?: Language[]; /** File path patterns to include */ includePatterns?: string[]; /** File path patterns to exclude */ excludePatterns?: string[]; /** Maximum results to return */ limit?: number; /** Offset for pagination */ offset?: number; /** Whether search is case-sensitive */ caseSensitive?: boolean; } /** * A search result with relevance scoring */ export interface SearchResult { /** Matching node */ node: Node; /** Relevance score (0-1) */ score: number; /** Matched text snippets for highlighting */ highlights?: string[]; } // ============================================================================= // Context Types // ============================================================================= /** * Context information for code understanding */ export interface Context { /** Primary node being examined */ focal: Node; /** Nodes containing the focal node (file, class, etc.) */ ancestors: Node[]; /** Nodes directly contained by focal node */ children: Node[]; /** Incoming references (who calls/uses this) */ incomingRefs: Array<{ node: Node; edge: Edge }>; /** Outgoing references (what this calls/uses) */ outgoingRefs: Array<{ node: Node; edge: Edge }>; /** Related type information */ types: Node[]; /** Relevant imports */ imports: Node[]; } /** * A block of code with context */ export interface CodeBlock { /** The code content */ content: string; /** File path */ filePath: string; /** Starting line */ startLine: number; /** Ending line */ endLine: number; /** Language for syntax highlighting */ language: Language; /** Associated node if extracted */ node?: Node; } // ============================================================================= // Configuration Types // ============================================================================= /** * Framework-specific hints for better extraction */ export interface FrameworkHint { /** Framework name (react, express, django, etc.) */ name: string; /** Version constraint if relevant */ version?: string; /** Custom patterns for this framework */ patterns?: { /** Component detection patterns */ components?: string[]; /** Route detection patterns */ routes?: string[]; /** Model detection patterns */ models?: string[]; }; } /** * Configuration for a CodeGraph project */ export interface CodeGraphConfig { /** Schema version for migrations */ version: number; /** Root directory of the project */ rootDir: string; /** Glob patterns for files to include */ include: string[]; /** Glob patterns for files to exclude */ exclude: string[]; /** Languages to process (auto-detected if empty) */ languages: Language[]; /** Framework hints for better extraction */ frameworks: FrameworkHint[]; /** Maximum file size to process (in bytes) */ maxFileSize: number; /** Whether to extract docstrings */ extractDocstrings: boolean; /** Whether to track call sites */ trackCallSites: boolean; /** Custom symbol patterns to extract */ customPatterns?: { /** Name for this pattern group */ name: string; /** Regex pattern to match */ pattern: string; /** Node kind to assign */ kind: NodeKind; }[]; } /** * Default configuration values */ export const DEFAULT_CONFIG: CodeGraphConfig = { version: 1, rootDir: '.', include: [ // TypeScript/JavaScript '**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', // Python '**/*.py', // Go '**/*.go', // Rust '**/*.rs', // Java '**/*.java', // C/C++ '**/*.c', '**/*.h', '**/*.cpp', '**/*.hpp', '**/*.cc', '**/*.cxx', // C# '**/*.cs', // PHP '**/*.php', // Ruby '**/*.rb', // Swift '**/*.swift', // Kotlin '**/*.kt', '**/*.kts', // Dart '**/*.dart', // Svelte '**/*.svelte', // Vue '**/*.vue', // Liquid (Shopify themes) '**/*.liquid', // Pascal / Delphi '**/*.pas', '**/*.dpr', '**/*.dpk', '**/*.lpr', '**/*.dfm', '**/*.fmx', // Scala '**/*.scala', '**/*.sc', // Lua '**/*.lua', // Luau '**/*.luau', ], exclude: [ // Version control '**/.git/**', // Dependencies '**/node_modules/**', '**/vendor/**', '**/Pods/**', // Generic build outputs '**/dist/**', '**/build/**', '**/out/**', '**/bin/**', '**/obj/**', '**/target/**', // JavaScript/TypeScript '**/*.min.js', '**/*.bundle.js', '**/.next/**', '**/.nuxt/**', '**/.svelte-kit/**', '**/.output/**', '**/.turbo/**', '**/.cache/**', '**/.parcel-cache/**', '**/.vite/**', '**/.astro/**', '**/.docusaurus/**', '**/.gatsby/**', '**/.webpack/**', '**/.nx/**', '**/.yarn/cache/**', '**/.pnpm-store/**', '**/storybook-static/**', // React Native / Expo '**/.expo/**', '**/web-build/**', '**/ios/Pods/**', '**/ios/build/**', '**/android/build/**', '**/android/.gradle/**', // Python '**/__pycache__/**', '**/.venv/**', '**/venv/**', '**/site-packages/**', '**/dist-packages/**', '**/.pytest_cache/**', '**/.mypy_cache/**', '**/.ruff_cache/**', '**/.tox/**', '**/.nox/**', '**/*.egg-info/**', '**/.eggs/**', // Go '**/go/pkg/mod/**', // Rust '**/target/debug/**', '**/target/release/**', // Java/Kotlin/Gradle '**/.gradle/**', '**/.m2/**', '**/generated-sources/**', '**/.kotlin/**', // Dart/Flutter '**/.dart_tool/**', // C#/.NET '**/.vs/**', '**/.nuget/**', '**/artifacts/**', '**/publish/**', // C/C++ '**/cmake-build-*/**', '**/CMakeFiles/**', '**/bazel-*/**', '**/vcpkg_installed/**', '**/.conan/**', '**/Debug/**', '**/Release/**', '**/x64/**', '**/.pio/**', // Platform.io (IoT/embedded build artifacts and library deps) // Electron '**/release/**', '**/*.app/**', '**/*.asar', // Swift/iOS/Xcode '**/DerivedData/**', '**/.build/**', '**/.swiftpm/**', '**/xcuserdata/**', '**/Carthage/Build/**', '**/SourcePackages/**', // Delphi/Pascal '**/__history/**', '**/__recovery/**', '**/*.dcu', // PHP '**/.composer/**', '**/storage/framework/**', '**/bootstrap/cache/**', // Ruby '**/.bundle/**', '**/tmp/cache/**', '**/public/assets/**', '**/public/packs/**', '**/.yardoc/**', // Testing/Coverage '**/coverage/**', '**/htmlcov/**', '**/.nyc_output/**', '**/test-results/**', '**/.coverage/**', // IDE/Editor '**/.idea/**', // Logs and temp '**/logs/**', '**/tmp/**', '**/temp/**', // Documentation build output '**/_build/**', '**/docs/_build/**', '**/site/**', ], languages: [], frameworks: [], maxFileSize: 1024 * 1024, // 1MB extractDocstrings: true, trackCallSites: true, }; // ============================================================================= // Database Types // ============================================================================= /** * Database schema version info */ export interface SchemaVersion { /** Current schema version */ version: number; /** When schema was created/updated */ appliedAt: number; /** Description of this version */ description?: string; } /** * Statistics about the knowledge graph */ export interface GraphStats { /** Total number of nodes */ nodeCount: number; /** Total number of edges */ edgeCount: number; /** Number of tracked files */ fileCount: number; /** Node counts by kind */ nodesByKind: Record; /** Edge counts by kind */ edgesByKind: Record; /** File counts by language */ filesByLanguage: Record; /** Database size in bytes */ dbSizeBytes: number; /** Last update timestamp */ lastUpdated: number; } // ============================================================================= // Task Context Types (for buildContext) // ============================================================================= /** * Input for building task context */ export type TaskInput = string | { title: string; description?: string }; /** * Options for building task context */ export interface BuildContextOptions { /** Maximum number of nodes to include (default: 50) */ maxNodes?: number; /** Maximum number of code blocks to include (default: 10) */ maxCodeBlocks?: number; /** Maximum characters per code block (default: 2000) */ maxCodeBlockSize?: number; /** Whether to include code blocks (default: true) */ includeCode?: boolean; /** Output format (default: 'markdown') */ format?: 'markdown' | 'json'; /** Number of semantic search results (default: 5) */ searchLimit?: number; /** Graph traversal depth from entry points (default: 2) */ traversalDepth?: number; /** Minimum semantic similarity score (default: 0.3) */ minScore?: number; } /** * Full context for a task, ready for Claude */ export interface TaskContext { /** The original query/task */ query: string; /** Subgraph of relevant nodes and edges */ subgraph: Subgraph; /** Entry point nodes (from semantic search) */ entryPoints: Node[]; /** Code blocks extracted from key nodes */ codeBlocks: CodeBlock[]; /** Files involved in this context */ relatedFiles: string[]; /** Brief summary of the context */ summary: string; /** Statistics about the context */ stats: { /** Number of nodes included */ nodeCount: number; /** Number of edges included */ edgeCount: number; /** Number of files touched */ fileCount: number; /** Number of code blocks included */ codeBlockCount: number; /** Total characters in code blocks */ totalCodeSize: number; }; } /** * Options for finding relevant context */ export interface FindRelevantContextOptions { /** Number of semantic search results (default: 5) */ searchLimit?: number; /** Graph traversal depth (default: 2) */ traversalDepth?: number; /** Maximum nodes in result (default: 50) */ maxNodes?: number; /** Minimum semantic similarity score (default: 0.3) */ minScore?: number; /** Edge types to follow in traversal */ edgeKinds?: EdgeKind[]; /** Node types to include */ nodeKinds?: NodeKind[]; }