/**
 * CodeGraph Type Definitions
 *
 * Core types for the semantic knowledge graph system.
 */
/**
 * 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 declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "type_alias", "namespace", "parameter", "import", "export", "route", "component"];
export type NodeKind = (typeof NODE_KINDS)[number];
/**
 * Types of edges (relationships) between nodes
 */
export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'want_ipc' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates';
/**
 * Supported programming languages. See NODE_KINDS for why this is a
 * runtime-iterable const array.
 */
export declare const LANGUAGES: readonly ["arkts", "typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "razor", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "astro", "liquid", "pascal", "scala", "lua", "luau", "objc", "r", "yaml", "twig", "xml", "properties", "unknown"];
export type Language = (typeof LANGUAGES)[number];
/**
 * 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[];
    /**
     * Normalized return/result type name for a function/method (the bare class
     * name, smart-pointer pointee unwrapped). Captured for C/C++ so resolution
     * can infer a chained receiver's type from what the inner call returns —
     * `Foo::instance().bar()` resolves `bar` on `Foo` (issue #645). Undefined for
     * languages/symbols where it isn't captured.
     */
    returnType?: 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<string, unknown>;
    /** 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[];
}
/**
 * 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;
}
/**
 * Kinds an unresolved reference can carry. `function_ref` is internal-only —
 * a function name used as a VALUE (callback registration, #756). It never
 * becomes an edge kind: resolution maps it to a `references` edge targeting
 * function/method nodes only (see `matchFunctionRef`).
 */
export type ReferenceKind = EdgeKind | 'function_ref';
/**
 * 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: ReferenceKind;
    /** 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[];
}
/**
 * A subgraph containing a subset of the knowledge graph
 */
export interface Subgraph {
    /** Nodes in this subgraph */
    nodes: Map<string, Node>;
    /** Edges in this subgraph */
    edges: Edge[];
    /** Root node IDs (entry points) */
    roots: string[];
    /**
     * Retrieval confidence for context-style queries. `'low'` means the query
     * resolved only to isolated common-word matches (no entry point corroborated
     * by 2+ distinct query terms) — callers should surface an honest handoff to
     * explore/trace rather than present the results as comprehensive. Undefined
     * for graph traversals that don't run the search-ranking path.
     */
    confidence?: 'high' | 'low';
}
/**
 * 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[];
    /** Optional retrieval provenance/signals captured during candidate ranking */
    retrievalSignals?: string[];
}
/**
 * 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;
}
/**
 * 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<NodeKind, number>;
    /** Edge counts by kind */
    edgesByKind: Record<EdgeKind, number>;
    /** File counts by language */
    filesByLanguage: Record<Language, number>;
    /** Database size in bytes */
    dbSizeBytes: number;
    /** Last update timestamp */
    lastUpdated: number;
}
/**
 * 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;
    /** Navigation-only context slice without code blocks or verbose metadata */
    navigationOnly?: boolean;
    /** Output mode for task-oriented low-noise retrieval experiments */
    mode?: 'default' | 'task';
}
/**
 * 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;
    /** Optional retrieval-first metadata for task-oriented consumers */
    retrieval?: {
        /** Ranked first-hop anchors from the retrieval pipeline */
        anchors: Array<{
            nodeId: string;
            score: number;
            confidence: 'high' | 'medium' | 'low';
            evidence: string[];
            scoreComponents?: Array<{
                category: 'anchor-match' | 'structural-evidence' | 'platform-fact' | 'semantic-grouping' | 'shell-penalty';
                label: string;
                value: number;
            }>;
        }>;
        /** Overall confidence of the selected first-hop result */
        confidence?: 'high' | 'medium' | 'low';
        /** Explicit high-confidence platform-evolution facts relevant to interpretation */
        platformFacts?: Array<{
            category: 'component-generation' | 'state-generation' | 'routing-generation' | 'config' | 'deprecated-replacement';
            label: string;
            value: string;
            evidence: string[];
        }>;
        /** Minimal platform-constraint groupings for app/module/build interpretation */
        platformConstraints?: Array<{
            label: string;
            boundaries: string[];
            permissions: string[];
            build: string[];
            routing: string[];
            evidence: string[];
        }>;
        /** Bounded ArkUI-aware verification surface for change review and diagnosis */
        validationPack?: {
            pages: string[];
            state: string[];
            routes: string[];
            platform: string[];
            evidence: string[];
        };
        /** Bounded ArkUI route/data contract clues for task-mode retrieval */
        routeContracts?: Array<{
            destination: string;
            entrySource: string;
            params: string[];
            results: string[];
            guards: string[];
            evidence: string[];
        }>;
        /** Bounded ArkTS bridge-boundary contracts for task-mode retrieval */
        bridgeContracts?: Array<{
            label: string;
            entrySource: string;
            boundaryType: string;
            crossingAnchors: string[];
            targets: string[];
            degradedReason?: string;
            evidence: string[];
        }>;
        /** Bounded lifecycle/interaction/async causality slices for task-mode retrieval */
        causalitySlices?: Array<{
            label: string;
            entryCauses: string[];
            lifecycleBreakpoints: string[];
            interactionBreakpoints: string[];
            asyncBreakpoints: string[];
            targets: string[];
            degradedReason?: string;
            evidence: string[];
        }>;
        /** Bounded state/effect neighborhood signals for task-mode retrieval */
        stateEffects?: Array<{
            category: 'state-write' | 'state-read' | 'effect-trigger';
            label: string;
            value: string;
            evidence: string[];
        }>;
        /** Grouped state facts with source/write/read/propagation/persistence anchors */
        stateFacts?: Array<{
            label: string;
            sourceOfTruth: string;
            canonicality?: 'canonical' | 'derived' | 'mirror' | 'unknown';
            writePoints: string[];
            readPoints: string[];
            propagation: string[];
            persistence: string[];
            riskSignals?: string[];
            evidence: string[];
        }>;
        /** Bounded concept/owner bundles for task-oriented retrieval */
        conceptClusters?: Array<{
            label: string;
            symbols: string[];
            files: string[];
            reasons: string[];
        }>;
        /** Minimal page/component skeletons for render-ownership-oriented queries */
        renderSkeletons?: Array<{
            page: string;
            shell?: string;
            owner: string;
            children: string[];
            evidence: string[];
        }>;
        /** Explicit identity/reuse boundary facts for ArkUI collection reuse queries */
        identityBoundaries?: Array<{
            label: string;
            page: string;
            owner: string;
            collection: string;
            keySignals: string[];
            stateSignals: string[];
            evidence: string[];
        }>;
        /** Explicit mixed-generation / mixed-paradigm diagnosis output */
        mixedParadigmDiagnosis?: Array<{
            label: string;
            boundaries: string[];
            migrationRisks: string[];
            evidence: string[];
        }>;
        /** Explicit confidence / provenance summary for task-mode consumers */
        confidenceProvenance?: {
            overallConfidence: 'high' | 'medium' | 'low';
            anchorEvidence: string[];
            semanticEvidence: string[];
            degradedSignals: string[];
            evidence: string[];
        };
        /** Explicit uncertainty hotspots when closure is partial or mixed */
        uncertaintyHotspots?: Array<{
            label: string;
            reason: string;
            evidence: string[];
        }>;
        /** Reviewer-oriented semantic change surface for before/after reasoning */
        semanticDiffs?: Array<{
            label: string;
            before: string[];
            after: string[];
            verify: string[];
            evidence: 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[];
    /** Navigation-only low-noise retrieval path */
    navigationOnly?: boolean;
    /** Retrieval mode used to tune query-time heuristics */
    mode?: 'default' | 'task';
}
export interface RetrievalAnchor {
    node: Node;
    score: number;
    confidence: 'high' | 'medium' | 'low';
    evidence: string[];
    scoreComponents?: Array<{
        category: 'anchor-match' | 'structural-evidence' | 'platform-fact' | 'semantic-grouping' | 'shell-penalty';
        label: string;
        value: number;
    }>;
}
export interface RetrievalSelection {
    candidates: SearchResult[];
    anchors: RetrievalAnchor[];
    confidence: 'high' | 'medium' | 'low';
}
//# sourceMappingURL=types.d.ts.map