import type { Adapter } from "../../adapters/types.js";
import { type EdgeDiffOutcome, type ObservedEdgePair, type TopologyModel } from "../../views/topology-html.js";
export type LoadObservedEdgesResult = {
    ok: true;
    edges: ObservedEdgePair[];
    observableComponents?: string[];
    observableTargetKinds?: string[];
} | {
    ok: false;
    error: string;
};
/**
 * Reads + validates the `--compare-edges` file. Every failure mode (missing
 * file, invalid JSON, schema violation) returns `{ok:false}` with a message
 * — NEVER an empty edge list. This distinction matters: a caller that
 * silently treated "couldn't load" the same as "loaded, zero rows" would
 * make `computeTopologyEdgeDiff`'s `observedTotal` read 0 and
 * `staticCoverage` read `null` ("nothing to compare") instead of surfacing
 * that the comparison never ran at all — exactly the "假绿" (false green)
 * this feature exists to prevent (see the PR's own review brief).
 */
export declare function loadObservedEdges(path: string): Promise<LoadObservedEdgesResult>;
export type TopologyResult = {
    ran: true;
    outputPath: string;
    model: TopologyModel;
    /** Present only when `--compare-edges` was passed — see `EdgeDiffOutcome`'s doc for the ok/error split. */
    edgeDiff?: EdgeDiffOutcome;
} | {
    ran: false;
    skippedReason: string;
    /**
     * `config_error`: `.loopgraph/config.json`'s `components` section
     * exists but failed validation — a real problem the CLI should surface
     * as an error, not a routine warning (mirrors `check`'s own
     * `inv1ConfigError`, which run.ts logs via `io.error` with a "✗"
     * prefix, not lumped in with an ordinary advisory skip).
     * `no_components`: nothing is declared — a normal, unconfigured state.
     * Kept as a discriminant rather than string-sniffing `skippedReason`
     * so the CLI's choice of log severity can never drift from the reason
     * text if either wording changes later.
     */
    skipKind: "config_error" | "no_components";
};
export interface TopologyOptions {
    /**
     * Repo checkout root to extract facts from. Unlike `graph`/`overview` (which
     * always have the model to fall back on), `topology` has NO structural
     * source without facts — omitting this still renders (declared components,
     * zero edges), because the components legend alone is honest, useful output,
     * not nothing.
     */
    repoRoot?: string | undefined;
    adapter?: Adapter | undefined;
    /** Output path override; defaults to `<dir>/.loopgraph/ws/topology.html`. */
    out?: string | undefined;
    cacheDir?: string | null | undefined;
    /**
     * Path to a `--compare-edges` file (see `loadObservedEdges`'s doc for the
     * shape) — diffs the extractor's own edges against it (issue #23 §4).
     * Omitted → no diff attempted, output identical to before this option
     * existed.
     */
    compareEdges?: string | undefined;
}
/**
 * `loopgraph topology`: a self-contained HTML architecture diagram rendered
 * PURELY from declared `components` (§ config/components.ts) + facts carrying
 * a `topology` hint (§ adapters/types.ts) — issue #23 P0. See
 * `views/topology-html.ts`'s module doc comment for why this reads no
 * `.loopgraph/model/` file and adds no model node kind: the whole point is to
 * ship the picture before any model decision about a topology dimension is
 * made, and let actual usage be the evidence for whether one is needed.
 *
 * Loud-skip discipline, same family as `graph`/`overview`/`snapshot`: a
 * malformed `components` config is a hard `ran: false` (never silently
 * treated as "no components" — see `loadComponents`'s own contract), and so
 * is a target with no components declared at all, because there is nothing
 * this command can meaningfully draw without at least one. Missing facts
 * (`--repo-root` absent, or the adapter chose not to run) is NOT a skip —
 * it degrades to a components-only render with zero edges and a banner that
 * says so, because the entry-type legend by itself already answers a
 * question ("what units does this repo have, and what kind is each").
 */
export declare function runTopology(targetDir: string, options?: TopologyOptions): Promise<TopologyResult>;
//# sourceMappingURL=topology.d.ts.map