Type Definitions

This page documents all public TypeScript types exported from the @code-rag/core package. These types are used across the MCP server, REST API, CLI, and viewer.

Note: > All types are defined with TypeScript strict mode. The project uses the Result<T, E> pattern from neverthrow for error handling instead of thrown exceptions.

Chunk Types

Chunks are the fundamental unit of indexed code in CodeRAG. Each chunk represents a semantically meaningful piece of code (a function, class, interface, etc.) extracted via Tree-sitter AST parsing.

Source: packages/core/src/types/chunk.ts

Chunk

interface Chunk {
  /** Unique identifier for the chunk (hash-based). */
  id: string;
  /** Raw source code content. */
  content: string;
  /** Natural language summary generated by LLM before embedding. */
  nlSummary: string;
  /** Relative file path from project root. */
  filePath: string;
  /** Start line number (1-based). */
  startLine: number;
  /** End line number (1-based, inclusive). */
  endLine: number;
  /** Programming language of the chunk. */
  language: string;
  /** Structured metadata about the chunk. */
  metadata: ChunkMetadata;
  /** Embedding vector (populated after embedding phase). */
  embedding?: number[];
}

ChunkWithEmbedding

/** A Chunk that is guaranteed to have an embedding vector. */
interface ChunkWithEmbedding extends Chunk {
  embedding: number[];
}

ChunkMetadata

interface ChunkMetadata {
  /** Type of code construct this chunk represents. */
  chunkType: ChunkType;
  /** Name of the symbol (function name, class name, etc.). */
  name: string;
  /** Parent symbol name (e.g., class name for a method). */
  parentName?: string;
  /** Symbols declared in this chunk. */
  declarations: string[];
  /** Imported symbols/modules. */
  imports: string[];
  /** Exported symbols. */
  exports: string[];
  /** Repository name (for multi-repo setups). */
  repoName?: string;
  /** Wikilinks extracted from documentation chunks ([[link]] syntax). */
  links?: string[];
  /** Tags extracted from documentation chunks (#tag syntax + frontmatter). */
  tags?: string[];
  /** Aliases from Obsidian frontmatter. */
  aliases?: string[];
  /** Document title from frontmatter. */
  docTitle?: string;
}

ChunkType

type ChunkType =
  | 'function'      // Standalone function
  | 'method'        // Method inside a class
  | 'class'         // Class definition
  | 'module'        // Module-level code
  | 'interface'     // Interface definition
  | 'type_alias'    // Type alias (type Foo = ...)
  | 'config_block'  // Configuration block
  | 'import_block'  // Import statements
  | 'doc';          // Documentation chunk (Markdown, Confluence)

Search Types

Types used by the hybrid search engine and retrieval pipeline.

Source: packages/core/src/types/search.ts

SearchResult

interface SearchResult {
  /** ID of the matched chunk. */
  chunkId: string;
  /** Full Chunk object (may be undefined in sparse results). */
  chunk?: Chunk;
  /** Raw content of the matched chunk. */
  content: string;
  /** Natural language summary. */
  nlSummary: string;
  /** Relevance score (0--1, higher is better). */
  score: number;
  /** Which search method produced this result. */
  method: SearchMethod;
  /** Chunk metadata. */
  metadata: ChunkMetadata;
}

SearchMethod

type SearchMethod = 'vector' | 'bm25' | 'hybrid';

SearchQuery

interface SearchQuery {
  /** The search text. */
  text: string;
  /** Optional filters to narrow results. */
  filters?: SearchFilters;
  /** Optional search behavior options. */
  options?: SearchOptions;
}

SearchFilters

interface SearchFilters {
  /** Filter to specific programming languages. */
  languages?: string[];
  /** Filter to specific file paths. */
  filePaths?: string[];
  /** Filter to specific chunk types. */
  chunkTypes?: ChunkType[];
}

SearchOptions

interface SearchOptions {
  /** Number of results to return. Default: 10 */
  topK?: number;
  /** Weight for vector (semantic) search. Default from config. */
  vectorWeight?: number;
  /** Weight for BM25 (keyword) search. Default from config. */
  bm25Weight?: number;
  /** Whether to expand results via dependency graph. */
  expandGraph?: boolean;
}

Query Analysis Types

Types for the query analysis pipeline that classifies user intent and extracts entities.

Source: packages/core/src/retrieval/query-analyzer.ts

AnalyzedQuery

interface AnalyzedQuery {
  /** The original user query string. */
  originalQuery: string;
  /** Classified intent of the query. */
  intent: QueryIntent;
  /** Extracted entities (symbols, files, concepts). */
  entities: QueryEntity[];
  /** Automatically suggested filters based on query analysis. */
  suggestedFilters: SearchFilters;
  /** Expanded search terms for broader matching. */
  expandedTerms: string[];
}

QueryIntent

type QueryIntent =
  | 'find_definition'    // Looking for where something is defined
  | 'find_usage'         // Looking for where something is used
  | 'understand_module'  // Trying to understand how a module works
  | 'find_similar'       // Looking for similar code patterns
  | 'general';           // General information query

QueryEntity

interface QueryEntity {
  /** Type of entity detected in the query. */
  type: 'function' | 'class' | 'module' | 'file' | 'concept';
  /** The extracted entity value. */
  value: string;
}

Context Expansion Types

Types for the graph-based context expansion pipeline.

Source: packages/core/src/retrieval/context-expander.ts

ExpandedContext

interface ExpandedContext {
  /** Primary search results. */
  primaryResults: SearchResult[];
  /** Related chunks found via dependency graph traversal. */
  relatedChunks: RelatedChunk[];
  /** Excerpt of the dependency graph relevant to these results. */
  graphExcerpt: GraphExcerpt;
}

RelatedChunk

interface RelatedChunk {
  /** The search result for the related chunk. */
  chunk: SearchResult;
  /** How this chunk is related to the primary results. */
  relationship: RelationshipType;
  /** Graph distance from the nearest primary result. */
  distance: number;
}

RelationshipType

type RelationshipType =
  | 'imports'       // This chunk imports from a primary chunk
  | 'imported_by'   // This chunk is imported by a primary chunk
  | 'test_for'      // This chunk is a test for a primary chunk
  | 'interface_of'  // This chunk is an interface implemented by a primary chunk
  | 'sibling';      // This chunk is in the same file as a primary chunk

GraphExcerpt

interface GraphExcerpt {
  /** Node IDs included in the excerpt. */
  nodes: string[];
  /** Edges between included nodes. */
  edges: Array<{ from: string; to: string; type: string }>;
}

AssembledContext

The output of the TokenBudgetOptimizer.

Source: packages/core/src/retrieval/token-budget.ts

interface AssembledContext {
  /** Final assembled context string with formatted sections. */
  content: string;
  /** Primary results that fit within the budget. */
  primaryChunks: SearchResult[];
  /** Related chunks that fit within the budget. */
  relatedChunks: RelatedChunk[];
  /** Estimated total token count of the assembled content. */
  tokenCount: number;
  /** Whether results were truncated to fit the budget. */
  truncated: boolean;
}

Graph Types

Types for the dependency graph that models relationships between code modules.

Source: packages/core/src/graph/dependency-graph.ts

GraphNode

interface GraphNode {
  /** Unique node ID (typically the file path). */
  id: string;
  /** Relative file path. */
  filePath: string;
  /** Symbols declared in this module. */
  symbols: string[];
  /** Type of node. */
  type: 'module' | 'class' | 'function';
}

GraphEdge

interface GraphEdge {
  /** ID of the source node. */
  source: string;
  /** ID of the target node. */
  target: string;
  /** Type of relationship. */
  type: 'imports' | 'extends' | 'implements' | 'calls';
}

Backlog Types

Types for the project backlog integration.

Source: packages/core/src/backlog/types.ts

BacklogItem

interface BacklogItem {
  /** Internal ID. */
  id: string;
  /** Provider-specific ID (e.g., "AB#123", "PROJ-456"). */
  externalId: string;
  /** Item title. */
  title: string;
  /** Full description text. */
  description: string;
  /** Item type. */
  type: BacklogItemType;
  /** Current state (e.g., "New", "Active", "Resolved", "Closed"). */
  state: string;
  /** Assigned user. */
  assignedTo?: string;
  /** Associated tags. */
  tags: string[];
  /** File paths linked to this item. */
  linkedCodePaths: string[];
  /** Web URL to view the item in the provider UI. */
  url?: string;
  /** Provider-specific metadata. */
  metadata: Record<string, unknown>;
}

BacklogItemType

type BacklogItemType = 'epic' | 'story' | 'task' | 'bug' | 'feature';

BacklogQuery

interface BacklogQuery {
  /** Text search filter. */
  text?: string;
  /** Filter by item types. */
  types?: BacklogItemType[];
  /** Filter by states. */
  states?: string[];
  /** Filter by assignee. */
  assignedTo?: string;
  /** Filter by tags. */
  tags?: string[];
  /** Maximum items to return. */
  limit?: number;
}

Configuration Types

Types for the .coderag.yaml configuration file.

Source: packages/core/src/types/config.ts

CodeRAGConfig

The root configuration object parsed from .coderag.yaml.

interface CodeRAGConfig {
  /** Config file version. */
  version: string;
  /** Project metadata. */
  project: ProjectConfig;
  /** Ingestion pipeline settings. */
  ingestion: IngestionConfig;
  /** Embedding provider settings. */
  embedding: EmbeddingConfig;
  /** LLM provider settings (for NL enrichment). */
  llm: LLMConfig;
  /** Search behavior settings. */
  search: SearchConfig;
  /** Storage backend settings. */
  storage: StorageConfig;
  /** Optional re-ranker configuration. */
  reranker?: ReRankerConfig;
  /** Optional multi-repo configuration. */
  repos?: RepoConfig[];
  /** Optional backlog provider configuration. */
  backlog?: BacklogConfig;
}

ProjectConfig

interface ProjectConfig {
  /** Project name. */
  name: string;
  /** Supported languages ("auto" for detection). */
  languages: string[] | 'auto';
}

IngestionConfig

interface IngestionConfig {
  /** Maximum tokens per chunk. */
  maxTokensPerChunk: number;
  /** Glob patterns to exclude from indexing. */
  exclude: string[];
}

EmbeddingConfig

interface EmbeddingConfig {
  /** Provider name (e.g., "ollama", "voyage", "openai"). */
  provider: string;
  /** Model name (e.g., "nomic-embed-text", "voyage-code-3"). */
  model: string;
  /** Embedding vector dimensions. */
  dimensions: number;
}

LLMConfig

interface LLMConfig {
  /** Provider name (e.g., "ollama"). */
  provider: string;
  /** Model name (e.g., "qwen2.5-coder", "llama3.2"). */
  model: string;
}

SearchConfig

interface SearchConfig {
  /** Default number of results. */
  topK: number;
  /** Default weight for vector search (0--1). */
  vectorWeight: number;
  /** Default weight for BM25 search (0--1). */
  bm25Weight: number;
}

StorageConfig

interface StorageConfig {
  /** Relative path to storage directory from project root. */
  path: string;
  /** Vector store provider. Default: "lancedb". */
  provider?: 'lancedb' | 'qdrant';
  /** Qdrant-specific settings (when provider is "qdrant"). */
  qdrant?: QdrantStorageConfig;
}

QdrantStorageConfig

interface QdrantStorageConfig {
  /** Qdrant server URL. */
  url?: string;
  /** Collection name. */
  collectionName?: string;
}

ReRankerConfig

interface ReRankerConfig {
  /** Whether re-ranking is enabled. */
  enabled: boolean;
  /** Cross-encoder model name. */
  model: string;
  /** Number of top results to re-rank. */
  topN: number;
}

RepoConfig

interface RepoConfig {
  /** Absolute or relative path to the repository. */
  path: string;
  /** Optional display name. */
  name?: string;
  /** Override languages for this repo. */
  languages?: string[];
  /** Override exclude patterns for this repo. */
  exclude?: string[];
}

BacklogConfig

interface BacklogConfig {
  /** Provider name ("azure-devops", "jira", "clickup"). */
  provider: string;
  /** Provider-specific configuration. */
  config?: Record<string, unknown>;
}

Parsed File Types

Types produced by the code parser during ingestion.

Source: packages/core/src/types/provider.ts

ParsedFile

interface ParsedFile {
  /** Relative file path from project root. */
  filePath: string;
  /** Detected programming language. */
  language: string;
  /** Full file content. */
  content: string;
  /** Top-level declarations found in the file. */
  declarations: string[];
}

Error Types

CodeRAG uses typed error classes with the Result<T, E> pattern from neverthrow. Each module has its own error class for precise error handling.

Source: packages/core/src/types/provider.ts, packages/core/src/backlog/backlog-provider.ts, packages/core/src/auth/types.ts, packages/core/src/storage/types.ts

class ParseError extends Error {
  readonly name = 'ParseError';
}

class ChunkError extends Error {
  readonly name = 'ChunkError';
}

class EmbedError extends Error {
  readonly name = 'EmbedError';
}

class StoreError extends Error {
  readonly name = 'StoreError';
}

class LLMError extends Error {
  readonly name = 'LLMError';
}

class ReRankerError extends Error {
  readonly name = 'ReRankerError';
}

class BacklogError extends Error {
  readonly name = 'BacklogError';
}

class AuthError extends Error {
  readonly name = 'AuthError';
}

class StorageError extends Error {
  readonly name = 'StorageError';
}

Tip: > All error types extend Error and set a descriptive name property. They are used as the E type in Result<T, E> return types throughout the codebase, ensuring errors are always handled explicitly.

Auth Types

Types for the authentication and authorization system.

Source: packages/core/src/auth/types.ts

Role

/** CodeRAG role hierarchy: Admin > Developer > Viewer */
type Role = 'admin' | 'developer' | 'viewer';

/** Ordered role hierarchy (index = privilege level). */
const ROLE_HIERARCHY: readonly Role[] = ['viewer', 'developer', 'admin'];

Action

/** Actions that can be gated by RBAC. */
type Action =
  | 'search'
  | 'context'
  | 'status'
  | 'explain'
  | 'docs'
  | 'index'
  | 'configure';

User

interface User {
  readonly id: string;
  readonly email: string;
  readonly name: string;
  readonly roles: readonly Role[];
  readonly allowedRepos: readonly string[];
}

AuthToken

interface AuthToken {
  readonly userId: string;
  readonly email: string;
  readonly roles: readonly Role[];
  readonly exp: number;   // Expiration (Unix timestamp)
  readonly iat: number;   // Issued at (Unix timestamp)
}

AuditEntry

interface AuditEntry {
  readonly timestamp: Date;
  readonly userId: string;
  readonly action: string;
  readonly resource: string;
  readonly details: string;
  readonly ip: string;
}

FilesExpand file tree

types.md

Latest commit

History