/**
 * Graph type contracts for CLEO code intelligence.
 *
 * Defines the node types, relationship types, and structures that form the
 * foundation of the code intelligence graph. Ported from GitNexus graph
 * primitives and adapted for CLEO's lightweight, in-process use case.
 *
 * @task T512
 * @module contracts/graph
 */
/**
 * All supported symbol node kinds in the code intelligence graph.
 *
 * Covers file/folder structural nodes plus every symbol-level construct
 * that tree-sitter can identify across TypeScript, JavaScript, and future
 * language providers. Includes synthetic graph-level nodes produced by
 * analysis phases (community detection, process detection, route extraction).
 *
 * @since T529 — expanded from T512 baseline with 17 new kinds
 */
export type GraphNodeKind = 'file' | 'folder' | 'module' | 'namespace' | 'function' | 'method' | 'constructor' | 'class' | 'interface' | 'struct' | 'trait' | 'impl' | 'type_alias' | 'enum' | 'property' | 'constant' | 'variable' | 'static' | 'record' | 'delegate' | 'macro' | 'union' | 'typedef' | 'annotation' | 'template' | 'community' | 'process' | 'route' | 'tool' | 'section' | 'import' | 'export' | 'type';
/**
 * All supported directed relationship types between graph nodes.
 *
 * Types are intentionally lowercase to match CLEO convention.
 * Each type carries semantic meaning about the nature of the dependency.
 *
 * @since T529 — expanded from T512 baseline with 10 new relation types
 */
export type GraphRelationType = 'contains' | 'defines' | 'imports' | 'accesses' | 'calls' | 'extends' | 'implements' | 'method_overrides' | 'method_implements' | 'has_method' | 'has_property' | 'member_of' | 'step_in_process' | 'handles_route' | 'fetches' | 'handles_tool' | 'entry_point_of' | 'wraps' | 'queries' | 'documents' | 'applies_to';
/**
 * A node in the code intelligence graph representing a symbol or structural
 * element extracted from source code.
 *
 * The `id` field is a stable identifier for the node, typically derived from
 * the file path and symbol name (e.g., `src/foo.ts::parseFile`).
 */
export interface GraphNode {
    /** Unique, stable node identifier. Typically `<filePath>::<name>`. */
    id: string;
    /** Kind of code element this node represents. */
    kind: GraphNodeKind;
    /** Symbol name as it appears in source code. */
    name: string;
    /** File path relative to the project root. */
    filePath: string;
    /** Start line in the source file (1-based). */
    startLine: number;
    /** End line in the source file (1-based). */
    endLine: number;
    /** Language of the source file (e.g., "typescript", "javascript"). */
    language: string;
    /** Whether the symbol is publicly exported from its module. */
    exported: boolean;
    /** Parent node ID, if this symbol is nested (e.g., method inside class). */
    parent?: string;
    /** Parameter names or signatures for functions and methods. */
    parameters?: string[];
    /** Return type annotation text, if available. */
    returnType?: string;
    /** First line of the TSDoc/JSDoc comment for this symbol, if present. */
    docSummary?: string;
    /** Community ID this node belongs to (set after Phase 5 community detection). */
    communityId?: string;
    /** Execution flow process IDs this node participates in (set after Phase 6). */
    processIds?: string[];
    /** Kind-specific metadata blob (matches nexus_nodes.meta_json). */
    meta?: Record<string, unknown>;
    /** Whether this node represents an external module (unresolved import). */
    isExternal?: boolean;
}
/**
 * Three-state confidence label for extracted edges.
 *
 * Complements the numeric `confidence` field with a categorical classification
 * that maps to the pipeline's resolution tiers:
 *
 * - **`EXTRACTED`** (Tier 1): Statically verifiable from the AST — the
 *   relationship is directly present in source. Covers `defines`, `imports`,
 *   structural containment (`has_method`, `has_property`), and same-file
 *   `calls` / `extends` / `implements`. Numeric confidence ≥ 0.90.
 *
 * - **`INFERRED`** (Tier 2a): Resolved through import-scoped analysis — the
 *   target is reachable via a known import but requires cross-file name
 *   resolution. Covers `accesses`, cross-file `calls`, and cross-file
 *   `extends` / `implements`. Numeric confidence in range 0.80 – 0.89.
 *
 * - **`AMBIGUOUS`** (Tier 3): Global fallback resolution — the target was
 *   found by scanning the entire repository index with no direct import
 *   path. Multiple candidates may exist. Numeric confidence < 0.80.
 *
 * @since T1862
 */
export type GraphEdgeConfidenceLabel = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
/**
 * Map a numeric confidence value to a {@link GraphEdgeConfidenceLabel}.
 *
 * Thresholds align with the pipeline resolution tiers defined in
 * `resolution-context.ts`:
 * - ≥ 0.90 → `EXTRACTED`  (same-file 0.95, import-scoped 0.90, defines 1.0)
 * - 0.80 – 0.89 → `INFERRED`   (accesses 0.80, heritage import-scoped 0.85)
 * - < 0.80 → `AMBIGUOUS`  (global 0.50, speculative)
 *
 * @param confidence - Numeric confidence in range [0.0, 1.0]
 * @returns The corresponding three-state label
 */
export declare function confidenceLabelFromNumeric(confidence: number): GraphEdgeConfidenceLabel;
/**
 * Structured provenance for an EXTRACTED confidence assignment.
 *
 * Used when confidence was derived from direct AST evidence (same-file
 * lookup, import-scoped resolution) or an explicit source annotation.
 *
 * @since T9145
 */
export interface ExtractedProvenance {
    /** Discriminant. */
    readonly kind: 'extracted';
    /**
     * AST / static-analysis source that produced this confidence value.
     * Examples: `"ast"`, `"import-scope"`, `"same-file"`, `"defines"`.
     */
    readonly source: string;
}
/**
 * Structured provenance for an INFERRED confidence assignment.
 *
 * Used when confidence was derived from resolution heuristics (cross-file
 * type lookup, heritage-map inference, name matching).
 *
 * @since T9145
 */
export interface InferredProvenance {
    /** Discriminant. */
    readonly kind: 'inferred';
    /**
     * Heuristic or rule that produced this confidence value.
     * Examples: `"heritage-map"`, `"name-match"`, `"global-tier"`.
     */
    readonly heuristic: string;
}
/**
 * Structured provenance for an AMBIGUOUS confidence assignment.
 *
 * Used when confidence is low because multiple candidates were found,
 * the parent is external / unresolvable, or resolution fell to a global stub.
 *
 * @since T9145
 */
export interface AmbiguousProvenance {
    /** Discriminant. */
    readonly kind: 'ambiguous';
    /**
     * Candidate node IDs that competed for this resolution slot.
     * May be empty when the ambiguity is due to an unresolvable external type.
     */
    readonly candidates: ReadonlyArray<string>;
}
/**
 * Discriminated union of structured confidence provenance variants.
 *
 * Replaces the bare numeric `confidence` field on {@link GraphRelation} as
 * part of the Beta gradient deprecation (phase 0: addition, phase 1:
 * co-existence, removal at v2026.9).
 *
 * **Backfill mapping** for existing records created without structured
 * provenance:
 * - `confidence === 1.0` → `{ kind: 'extracted', source: 'ast' }`
 * - `confidence >= 0.90` → `{ kind: 'extracted', source: 'legacy' }`
 * - `confidence >= 0.80` → `{ kind: 'inferred', heuristic: 'legacy' }`
 * - `confidence < 0.80`  → `{ kind: 'ambiguous', candidates: [] }`
 *
 * @since T9145
 * @deprecated Numeric `confidence` on {@link GraphRelation} will be removed in v2026.9.
 *   Use `confidenceProvenance` instead. Migration: `confidenceFromProvenance()` maps back.
 */
export type ConfidenceProvenance = ExtractedProvenance | InferredProvenance | AmbiguousProvenance;
/**
 * Backfill a {@link ConfidenceProvenance} from a legacy numeric confidence value.
 *
 * @param confidence - Numeric confidence in range [0.0, 1.0]
 * @returns A structured provenance record consistent with the numeric value
 * @since T9145
 */
export declare function provenanceFromNumeric(confidence: number): ConfidenceProvenance;
/**
 * Recover a numeric confidence value from a {@link ConfidenceProvenance} record.
 *
 * Inverse of {@link provenanceFromNumeric} for backward-compat bridging.
 *
 * @param provenance - Structured provenance record
 * @returns Best-effort numeric confidence in range [0.0, 1.0]
 * @since T9145
 */
export declare function confidenceFromProvenance(provenance: ConfidenceProvenance): number;
/**
 * A directed relationship between two nodes in the code intelligence graph.
 *
 * The `source` and `target` fields reference node IDs (see {@link GraphNode.id}).
 * Confidence reflects how certain the extractor is about this relationship,
 * from 0.0 (speculative) to 1.0 (statically verified).
 *
 * The `confidenceLabel` field provides a categorical three-state classification
 * (see {@link GraphEdgeConfidenceLabel}) derived from the numeric `confidence`.
 * Both fields are kept for backward compatibility: existing consumers that read
 * the numeric field are unaffected; new consumers can use the label directly.
 */
export interface GraphRelation {
    /** ID of the originating node. */
    source: string;
    /** ID of the target node. */
    target: string;
    /** Semantic type of the relationship. */
    type: GraphRelationType;
    /**
     * Extractor confidence for this relationship (0.0 to 1.0).
     *
     * Common values by type:
     * - `calls` / `imports`: 0.9 (direct, strongly typed)
     * - `extends` / `implements`: 0.85 (statically verifiable)
     * - `has_method` / `has_property`: 0.95 (structural containment)
     * - `accesses`: 0.8 (field read/write, may be indirect)
     */
    confidence: number;
    /**
     * Three-state categorical label derived from the numeric `confidence` tier.
     *
     * Optional for backward compatibility with callers that construct
     * `GraphRelation` objects directly. Pipeline code SHOULD populate this
     * field. See {@link GraphEdgeConfidenceLabel} and
     * {@link confidenceLabelFromNumeric} for values and thresholds.
     */
    confidenceLabel?: GraphEdgeConfidenceLabel;
    /** Human-readable note explaining why this relation was emitted. */
    reason?: string;
}
/**
 * Result of a BFS-based impact analysis starting from a named symbol.
 *
 * Affected nodes are grouped into three depth tiers that reflect the
 * likelihood and urgency of breakage:
 *
 * - **depth1_willBreak** (d=1): Direct callers/importers — WILL break.
 *   Must be updated whenever the target changes.
 * - **depth2_likelyAffected** (d=2): Indirect dependants — LIKELY affected.
 *   Should be tested.
 * - **depth3_mayNeedTesting** (d=3): Transitive dependants — MAY need testing.
 *   Test if the symbol is on a critical path.
 */
export interface ImpactResult {
    /** Name or ID of the symbol that was analyzed. */
    target: string;
    /**
     * Overall risk classification based on the number and type of affected nodes.
     *
     * - `low`: 0–3 direct dependants, no cross-module spread
     * - `medium`: 4–9 direct dependants, or limited cross-module spread
     * - `high`: 10+ direct dependants, or significant cross-module spread
     * - `critical`: Exported symbol with high cross-module usage
     */
    riskLevel: 'low' | 'medium' | 'high' | 'critical';
    /** Human-readable summary of the impact analysis outcome. */
    summary: string;
    /** Nodes affected at each traversal depth. */
    affectedByDepth: {
        /** d=1: Direct dependants — WILL BREAK. */
        depth1_willBreak: GraphNode[];
        /** d=2: Indirect dependants — LIKELY AFFECTED. */
        depth2_likelyAffected: GraphNode[];
        /** d=3: Transitive dependants — MAY NEED TESTING. */
        depth3_mayNeedTesting: GraphNode[];
    };
    /** Total number of affected nodes across all depths. */
    totalAffected: number;
}
/**
 * An in-memory symbol table entry tracking all files where a name appears.
 * Used during ingestion to resolve cross-file call targets.
 */
export interface SymbolIndex {
    /** Symbol name as it appears in source (e.g., "parseFile"). */
    name: string;
    /** All node IDs that define this name across the project. */
    nodeIds: string[];
    /** All file paths that export this name. */
    exportingFiles: string[];
}
/**
 * The in-memory KnowledgeGraph assembled during a single ingestion run.
 * Flushed to nexus_nodes + nexus_relations after all phases complete.
 */
export interface KnowledgeGraph {
    /** Primary node store: nodeId → GraphNode. */
    nodes: Map<string, GraphNode>;
    /** All directed edges (appended during ingestion, deduplicated at flush). */
    relations: GraphRelation[];
    /** Indexes for fast lookup during resolution phases. */
    symbolTable: SymbolIndex[];
    /** Files that changed since last index (incremental mode only). */
    changedFiles?: Set<string>;
}
/**
 * A community (module cluster) identified by Louvain community detection
 * during Phase 5. Represents a group of cohesive symbols within the graph.
 */
export interface CommunityNode {
    /** Node ID format: `community:<n>` */
    id: string;
    /** Inferred label from the top folder name. */
    label: string;
    /** Number of member symbols in this community. */
    memberCount: number;
    /** Top-level folders contributing most members. */
    topFolders: string[];
}
/**
 * A detected execution flow (process) from BFS entry point analysis
 * during Phase 6. Represents a named sequence of function calls.
 */
export interface ProcessNode {
    /** Node ID format: `process:<slug>` */
    id: string;
    /** Entry point function name used as the process label. */
    label: string;
    /** Node ID of the entry point function. */
    entryPointId: string;
    /** Ordered node IDs representing each step in the flow. */
    stepIds: string[];
    /** Total number of steps in this execution flow. */
    stepCount: number;
}
//# sourceMappingURL=graph.d.ts.map