import type { RepoManifest } from "../types.js";
import type { FileDisposition, GraphBundle, GraphEdge, NodeMetrics, RouteEdge } from "audit-tools/shared";
import type { ExternalAnalyzerResults } from "audit-tools/shared";
export interface BuildGraphBundleOptions {
    fileContents?: Record<string, string>;
    /** Results from every acquired/imported external analyzer (one entry per tool). */
    externalAnalyzerResults?: ExternalAnalyzerResults[];
    /**
     * Per-file edge cache from a prior build (C2 incremental graph-build). A file's
     * cached contribution is reused only while BOTH the global `path_lookup_hash`
     * still matches (no file added/removed/disposition-changed → import resolution and
     * the cross-file heuristics are unaffected) AND that file's `content_key` is
     * unchanged — the key covers the content hash, whether content was AVAILABLE, and
     * the cache-format version (see {@link graphEdgeCacheKey}). Any drift, or an entry
     * whose shape does not validate, falls back to a fresh extraction (fail-safe).
     */
    priorEdgeCache?: GraphEdgeCache;
    /**
     * Out-param: when present, `buildGraphBundle` deposits the freshly-built per-file
     * edge cache here (covering every in-scope file, reused or re-extracted) so the
     * caller can persist it for the next incremental build. The bundle itself never
     * carries the cache.
     */
    edgeCacheSink?: {
        cache?: GraphEdgeCache;
    };
}
/** One file's cached per-file edge contribution (everything the per-file loop body produces). */
export interface PerFileGraphContribution {
    imports: GraphEdge[];
    calls: GraphEdge[];
    references: GraphEdge[];
    heuristics: GraphEdge[];
    routes: RouteEdge[];
    metrics?: NodeMetrics[string];
}
/**
 * A cache entry: the file's content key + its per-file contribution. The key is
 * minted by {@link graphEdgeCacheKey} and is the ONLY thing reuse is decided on
 * (beyond the cache-wide `path_lookup_hash`), so everything that changes what a
 * contribution contains must be encoded in it.
 */
export interface GraphEdgeCacheEntry {
    content_key: string;
    contribution: PerFileGraphContribution;
}
/**
 * The persisted per-file graph-edge cache (C2). `path_lookup_hash` is the hash of
 * the global in-scope path set; entries are valid only while it matches the fresh
 * build's hash. Keyed by repo-manifest file path.
 */
export interface GraphEdgeCache {
    path_lookup_hash: string;
    entries: Record<string, GraphEdgeCacheEntry>;
}
export declare function buildPathLookup(repoManifest: RepoManifest, dispositionMap: Map<string, FileDisposition["files"][number]["status"]>): Map<string, string>;
/**
 * Dedupe by content signature, then sort by it — both halves content-derived, so
 * a shuffled input array yields byte-identical output (the extractor array-order
 * invariant).
 *
 * The signature is (from, to, kind), which does NOT cover `direction` /
 * `confidence` / `reason`: two extractors can contribute the same edge with
 * different provenance. Keeping "whichever arrived last" made the surviving
 * payload a function of PUSH ORDER; {@link survivesDedupe} decides it by content
 * instead. Serialization runs only on a collision.
 */
export declare function uniqueSortedEdges(edges: GraphEdge[]): GraphEdge[];
export declare function buildGraphBundleFromFs(repoManifest: RepoManifest, root: string, disposition?: FileDisposition, options?: Pick<BuildGraphBundleOptions, "externalAnalyzerResults" | "priorEdgeCache" | "edgeCacheSink">): Promise<GraphBundle>;
/**
 * Version tag carried inside every cache key. Bump it whenever the MEANING of a
 * key or of a cached contribution changes: an entry written under an older tag can
 * never equal a key minted now, so a stale cache degrades to a full re-extraction
 * (fail-safe) instead of replaying contributions built under different rules.
 */
export declare const GRAPH_EDGE_CACHE_KEY_VERSION = "v2";
/**
 * CCU-analyzer-merge-helper-seam (graph half).
 *
 * Append an analyzer's contributed edges into a graph bundle's edge categories,
 * returning a NEW bundle (the input is never mutated). This is the single,
 * pre-shipped seam through which any post-build analyzer contribution —
 * git-history co-change, and any later acquired analyzer — re-enters the graph,
 * so contributions can never drift in how they merge.
 *
 * Merged into `graphs.references` by default (the open-ended cross-file edge
 * category) under one `category` key, then deduped + sorted by the same
 * `uniqueSortedEdges` the build uses, so the result is deterministic and an edge
 * already present (same from/to/kind) is idempotent. Degrades to the original
 * bundle (structurally cloned) when `edges` is empty / not an array.
 */
export declare function mergeAnalyzerGraphContribution(bundle: GraphBundle, edges: GraphEdge[] | undefined, options?: {
    category?: string;
}): GraphBundle;
export declare function buildGraphBundle(repoManifest: RepoManifest, disposition?: FileDisposition, options?: BuildGraphBundleOptions): GraphBundle;
//# sourceMappingURL=graph.d.ts.map