@optave/codegraph 3.1.5 → 3.3.0

package/dist/types.d.ts

@@ -0,0 +1,1322 @@
+/**
+ * Core type definitions for codegraph.
+ *
+ * These interfaces serve as the migration contract — each module is migrated
+ * to satisfy its interface. They capture every abstraction in the codebase:
+ * symbol/edge kinds, database shapes, repository contracts, extractors,
+ * parsers, builders, visitors, features, config, and the graph model.
+ */
+/** The original 10 symbol kinds — default query scope. */
+export type CoreSymbolKind = 'function' | 'method' | 'class' | 'interface' | 'type' | 'struct' | 'enum' | 'trait' | 'record' | 'module';
+/** Sub-declaration kinds (Phase 1). Includes 'method' for class child nodes. */
+export type ExtendedSymbolKind = 'parameter' | 'property' | 'constant' | 'method';
+/** All queryable symbol kinds. */
+export type SymbolKind = CoreSymbolKind | ExtendedSymbolKind;
+/** Special kind used for file-level nodes in the graph. */
+export type FileNodeKind = 'file';
+/** Union of every kind that can appear in a node row. */
+export type AnyNodeKind = SymbolKind | FileNodeKind;
+/** Coupling and dependency edge kinds. */
+export type CoreEdgeKind = 'imports' | 'imports-type' | 'dynamic-imports' | 'reexports' | 'calls' | 'extends' | 'implements' | 'contains';
+/** Parent/child and type relationship edges. */
+export type StructuralEdgeKind = 'parameter_of' | 'receiver';
+/** Dataflow-specific edge kinds. */
+export type DataflowEdgeKind = 'flows_to' | 'returns' | 'mutates';
+/** All edge kinds that can appear in the graph. */
+export type EdgeKind = CoreEdgeKind | StructuralEdgeKind;
+/** Extended edge kinds including dataflow. */
+export type AnyEdgeKind = EdgeKind | DataflowEdgeKind;
+/** AST node kinds extracted during analysis. */
+export type ASTNodeKind = 'call' | 'new' | 'string' | 'regex' | 'throw' | 'await';
+/** Coarse role classifications for symbols based on connectivity. */
+export type CoreRole = 'entry' | 'core' | 'utility' | 'adapter' | 'dead' | 'test-only' | 'leaf';
+/** Dead sub-roles — refine the coarse "dead" bucket. */
+export type DeadSubRole = 'dead-leaf' | 'dead-entry' | 'dead-ffi' | 'dead-unresolved';
+/** Every valid role. */
+export type Role = CoreRole | DeadSubRole;
+/** Supported language identifiers (from LANGUAGE_REGISTRY). */
+export type LanguageId = 'javascript' | 'typescript' | 'tsx' | 'python' | 'go' | 'rust' | 'java' | 'csharp' | 'ruby' | 'php' | 'hcl';
+/** Engine mode selector. */
+export type EngineMode = 'native' | 'wasm' | 'auto';
+/** Graph export formats. */
+export type ExportFormat = 'dot' | 'mermaid' | 'json' | 'graphml' | 'graphson' | 'neo4j-csv';
+/** A node row as stored in (and returned from) SQLite. */
+export interface NodeRow {
+    id: number;
+    name: string;
+    kind: AnyNodeKind;
+    file: string;
+    line: number;
+    end_line: number | null;
+    parent_id: number | null;
+    exported: 0 | 1 | null;
+    qualified_name: string | null;
+    scope: string | null;
+    visibility: 'public' | 'private' | 'protected' | null;
+    role: Role | null;
+}
+/** A node row augmented with fan-in count (from findNodesWithFanIn). */
+export interface NodeRowWithFanIn extends NodeRow {
+    fan_in: number;
+}
+/** Compact node ID row (from bulkNodeIdsByFile). */
+export interface NodeIdRow {
+    id: number;
+    name: string;
+    kind: string;
+    line: number;
+}
+/** A child node row (from findNodeChildren). */
+export interface ChildNodeRow {
+    name: string;
+    kind: SymbolKind;
+    line: number;
+    end_line: number | null;
+    qualified_name: string | null;
+    scope: string | null;
+    visibility: 'public' | 'private' | 'protected' | null;
+}
+/** An edge row as stored in SQLite. */
+export interface EdgeRow {
+    id: number;
+    source_id: number;
+    target_id: number;
+    kind: EdgeKind;
+    confidence: number | null;
+    dynamic: 0 | 1;
+}
+/** Callee/caller node shape (from findCallees / findCallers). */
+export interface RelatedNodeRow {
+    id: number;
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    end_line?: number | null;
+}
+/** An incoming/outgoing edge with the related node info. */
+export interface AdjacentEdgeRow {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    edge_kind: EdgeKind;
+}
+/** Import target/source row. */
+export interface ImportEdgeRow {
+    file: string;
+    edge_kind: EdgeKind;
+}
+/** Intra-file call edge (from findIntraFileCallEdges). */
+export interface IntraFileCallEdge {
+    caller_name: string;
+    callee_name: string;
+}
+/** Callable node row (for graph-read queries). */
+export interface CallableNodeRow {
+    id: number;
+    name: string;
+    kind: string;
+    file: string;
+}
+/** Call edge row (for graph-read queries). */
+export interface CallEdgeRow {
+    source_id: number;
+    target_id: number;
+    confidence: number | null;
+}
+/** File node row (for graph-read queries). */
+export interface FileNodeRow {
+    id: number;
+    name: string;
+    file: string;
+}
+/** Import edge row (for graph-read queries). */
+export interface ImportGraphEdgeRow {
+    source_id: number;
+    target_id: number;
+}
+/** Complexity metrics (from getComplexityForNode). */
+export interface ComplexityMetrics {
+    cognitive: number;
+    cyclomatic: number;
+    max_nesting: number;
+    maintainability_index: number | null;
+    halstead_volume: number | null;
+}
+/** Query options common across many repository methods. */
+export interface QueryOpts {
+    kind?: SymbolKind;
+    kinds?: SymbolKind[];
+    file?: string;
+    noTests?: boolean;
+}
+/** Options for listFunctionNodes / iterateFunctionNodes. */
+export interface ListFunctionOpts {
+    file?: string;
+    pattern?: string;
+    noTests?: boolean;
+}
+/** Options for findNodesForTriage. */
+export interface TriageQueryOpts {
+    kind?: string;
+    role?: Role;
+    noTests?: boolean;
+    file?: string;
+}
+/**
+ * Abstract Repository contract — defines all graph data access methods.
+ * Concrete implementations: SqliteRepository, InMemoryRepository.
+ */
+export interface Repository {
+    findNodeById(id: number): NodeRow | undefined;
+    findNodesByFile(file: string): NodeRow[];
+    findFileNodes(fileLike: string): NodeRow[];
+    findNodesWithFanIn(namePattern: string, opts?: QueryOpts): NodeRowWithFanIn[];
+    countNodes(): number;
+    countEdges(): number;
+    countFiles(): number;
+    getNodeId(name: string, kind: string, file: string, line: number): number | undefined;
+    getFunctionNodeId(name: string, file: string, line: number): number | undefined;
+    bulkNodeIdsByFile(file: string): NodeIdRow[];
+    findNodeChildren(parentId: number): ChildNodeRow[];
+    findNodesByScope(scopeName: string, opts?: QueryOpts): NodeRow[];
+    findNodeByQualifiedName(qualifiedName: string, opts?: {
+        file?: string;
+    }): NodeRow[];
+    listFunctionNodes(opts?: ListFunctionOpts): NodeRow[];
+    iterateFunctionNodes(opts?: ListFunctionOpts): IterableIterator<NodeRow>;
+    findNodesForTriage(opts?: TriageQueryOpts): NodeRow[];
+    findCallees(nodeId: number): RelatedNodeRow[];
+    findCallers(nodeId: number): RelatedNodeRow[];
+    findDistinctCallers(nodeId: number): RelatedNodeRow[];
+    findAllOutgoingEdges(nodeId: number): AdjacentEdgeRow[];
+    findAllIncomingEdges(nodeId: number): AdjacentEdgeRow[];
+    findCalleeNames(nodeId: number): string[];
+    findCallerNames(nodeId: number): string[];
+    findImportTargets(nodeId: number): ImportEdgeRow[];
+    findImportSources(nodeId: number): ImportEdgeRow[];
+    findImportDependents(nodeId: number): NodeRow[];
+    findCrossFileCallTargets(file: string): Set<number>;
+    countCrossFileCallers(nodeId: number, file: string): number;
+    getClassHierarchy(classNodeId: number): Set<number>;
+    findIntraFileCallEdges(file: string): IntraFileCallEdge[];
+    getCallableNodes(): CallableNodeRow[];
+    getCallEdges(): CallEdgeRow[];
+    getFileNodesAll(): FileNodeRow[];
+    getImportEdges(): ImportGraphEdgeRow[];
+    hasCfgTables(): boolean;
+    hasEmbeddings(): boolean;
+    hasDataflowTable(): boolean;
+    getComplexityForNode(nodeId: number): ComplexityMetrics | undefined;
+}
+/**
+ * In-memory repository — mutable, used for testing and incremental builds.
+ * Extends Repository with mutation methods.
+ */
+export interface MutableRepository extends Repository {
+    addNode(attrs: {
+        name: string;
+        kind: AnyNodeKind;
+        file: string;
+        line: number;
+        end_line?: number;
+        parent_id?: number;
+        exported?: 0 | 1;
+        qualified_name?: string;
+        scope?: string;
+        visibility?: 'public' | 'private' | 'protected';
+        role?: Role;
+    }): number;
+    addEdge(attrs: {
+        source_id: number;
+        target_id: number;
+        kind: AnyEdgeKind;
+        confidence?: number;
+        dynamic?: 0 | 1;
+    }): number;
+    addComplexity(nodeId: number, metrics: {
+        cognitive: number;
+        cyclomatic: number;
+        max_nesting: number;
+        maintainability_index?: number;
+        halstead_volume?: number;
+    }): void;
+}
+/** A symbol definition produced by any extractor. */
+export interface Definition {
+    name: string;
+    kind: SymbolKind;
+    line: number;
+    endLine?: number;
+    children?: SubDeclaration[];
+    visibility?: 'public' | 'private' | 'protected';
+    decorators?: string[];
+    /** Populated post-analysis by the complexity visitor. */
+    complexity?: DefinitionComplexity;
+    /** Populated post-analysis by the CFG visitor. */
+    cfg?: {
+        blocks: CfgBlock[];
+        edges: CfgEdge[];
+    } | null;
+}
+/** Sub-declaration (child) within a definition. */
+export interface SubDeclaration {
+    name: string;
+    kind: 'parameter' | 'property' | 'constant' | 'method';
+    line: number;
+    endLine?: number;
+    visibility?: 'public' | 'private' | 'protected';
+}
+/** Complexity metrics attached to a definition post-analysis. */
+export interface DefinitionComplexity {
+    cognitive: number;
+    cyclomatic: number;
+    maxNesting: number;
+    halstead?: HalsteadMetrics;
+    loc?: LOCMetrics;
+    maintainabilityIndex?: number;
+}
+/** Halstead software science metrics. */
+export interface HalsteadMetrics {
+    volume: number;
+    difficulty: number;
+    effort: number;
+    bugs: number;
+}
+/** Lines-of-code metrics. */
+export interface LOCMetrics {
+    loc: number;
+    sloc: number;
+    commentLines: number;
+}
+/** A function/method call detected by an extractor. */
+export interface Call {
+    name: string;
+    line: number;
+    receiver?: string;
+    dynamic?: boolean;
+}
+/** An import statement detected by an extractor. */
+export interface Import {
+    source: string;
+    names: string[];
+    line: number;
+    typeOnly?: boolean;
+    reexport?: boolean;
+    wildcardReexport?: boolean;
+    dynamicImport?: boolean;
+    pythonImport?: boolean;
+    goImport?: boolean;
+    rustUse?: boolean;
+    javaImport?: boolean;
+    csharpUsing?: boolean;
+    rubyRequire?: boolean;
+    phpUse?: boolean;
+}
+/** A class/struct/trait relationship (extends or implements). */
+export interface ClassRelation {
+    name: string;
+    extends?: string;
+    implements?: string;
+    line: number;
+}
+/** A named export from a module. */
+export interface Export {
+    name: string;
+    kind: SymbolKind;
+    line: number;
+}
+/** A type-map entry for call resolution confidence scoring. */
+export interface TypeMapEntry {
+    type: string;
+    confidence: number;
+}
+/** The normalized output shape returned by every language extractor. */
+export interface ExtractorOutput {
+    definitions: Definition[];
+    calls: Call[];
+    imports: Import[];
+    classes: ClassRelation[];
+    exports: Export[];
+    typeMap: Map<string, TypeMapEntry>;
+    /** WASM tree retained for downstream analysis (complexity, CFG, dataflow). */
+    _tree?: TreeSitterTree;
+    /** Language identifier. */
+    _langId?: LanguageId;
+    /** Line count for metrics. */
+    _lineCount?: number;
+    /** Dataflow results, populated post-analysis. */
+    dataflow?: DataflowResult;
+    /** AST node rows, populated post-analysis. */
+    astNodes?: ASTNodeRow[];
+}
+/** Extractor function signature. */
+export type ExtractorFn = (tree: TreeSitterTree, filePath: string, query?: TreeSitterQuery) => ExtractorOutput;
+/** A single entry in the LANGUAGE_REGISTRY. */
+export interface LanguageRegistryEntry {
+    id: LanguageId;
+    extensions: string[];
+    grammarFile: string;
+    extractor: ExtractorFn;
+    required: boolean;
+}
+/** tree-sitter opaque types (thin wrappers — real impl is WASM). */
+export interface TreeSitterNode {
+    type: string;
+    text: string;
+    startPosition: {
+        row: number;
+        column: number;
+    };
+    endPosition: {
+        row: number;
+        column: number;
+    };
+    childCount: number;
+    namedChildCount: number;
+    child(index: number): TreeSitterNode | null;
+    namedChild(index: number): TreeSitterNode | null;
+    childForFieldName(name: string): TreeSitterNode | null;
+    parent: TreeSitterNode | null;
+    children: TreeSitterNode[];
+    namedChildren: TreeSitterNode[];
+}
+export interface TreeSitterTree {
+    rootNode: TreeSitterNode;
+}
+export interface TreeSitterQuery {
+    matches(node: TreeSitterNode): TreeSitterQueryMatch[];
+    captures(node: TreeSitterNode): TreeSitterQueryCapture[];
+}
+export interface TreeSitterQueryMatch {
+    pattern: number;
+    captures: TreeSitterQueryCapture[];
+}
+export interface TreeSitterQueryCapture {
+    name: string;
+    node: TreeSitterNode;
+}
+/** A single import to resolve. */
+export interface ImportBatchItem {
+    fromFile: string;
+    importSource: string;
+}
+/** Batch of imports to resolve. */
+export type ImportBatch = ImportBatchItem[];
+/** Result of resolveImportsBatch: Map<"fromFile|importSource", resolvedPath>. */
+export type BatchResolvedMap = Map<string, string>;
+/** Path aliases from tsconfig/jsconfig. */
+export interface PathAliases {
+    baseUrl: string | null;
+    paths: Record<string, string[]>;
+}
+/** Parsed bare specifier. */
+export interface BareSpecifier {
+    packageName: string;
+    subpath: string;
+}
+/** Shared context mutated during the DFS walk. */
+export interface VisitorContext {
+    nestingLevel: number;
+    currentFunction: TreeSitterNode | null;
+    langId: string;
+    scopeStack: ScopeEntry[];
+}
+/** An entry on the scope stack. */
+export interface ScopeEntry {
+    funcName: string | null;
+    funcNode: TreeSitterNode;
+    params: Map<string, unknown>;
+    locals: Map<string, unknown>;
+}
+/** Return value from enterNode — request skip of descendants. */
+export interface EnterNodeResult {
+    skipChildren?: boolean;
+}
+/** A pluggable analysis visitor for the unified DFS walker. */
+export interface Visitor {
+    name: string;
+    init?(langId: string): void;
+    enterNode?(node: TreeSitterNode, context: VisitorContext): EnterNodeResult | undefined;
+    exitNode?(node: TreeSitterNode, context: VisitorContext): void;
+    enterFunction?(funcNode: TreeSitterNode, funcName: string | null, context: VisitorContext): void;
+    exitFunction?(funcNode: TreeSitterNode, funcName: string | null, context: VisitorContext): void;
+    finish?(): unknown;
+    functionNodeTypes?: Set<string>;
+}
+/** Options for walkWithVisitors. */
+export interface WalkOptions {
+    functionNodeTypes?: Set<string>;
+    nestingNodeTypes?: Set<string>;
+    getFunctionName?: (node: TreeSitterNode) => string | null;
+}
+/** Result of walkWithVisitors: Map of visitor.name → finish() result. */
+export type WalkResults = Record<string, unknown>;
+/** Toggles for runAnalyses. */
+export interface AnalysisOpts {
+    ast?: boolean;
+    complexity?: boolean;
+    cfg?: boolean;
+    dataflow?: boolean;
+}
+/** Timing output from runAnalyses. */
+export interface AnalysisTiming {
+    astMs: number;
+    complexityMs: number;
+    cfgMs: number;
+    dataflowMs: number;
+    _unifiedWalkMs?: number;
+}
+/** An AST node row stored in the database. */
+export interface ASTNodeRow {
+    node_id: number;
+    kind: ASTNodeKind;
+    line: number;
+    text: string;
+}
+/** AST type mapping: tree-sitter node type → analysis kind. */
+export type ASTTypeMap = Map<string, ASTNodeKind>;
+/** Complexity rules for a language. */
+export interface ComplexityRules {
+    branchNodes: Set<string>;
+    nestingNodes: Set<string>;
+    functionNodes: Set<string>;
+}
+/** Halstead rules for a language. */
+export interface HalsteadRules {
+    operators: Set<string>;
+    operands: Set<string>;
+}
+/** CFG rules for a language. */
+export interface CfgRules {
+    controlFlowNodes: Set<string>;
+    functionNodes: Set<string>;
+}
+/** Dataflow rules for a language. */
+export interface DataflowRules {
+    variableDeclarators: Set<string>;
+    parameterNodes: Set<string>;
+    callNodes: Set<string>;
+    memberNodes: Set<string>;
+    returnNodes: Set<string>;
+    awaitNodes: Set<string>;
+}
+/** A basic block in a control flow graph. */
+export interface CfgBlock {
+    id: number;
+    label: string;
+    startLine: number;
+    endLine: number;
+}
+/** An edge in a control flow graph. */
+export interface CfgEdge {
+    from: number;
+    to: number;
+    label?: string;
+}
+/** Dataflow extraction result. */
+export interface DataflowResult {
+    parameters: DataflowParam[];
+    returns: DataflowReturn[];
+    assignments: DataflowAssignment[];
+    argFlows: DataflowArgFlow[];
+    mutations: DataflowMutation[];
+}
+export interface DataflowParam {
+    name: string;
+    funcName: string;
+    line: number;
+    typeHint?: string;
+}
+export interface DataflowReturn {
+    funcName: string;
+    line: number;
+    expression: string;
+}
+export interface DataflowAssignment {
+    name: string;
+    line: number;
+    expression: string;
+}
+export interface DataflowArgFlow {
+    callerFunc: string;
+    callee: string;
+    argIndex: number;
+    binding: {
+        name: string;
+        type: 'param' | 'local' | 'unknown';
+    };
+    line: number;
+}
+export interface DataflowMutation {
+    binding: {
+        name: string;
+        type: 'param' | 'local' | 'unknown';
+    };
+    mutatingExpr: string;
+    line: number;
+}
+/** Node attributes stored in the in-memory graph. */
+export interface GraphNodeAttrs {
+    label?: string;
+    kind?: string;
+    file?: string;
+    name?: string;
+    line?: number;
+    dbId?: number;
+    [key: string]: unknown;
+}
+/** Edge attributes stored in the in-memory graph. */
+export interface GraphEdgeAttrs {
+    kind?: string;
+    confidence?: number;
+    weight?: number;
+    [key: string]: unknown;
+}
+/** The unified in-memory graph model. */
+export interface CodeGraph {
+    readonly directed: boolean;
+    readonly nodeCount: number;
+    readonly edgeCount: number;
+    addNode(id: string, attrs?: GraphNodeAttrs): CodeGraph;
+    hasNode(id: string): boolean;
+    getNodeAttrs(id: string): GraphNodeAttrs | undefined;
+    nodes(): IterableIterator<[string, GraphNodeAttrs]>;
+    nodeIds(): string[];
+    addEdge(source: string, target: string, attrs?: GraphEdgeAttrs): CodeGraph;
+    hasEdge(source: string, target: string): boolean;
+    getEdgeAttrs(source: string, target: string): GraphEdgeAttrs | undefined;
+    edges(): Generator<[string, string, GraphEdgeAttrs]>;
+    successors(id: string): string[];
+    predecessors(id: string): string[];
+    neighbors(id: string): string[];
+    outDegree(id: string): number;
+    inDegree(id: string): number;
+    subgraph(predicate: (id: string, attrs: GraphNodeAttrs) => boolean): CodeGraph;
+    filterEdges(predicate: (src: string, tgt: string, attrs: GraphEdgeAttrs) => boolean): CodeGraph;
+    toEdgeArray(): Array<{
+        source: string;
+        target: string;
+    }>;
+    toGraphology(opts?: {
+        type?: string;
+    }): unknown;
+    clone(): CodeGraph;
+    merge(other: CodeGraph): CodeGraph;
+}
+/** Engine options for the build pipeline. */
+export interface EngineOpts {
+    engine: EngineMode;
+    dataflow: boolean;
+    ast: boolean;
+}
+/** A file change detected during incremental builds. */
+export interface ParseChange {
+    file: string;
+    relPath?: string;
+    content?: string;
+    hash?: string;
+    stat?: {
+        mtime: number;
+        size: number;
+    };
+    _reverseDepOnly?: boolean;
+}
+/** Metadata-only self-heal update. */
+export interface MetadataUpdate {
+    relPath: string;
+    hash: string;
+    stat: {
+        mtime: number;
+        size: number;
+    };
+}
+/** A file queued for parsing. */
+export interface FileToParse {
+    file: string;
+    relPath?: string;
+}
+/** Shared mutable state threaded through all build stages. */
+export interface PipelineContext {
+    rootDir: string;
+    db: unknown;
+    dbPath: string;
+    config: CodegraphConfig;
+    opts: BuildGraphOpts;
+    engineOpts: EngineOpts;
+    engineName: 'native' | 'wasm';
+    engineVersion: string | null;
+    aliases: PathAliases;
+    incremental: boolean;
+    forceFullRebuild: boolean;
+    schemaVersion: number;
+    allFiles: string[];
+    discoveredDirs: Set<string>;
+    isFullBuild: boolean;
+    parseChanges: ParseChange[];
+    metadataUpdates: MetadataUpdate[];
+    removed: string[];
+    earlyExit: boolean;
+    allSymbols: Map<string, ExtractorOutput>;
+    fileSymbols: Map<string, ExtractorOutput>;
+    filesToParse: FileToParse[];
+    batchResolved: BatchResolvedMap | null;
+    reexportMap: Map<string, unknown[]>;
+    barrelOnlyFiles: Set<string>;
+    nodesByName: Map<string, NodeRow[]>;
+    nodesByNameAndFile: Map<string, NodeRow[]>;
+    hasEmbeddings: boolean;
+    lineCountMap: Map<string, number>;
+    timing: Record<string, number>;
+    buildStart: number;
+}
+/** Options for buildGraph. */
+export interface BuildGraphOpts {
+    incremental?: boolean;
+    engine?: EngineMode;
+    dataflow?: boolean;
+    ast?: boolean;
+}
+/** Build timing result from buildGraph. */
+export interface BuildResult {
+    phases: {
+        setupMs: number;
+        parseMs: number;
+        insertMs: number;
+        resolveMs: number;
+        edgesMs: number;
+        structureMs: number;
+        rolesMs: number;
+        astMs: number;
+        complexityMs: number;
+        cfgMs: number;
+        dataflowMs: number;
+        finalizeMs: number;
+    };
+}
+/** A pipeline stage function. */
+export type PipelineStage = (ctx: PipelineContext) => Promise<void>;
+export interface CodegraphConfig {
+    include: string[];
+    exclude: string[];
+    ignoreDirs: string[];
+    extensions: string[];
+    aliases: Record<string, unknown>;
+    build: {
+        incremental: boolean;
+        dbPath: string;
+        driftThreshold: number;
+    };
+    query: {
+        defaultDepth: number;
+        defaultLimit: number;
+        excludeTests: boolean;
+    };
+    embeddings: {
+        model: string;
+        llmProvider: string | null;
+    };
+    llm: {
+        provider: string | null;
+        model: string | null;
+        baseUrl: string | null;
+        apiKey: string | null;
+        apiKeyCommand: string | null;
+    };
+    search: {
+        defaultMinScore: number;
+        rrfK: number;
+        topK: number;
+        similarityWarnThreshold: number;
+    };
+    ci: {
+        failOnCycles: boolean;
+        impactThreshold: number | null;
+    };
+    manifesto: {
+        rules: ManifestoRules;
+        boundaries: unknown | null;
+    };
+    check: {
+        cycles: boolean;
+        blastRadius: number | null;
+        signatures: boolean;
+        boundaries: boolean;
+        depth: number;
+    };
+    coChange: {
+        since: string;
+        minSupport: number;
+        minJaccard: number;
+        maxFilesPerCommit: number;
+    };
+    analysis: {
+        impactDepth: number;
+        fnImpactDepth: number;
+        auditDepth: number;
+        sequenceDepth: number;
+        falsePositiveCallers: number;
+        briefCallerDepth: number;
+        briefImporterDepth: number;
+        briefHighRiskCallers: number;
+        briefMediumRiskCallers: number;
+    };
+    community: {
+        resolution: number;
+    };
+    structure: {
+        cohesionThreshold: number;
+    };
+    risk: {
+        weights: RiskWeights;
+        roleWeights: Record<Role, number>;
+        defaultRoleWeight: number;
+    };
+    display: {
+        maxColWidth: number;
+        excerptLines: number;
+        summaryMaxChars: number;
+        jsdocEndScanLines: number;
+        jsdocOpenScanLines: number;
+        signatureGatherLines: number;
+    };
+    mcp: {
+        defaults: McpDefaults;
+    };
+}
+export interface ManifestoRules {
+    cognitive: ThresholdRule;
+    cyclomatic: ThresholdRule;
+    maxNesting: ThresholdRule;
+    maintainabilityIndex: ThresholdRule;
+    importCount: ThresholdRule;
+    exportCount: ThresholdRule;
+    lineCount: ThresholdRule;
+    fanIn: ThresholdRule;
+    fanOut: ThresholdRule;
+    noCycles: ThresholdRule;
+    boundaries: ThresholdRule;
+}
+export interface ThresholdRule {
+    warn: number | null;
+    fail?: number | null;
+}
+export interface RiskWeights {
+    fanIn: number;
+    complexity: number;
+    churn: number;
+    role: number;
+    mi: number;
+}
+export interface McpDefaults {
+    list_functions: number;
+    query: number;
+    where: number;
+    node_roles: number;
+    export_graph: number;
+    fn_impact: number;
+    context: number;
+    explain: number;
+    file_deps: number;
+    file_exports: number;
+    diff_impact: number;
+    impact_analysis: number;
+    semantic_search: number;
+    execution_flow: number;
+    hotspots: number;
+    co_changes: number;
+    complexity: number;
+    manifesto: number;
+    communities: number;
+    structure: number;
+    triage: number;
+    ast_query: number;
+}
+export interface PaginationOpts {
+    limit?: number;
+    offset?: number;
+}
+export interface PaginationMeta {
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    returned: number;
+}
+export interface PaginatedItems<T> {
+    items: T[];
+    pagination?: PaginationMeta;
+}
+/** A result object with optional _pagination metadata. */
+export type Paginated<T> = T & {
+    _pagination?: PaginationMeta;
+};
+export type ErrorCode = 'CODEGRAPH_ERROR' | 'PARSE_FAILED' | 'DB_ERROR' | 'CONFIG_INVALID' | 'RESOLUTION_FAILED' | 'ENGINE_UNAVAILABLE' | 'ANALYSIS_FAILED' | 'BOUNDARY_VIOLATION';
+export interface CodegraphErrorOpts {
+    code?: ErrorCode;
+    file?: string;
+    cause?: Error;
+}
+export interface AuditResult {
+    target: string;
+    kind: 'function' | 'file';
+    functions: AuditFunctionEntry[];
+}
+export interface AuditFunctionEntry {
+    name: string;
+    kind: SymbolKind;
+    file: string;
+    line: number;
+    endLine: number | null;
+    role: Role | null;
+    lineCount: number;
+    summary: string | null;
+    signature: string | null;
+    callees: string[];
+    callers: string[];
+    relatedTests: string[];
+    impact: {
+        totalDependents: number;
+        levels: Record<number, ImpactLevelEntry[]>;
+    };
+    health: {
+        cognitive: number;
+        cyclomatic: number;
+        maxNesting: number;
+        maintainabilityIndex: number | null;
+        halstead: HalsteadMetrics | null;
+        loc: number;
+        sloc: number;
+        commentLines: number;
+        thresholdBreaches: string[];
+    };
+    riskScore: number;
+    complexityNotes: string[];
+    sideEffects: string[];
+}
+export interface ImpactLevelEntry {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    viaImplements?: boolean;
+}
+export interface ComplexityResult {
+    functions: ComplexityEntry[];
+    summary: {
+        analyzed: number;
+        avgCognitive: number;
+        maxCognitive: number;
+        avgCyclomatic: number;
+        maxCyclomatic: number;
+        avgMI: number;
+        minMI: number;
+        aboveWarn: number;
+    };
+    thresholds: ManifestoRules;
+    hasGraph: boolean;
+}
+export interface ComplexityEntry {
+    name: string;
+    kind: SymbolKind;
+    file: string;
+    line: number;
+    endLine: number | null;
+    cognitive: number;
+    cyclomatic: number;
+    maxNesting: number;
+    loc: number;
+    sloc: number;
+    maintainabilityIndex: number;
+    halstead: HalsteadMetrics;
+    exceeds?: Array<'cognitive' | 'cyclomatic' | 'maxNesting' | 'maintainabilityIndex'>;
+}
+export interface DiffImpactResult {
+    error?: string;
+    changedFiles: number;
+    newFiles: string[];
+    affectedFunctions: AffectedFunction[];
+    affectedFiles: string[];
+    historicallyCoupled?: CoChangeEntry[];
+    ownership?: Record<string, string>;
+    boundaryViolations?: BoundaryViolation[];
+    boundaryViolationCount: number;
+    summary?: DiffImpactSummary;
+}
+export interface AffectedFunction {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    totalDependents: number;
+    levels: Record<number, ImpactLevelEntry[]>;
+}
+export interface CoChangeEntry {
+    file: string;
+    support: number;
+    jaccard: number;
+}
+export interface BoundaryViolation {
+    from: string;
+    to: string;
+    rule: string;
+}
+export interface DiffImpactSummary {
+    changedFiles: number;
+    newFiles: number;
+    affectedFunctions: number;
+    totalDependents: number;
+    boundaryViolations: number;
+}
+export interface TriageResult {
+    items: TriageEntry[];
+    summary: {
+        total: number;
+        analyzed: number;
+        avgScore: number;
+        maxScore: number;
+        weights: RiskWeights;
+        signalCoverage: {
+            complexity: number;
+            churn: number;
+            fanIn: number;
+            mi: number;
+        };
+    };
+    _pagination?: PaginationMeta;
+}
+export interface TriageEntry {
+    name: string;
+    kind: SymbolKind;
+    file: string;
+    line: number;
+    role: Role | null;
+    fanIn: number;
+    cognitive: number;
+    churn: number;
+    maintainabilityIndex: number;
+    normFanIn: number;
+    normComplexity: number;
+    normChurn: number;
+    normMI: number;
+    roleWeight: number;
+    riskScore: number;
+}
+export interface CommunitiesResult {
+    communities: CommunityEntry[];
+    modularity: number;
+    drift: {
+        splitCandidates: Array<{
+            directory: string;
+            communityCount: number;
+        }>;
+        mergeCandidates: Array<{
+            communityId: number;
+            size: number;
+            directoryCount: number;
+            directories: string[];
+        }>;
+    };
+    summary: {
+        communityCount: number;
+        modularity: number;
+        nodeCount: number;
+        driftScore: number;
+    };
+    _pagination?: PaginationMeta;
+}
+export interface CommunityEntry {
+    id: number;
+    size: number;
+    directories: Record<string, number>;
+    members?: Array<{
+        name: string;
+        file: string;
+        kind?: string;
+    }>;
+}
+export interface CheckResult {
+    predicates: CheckPredicate[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        changedFiles: number;
+        newFiles: number;
+    };
+    passed: boolean;
+    error?: string;
+}
+export interface CheckPredicate {
+    name: string;
+    passed: boolean;
+    violations: unknown[];
+    maxFound?: number;
+    threshold?: number;
+    note?: string;
+}
+export type BatchCommand = 'fn-impact' | 'context' | 'explain' | 'where' | 'query' | 'impact' | 'deps' | 'exports' | 'flow' | 'dataflow' | 'complexity';
+export interface BatchResult {
+    command: BatchCommand;
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: BatchResultEntry[];
+}
+export interface BatchResultEntry {
+    target: string;
+    ok: boolean;
+    data?: unknown;
+    error?: string;
+}
+export interface MultiBatchItem {
+    command: BatchCommand;
+    target: string;
+    opts?: Record<string, unknown>;
+}
+export interface MultiBatchResult {
+    mode: 'multi';
+    total: number;
+    succeeded: number;
+    failed: number;
+    results: BatchResultEntry[];
+}
+export interface FlowResult {
+    entry: FlowEntry | null;
+    depth: number;
+    steps: Array<{
+        depth: number;
+        nodes: Array<{
+            name: string;
+            kind: string;
+            file: string;
+            line: number;
+        }>;
+    }>;
+    leaves: Array<{
+        name: string;
+        kind: string;
+        file: string;
+        line: number;
+        depth: number;
+    }>;
+    cycles: Array<{
+        from: string;
+        to: string;
+        depth: number;
+    }>;
+    totalReached: number;
+    truncated: boolean;
+    _pagination?: PaginationMeta;
+}
+export interface FlowEntry {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    type: string;
+    role: Role | null;
+}
+export type ManifestoRuleLevel = 'function' | 'file' | 'graph';
+export interface ManifestoRuleDef {
+    name: string;
+    level: ManifestoRuleLevel;
+    metric: string;
+    defaults: ThresholdRule;
+    reportOnly?: boolean;
+}
+export interface ManifestoResult {
+    rules: ManifestoRuleStatus[];
+    violations: ManifestoViolation[];
+    summary: {
+        total: number;
+        passed: number;
+        warned: number;
+        failed: number;
+    };
+    _pagination?: PaginationMeta;
+}
+export interface ManifestoRuleStatus {
+    name: string;
+    level: ManifestoRuleLevel;
+    status: 'pass' | 'warn' | 'fail';
+    thresholds: ThresholdRule;
+    violationCount: number;
+}
+export interface ManifestoViolation {
+    rule: string;
+    level: ManifestoRuleLevel;
+    value: number;
+    threshold: number;
+    name?: string;
+    kind?: string;
+    file?: string;
+    line?: number;
+}
+export interface FileExportsResult {
+    file: string;
+    results: FileExportEntry[];
+    reexports: Array<{
+        file: string;
+    }>;
+    totalExported: number;
+    totalInternal: number;
+    totalUnused: number;
+}
+export interface FileExportEntry {
+    name: string;
+    kind: SymbolKind;
+    line: number;
+    endLine: number | null;
+    role: Role | null;
+    signature: string | null;
+    summary: string | null;
+    consumers: Array<{
+        name: string;
+        file: string;
+        line: number;
+    }>;
+    consumerCount: number;
+}
+export interface PathResult {
+    from: string;
+    to: string;
+    fromCandidates: NodeRow[];
+    toCandidates: NodeRow[];
+    found: boolean;
+    hops: number | null;
+    path: PathStep[];
+    alternateCount: number;
+    edgeKinds: string[];
+    reverse: boolean;
+    maxDepth: number;
+}
+export interface PathStep {
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    edgeKind: AnyEdgeKind | null;
+}
+export interface StatsResult {
+    nodes: {
+        total: number;
+        byKind: Record<string, number>;
+    };
+    edges: {
+        total: number;
+        byKind: Record<string, number>;
+    };
+    files: Record<string, unknown>;
+    cycles: {
+        fileLevel: number;
+        functionLevel: number;
+    };
+    hotspots: unknown[];
+    embeddings?: unknown;
+    quality?: unknown;
+    roles: Record<Role, number>;
+    complexity?: unknown;
+}
+export interface ModuleMapResult {
+    limit: number;
+    topNodes: ModuleMapEntry[];
+    stats: {
+        totalFiles: number;
+        totalNodes: number;
+        totalEdges: number;
+    };
+}
+export interface ModuleMapEntry {
+    file: string;
+    dir: string;
+    inEdges: number;
+    outEdges: number;
+    coupling: number;
+}
+export interface RolesResult {
+    count: number;
+    summary: Record<Role, number>;
+    symbols: NodeRow[];
+}
+export interface RegistryEntry {
+    path: string;
+    dbPath: string;
+    addedAt: string;
+    lastAccessedAt: string;
+}
+export interface Registry {
+    repos: Record<string, RegistryEntry>;
+}
+export interface RegistryListItem {
+    name: string;
+    path: string;
+    dbPath: string;
+    addedAt: string;
+    lastAccessedAt: string;
+}
+export interface MCPServerOptions {
+    multiRepo?: boolean;
+    allowedRepos?: string[];
+}
+export interface OptionDef {
+    flags: string;
+    description: string;
+    default?: unknown;
+}
+export interface Command {
+    name: string;
+    description: string;
+    options: OptionDef[];
+    validate?(args: unknown, opts: unknown): void;
+    execute(args: unknown, opts: unknown): Promise<void>;
+}
+export interface RiskInput {
+    fan_in: number;
+    cognitive: number;
+    churn: number;
+    mi: number;
+    role?: Role;
+}
+export interface RiskScored {
+    normFanIn: number;
+    normComplexity: number;
+    normChurn: number;
+    normMI: number;
+    roleWeight: number;
+    riskScore: number;
+}
+export interface SequenceStep {
+    caller: string;
+    callee: string;
+    depth: number;
+}
+export interface SequenceResult {
+    entry: string;
+    steps: SequenceStep[];
+    participants: string[];
+}
+export interface ExportOpts {
+    fileLevel?: boolean;
+    noTests?: boolean;
+    minConfidence?: number;
+    limit?: number;
+    offset?: number;
+    direction?: string;
+}
+export interface ExportJSONResult {
+    nodes: NodeRow[];
+    edges: EdgeRow[];
+    _pagination?: PaginationMeta;
+}
+export interface ExportGraphSONResult {
+    vertices: unknown[];
+    edges: unknown[];
+    _pagination?: PaginationMeta;
+}
+export interface ExportNeo4jCSVResult {
+    nodes: string;
+    relationships: string;
+}
+//# sourceMappingURL=types.d.ts.map