@vibgrate/cli 2026.702.1 → 2026.703.1

package/dist/index.d.ts

@@ -1 +1,1010 @@
-export { DependencyRow, DriftScore, Finding, ProjectScan, RiskLevel, ScanArtifact, ScanOptions, VibgrateConfig, computeDriftScore, formatMarkdown, formatSarif, formatText, generateFindings, runScan } from '@vibgrate/core';
+import { G as GraphNode, a as GraphEdge, A as Area, R as ResolverKind, V as VgGraph, F as FileParse, E as EdgeKind, b as Fact, c as GroundingKind, d as GroundingEdge } from './types-C6ZyQpa9.js';
+export { C as Centrality, D as DerivedBy, e as FactConfidence, f as FactKind, g as GraphMeta, N as NodeKind, P as Provenance, S as SCHEMA_VERSION, h as Span } from './types-C6ZyQpa9.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+
+declare const VERSION = "2026.703.1";
+
+/**
+ * Analysis stage: importance, centrality, hubs, communities, and surprise.
+ *
+ * - **Centrality** blends PageRank + betweenness + eigenvector + degree over the
+ *   dependency graph (call/import/extends/implements/references), catching
+ *   high-fan-in critical nodes that degree-only ranking (Graphify) misses.
+ * - **Communities** via Louvain (`graphology-communities-louvain`, MIT), seeded
+ *   and single-pass for determinism. Leiden (via a permissive WASM impl) is a
+ *   later enhancement; the cluster mode is reported honestly, never silent.
+ * - **Hubs** are centrality outliers (importance ≥ mean + 2σ).
+ * - **Surprise** flags improbable cross-area edges (architectural smells),
+ *   surfaced by `vg oddities`.
+ *
+ * Pure and deterministic: identical (nodes, edges) → identical result.
+ */
+type ClusterMode = 'leiden' | 'louvain' | 'none';
+interface AnalyzeOptions {
+    cluster?: ClusterMode;
+    /** Skip betweenness above this node count (O(V·E) — too slow for huge graphs). */
+    betweennessLimit?: number;
+}
+interface AnalyzeResult {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    areas: Area[];
+    cluster: ClusterMode;
+}
+declare function analyze(nodes: GraphNode[], edges: GraphEdge[], options?: AnalyzeOptions): AnalyzeResult;
+
+/**
+ * Module resolution for import edges. Resolves an import specifier (relative,
+ * `tsconfig` path alias, or workspace-package name) to a repo-relative file —
+ * the fix for alias-heavy TS monorepos (Nx/Turborepo) where every cross-package
+ * import looked "external" and tanked call resolution.
+ *
+ * Deterministic: it reads the repo's tsconfig(s) and workspace manifests once at
+ * construction, then `resolve()` is pure over those in-memory maps. Still the
+ * heuristic rung — precise SCIP/stack-graphs slot above it later — but now
+ * scope-aware of the project's own module map.
+ */
+interface ModuleResolver {
+    /** Resolve `source` imported from `fromRel`; returns a repo-rel path or null (external). */
+    resolve(fromRel: string, source: string): string | null;
+}
+declare function buildModuleResolver(root: string, relSet: Set<string>): ModuleResolver;
+/** A resolver that only handles relative imports (no fs) — for tests/embedding. */
+declare function relativeResolver(relSet: Set<string>): ModuleResolver;
+declare function parseJsonc<T = unknown>(text: string): T;
+
+/**
+ * Resolution: turn per-file symbol/edge tables into a connected graph of nodes
+ * and typed, id'd edges.
+ *
+ * The Phase-0 resolver is the deterministic **heuristic** rung of the ladder
+ * (VG-ENGINE-TEARDOWN §3.2). It is already well beyond Graphify's
+ * single-candidate label match: it is scope-aware (same-file first), import-aware
+ * (callees reachable through imported files next), and arity/visibility-honest
+ * (records its confidence and resolution rung per edge rather than silently
+ * dropping ambiguity). SCIP/stack-graphs rungs slot in above it later, recorded
+ * via `edge.resolution`.
+ */
+interface ResolveResult {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    /** Diagnostic counts, surfaced by `vg status`. */
+    stats: {
+        callsResolved: number;
+        callsUnresolved: number;
+        importsResolvedToFile: number;
+        importsExternal: number;
+        resolvers: ResolverKind[];
+    };
+}
+
+interface BuildOptions {
+    /** Directory to build (default cwd). */
+    root: string;
+    /** Restrict to language ids. */
+    only?: string[];
+    /** Extra ignore globs (gitignore syntax). */
+    exclude?: string[];
+    /** Sub-paths to scope to. */
+    paths?: string[];
+    /** Worker count; 1 forces inline. */
+    jobs?: number;
+    /** Force single-threaded parsing. */
+    inline?: boolean;
+    /** Disable the incremental cache (full rebuild). */
+    noCache?: boolean;
+    /** Heavier open passes (recorded in provenance; Phase 1+ wires the analyses). */
+    deep?: boolean;
+    /** Community detection mode (default 'louvain'). */
+    cluster?: ClusterMode;
+    /** Coverage report paths (default: auto-detect lcov/istanbul). */
+    coverage?: string[];
+    /** Skip coverage ingestion. */
+    noCoverage?: boolean;
+    /** Skip grounding (free knowledge pack). Default: grounding on. */
+    noGround?: boolean;
+    /** Path to a SCIP index to ingest (default: auto-detect index.scip). */
+    scip?: string;
+    /** Skip SCIP ingestion even if an index is present. */
+    noScip?: boolean;
+    /** Skip the in-process TypeScript Compiler API resolver (heuristic floor only). */
+    noTsc?: boolean;
+    /** Pin the artifact timestamp for byte-deterministic output. */
+    generatedAt?: string;
+    /** Live progress during the parse phase (files done of total). */
+    onParseProgress?: (done: number, total: number) => void;
+    /** Override directory for grammar .wasm files (offline / air-gapped). */
+    grammarsDir?: string;
+}
+/** Stat + content hash of one corpus file at build time. */
+interface FileStat {
+    rel: string;
+    size: number;
+    mtimeMs: number;
+    hash: string;
+}
+interface BuildResult {
+    graph: VgGraph;
+    timing: {
+        totalMs: number;
+    };
+    reparsed: number;
+    reused: number;
+    totalFiles: number;
+    /** Stat+hash of every file in the corpus — input for the freshness snapshot. */
+    fileStats: FileStat[];
+    resolveStats: ResolveResult['stats'];
+    /** Present when the TypeScript Compiler API resolver ran (TS/JS files). */
+    tsc?: {
+        files: number;
+        calls: number;
+        jsx: number;
+        heritage: number;
+        resolved: number;
+    };
+    /** Present when a SCIP index was ingested. */
+    scip?: {
+        documents: number;
+        references: number;
+        resolved: number;
+        tool?: string;
+    };
+    warnings: string[];
+}
+declare function buildGraph(options: BuildOptions): Promise<BuildResult>;
+
+/** Load a committed `graph.json`. Returns null if none exists at the path. */
+declare function loadGraph(root: string, graphPath?: string): VgGraph | null;
+
+/**
+ * Deterministic serialization of `graph.json`.
+ *
+ * Object keys are sorted recursively and arrays are emitted in the (already
+ * stable) order the engine produced them, so two runs over identical content
+ * yield byte-identical output — the determinism contract (VG-CLI-SPEC §1.3).
+ * Pretty-printed (2-space) and newline-terminated so the committed artifact is
+ * human-diffable and plays well with the union merge driver.
+ */
+declare function serializeGraph(graph: VgGraph): string;
+declare function stableStringify(value: unknown, indent?: number): string;
+declare function parseGraph(json: string): VgGraph;
+
+/**
+ * Write the build artifacts under `.vibgrate/`. `graph.json` is the committable
+ * map; `GRAPH_REPORT.md` and `graph.html` are convenience artifacts (volatile —
+ * gitignored by default via `vg share`).
+ */
+interface WriteOptions {
+    root: string;
+    html?: boolean;
+    report?: boolean;
+    graphPath?: string;
+}
+interface WrittenArtifacts {
+    graphPath: string;
+    reportPath?: string;
+    htmlPath?: string;
+    factsPath?: string;
+}
+declare function vibgrateDir(root: string): string;
+declare function defaultGraphPath(root: string): string;
+declare function writeArtifacts(graph: VgGraph, options: WriteOptions): WrittenArtifacts;
+
+interface VerifyResult {
+    ok: boolean;
+    checks: {
+        name: string;
+        ok: boolean;
+        detail?: string;
+    }[];
+    digest: string;
+}
+declare function verifyDeterminism(opts: {
+    root: string;
+    only?: string[];
+    exclude?: string[];
+    jobs?: number;
+}): Promise<VerifyResult>;
+
+/**
+ * Deterministic Markdown summary (`GRAPH_REPORT.md`). Given a pinned
+ * `generatedAt`, the report is byte-stable. Numbers are derived purely from the
+ * graph, so the report can be regenerated from a committed `graph.json`.
+ */
+declare function renderReport(graph: VgGraph): string;
+
+/**
+ * Phase-0 `graph.html`: a self-contained, dependency-free, deterministic
+ * overview (summary + most-connected definitions + per-file breakdown), with the
+ * full graph embedded as JSON for tooling. The interactive WebGL view (sigma.js
+ * over a ForceAtlas2 layout, scaling past ~5k nodes — VG-ENGINE-TEARDOWN §3.12)
+ * lands in Phase 1; this keeps the artifact present, honest, and byte-stable now.
+ */
+declare function renderHtml(graph: VgGraph): string;
+
+/**
+ * SCIP ingestion — the precise resolution rung (VG-ENGINE-TEARDOWN §3.2).
+ *
+ * Reads a real SCIP index (`index.scip`) produced by a language indexer
+ * (scip-typescript, scip-python, scip-java, rust-analyzer→SCIP, …) and turns its
+ * precise occurrences into call/reference edges at `resolution: "scip"`,
+ * confidence 1.0 — the genuine "real SCIP vs Graphify's fake-SCIP" win. vg does
+ * NOT bundle indexers; it consumes an index the user/CI generates (deterministic,
+ * offline). The heuristic resolver remains the floor for files SCIP didn't cover.
+ *
+ * A small, dependency-free protobuf reader decodes only the fields we need, so
+ * the core stays lean.
+ */
+
+interface ScipOccurrence {
+    /** [startLine, startChar, endLine, endChar] or [startLine, startChar, endChar], 0-based. */
+    range: number[];
+    symbol: string;
+    roles: number;
+}
+interface ScipDocument {
+    relativePath: string;
+    occurrences: ScipOccurrence[];
+}
+interface ScipIndex {
+    documents: ScipDocument[];
+    toolName?: string;
+    toolVersion?: string;
+}
+declare function decodeScipIndex(buf: Uint8Array): ScipIndex;
+interface ScipResult {
+    edges: GraphEdge[];
+    /** Repo-relative files SCIP covered (it is authoritative for these). */
+    coveredFiles: Set<string>;
+    /** counts for status/provenance. */
+    stats: {
+        documents: number;
+        references: number;
+        resolved: number;
+    };
+}
+/**
+ * Build precise edges from a SCIP index, mapped onto our nodes by (file, line).
+ * A reference occurrence's enclosing node → the node where its symbol is defined.
+ */
+declare function scipEdges(index: ScipIndex, nodes: GraphNode[], relForScip: (p: string) => string): ScipResult;
+
+/**
+ * Language registry: 20 supported languages (first wave + the Phase-3 expansion).
+ *
+ * Each language maps to a tree-sitter grammar shipped (pre-compiled to .wasm) by
+ * `tree-sitter-wasms`. `grammarFile` is the base name under that package's `out/`
+ * directory (and our bundled `grammars/` copy). The grammar *version* is recorded
+ * in provenance so the determinism contract is explicit about its inputs.
+ */
+interface LanguageDef {
+    /** Canonical short id used in the schema (`lang` field) and `--only`. */
+    id: string;
+    /** Human label. */
+    label: string;
+    /** File extensions (lowercase, with leading dot). */
+    extensions: string[];
+    /** tree-sitter-wasms grammar base name, e.g. `tree-sitter-typescript`. */
+    grammarFile: string;
+}
+declare const LANGUAGES: LanguageDef[];
+declare function langForExtension(ext: string): LanguageDef | undefined;
+declare function langById(id: string): LanguageDef | undefined;
+declare function allLanguageIds(): string[];
+
+/**
+ * Deterministic file discovery.
+ *
+ * Respects `.gitignore` (including nested ones), explicit config excludes, and a
+ * built-in SKIP_DIRS set consistent with the scanner. Results are returned
+ * sorted by relative POSIX path so the build is order-independent of the
+ * filesystem.
+ */
+declare const SKIP_DIRS: Set<string>;
+interface DiscoverOptions {
+    /** Absolute root directory. */
+    root: string;
+    /** Restrict to these language ids (e.g. ['ts','py']). Empty = all. */
+    only?: string[];
+    /** Additional ignore globs (gitignore syntax), e.g. from config `exclude`. */
+    exclude?: string[];
+    /** Explicit sub-paths to scope to (relative or absolute). */
+    paths?: string[];
+}
+interface DiscoveredFile {
+    /** Relative POSIX path from root. */
+    rel: string;
+    /** Absolute path. */
+    abs: string;
+    lang: LanguageDef;
+}
+declare function discover(options: DiscoverOptions): DiscoveredFile[];
+/** A usage error that maps to exit code 5 at the CLI boundary. */
+declare class UsageError extends Error {
+    readonly isUsageError = true;
+    constructor(message: string);
+}
+
+declare function parseSource(rel: string, langId: string, source: string): Promise<FileParse>;
+
+/**
+ * Local-embedding semantic search for `vg ask --semantic`/`--deep` (no API key).
+ *
+ * The embedding backend is an OPTIONAL, lazily-loaded dependency (`fastembed`,
+ * Apache-2.0, local ONNX) so the core install stays lean and `ask` never breaks:
+ * if the backend or model isn't available it degrades to (prefix-fuzzy) lexical
+ * search with a clear note. Embeddings are query-time + cached under
+ * `.vibgrate/cache/` (keyed by node-text hash); they are NEVER written into the
+ * committed `graph.json`, so the artifact stays byte-deterministic.
+ *
+ * `--local` disables the model download (semantic is skipped unless already
+ * cached via an injected backend), keeping the air-gapped guarantee.
+ */
+interface Embedder {
+    /** Stable model id (recorded with cached vectors so a model change invalidates them). */
+    id: string;
+    /** Embed documents → unit-or-raw vectors (cosine handles normalization). */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Embed a single query string. */
+    embedQuery(text: string): Promise<number[]>;
+}
+/** Why semantic fell back to lexical — for calm, specific messaging. */
+type EmbedUnavailable = 'not-installed' | 'no-permission' | 'download-failed' | 'init-failed';
+interface LoadEmbedderOptions {
+    local?: boolean;
+    model?: string;
+    noDownload?: boolean;
+    showDownloadProgress?: boolean;
+    onUnavailable?: (reason: EmbedUnavailable) => void;
+}
+/**
+ * Try to load the optional local embedding backend. Returns null (→ caller falls
+ * back to lexical) when running `--local`, when the dependency isn't installed,
+ * or when the model can't initialize.
+ */
+declare function loadEmbedder(options?: LoadEmbedderOptions): Promise<Embedder | null>;
+/**
+ * The text we embed for a node. Alongside identity + signature we add the
+ * strongest available signal — the node's **doc-comment / docstring** summary —
+ * plus lightweight context already on the graph (file-path words, area label), so
+ * a tersely-named symbol (`Table`, `NotificationJob`) a concept query can reach.
+ * Only the short, truncated doc summary is used (captured at build time); no full
+ * file bodies, so the graph artifact stays deterministic.
+ */
+declare function nodeEmbedText(node: GraphNode, areaLabel?: string): string;
+declare function cosine(a: number[], b: number[]): number;
+/** Reports embedding progress: how many of `total` nodes are done so far. */
+type EmbedProgress = (done: number, total: number) => void;
+/**
+ * Node embeddings for the searchable (non-file/external) nodes, cache-backed:
+ * only nodes whose embed-text changed are re-embedded. The first run embeds in
+ * chunks, **persists the cache incrementally** (so an interrupted/timed-out run
+ * resumes instead of wasting the work), and reports progress via `onProgress`.
+ */
+declare function getNodeEmbeddings(graph: VgGraph, embedder: Embedder, root: string, onProgress?: EmbedProgress): Promise<Map<string, number[]>>;
+
+/**
+ * Deterministic retrieval for `vg ask` (VG-CLI-SPEC §3.2).
+ *
+ * Builds a structured, fact-annotated, budget-bounded context block for a
+ * question — designed to drop straight into an assistant's context. The default
+ * is deterministic lexical+structural retrieval (identifier/term matching with
+ * morphological prefix-fuzzing, ranked by importance). `--semantic`/`--deep` adds
+ * a hybrid local-embedding pass (`queryGraphSemantic`) that surfaces conceptually
+ * related code even when no word is shared — still no API key.
+ */
+interface QueryOptions {
+    budget?: number;
+    limit?: number;
+}
+interface QueryMatch {
+    node: GraphNode;
+    score: number;
+    why: string;
+}
+interface QueryResult {
+    question: string;
+    matches: QueryMatch[];
+    context: string;
+    tokensEstimate: number;
+}
+declare function queryGraph(graph: VgGraph, question: string, options?: QueryOptions): QueryResult;
+interface SemanticQueryOptions extends QueryOptions {
+    embedder: Embedder;
+    /** Precomputed node vectors (from getNodeEmbeddings); falls back to lexical for nodes without one. */
+    nodeVectors: Map<string, number[]>;
+}
+/**
+ * Hybrid lexical + local-embedding retrieval. Blends the normalized lexical score
+ * with cosine similarity to the query embedding (50/50), so a question like
+ * "where do we handle auth failures?" can surface `verify_token` even with no
+ * shared identifier. Deterministic given the same model + cached vectors;
+ * embeddings live only in the cache, never in `graph.json`.
+ */
+declare function queryGraphSemantic(graph: VgGraph, question: string, options: SemanticQueryOptions): Promise<QueryResult>;
+/** camelCase / snake_case / kebab split of an identifier → lowercased parts. */
+declare function identifierParts(name: string): Set<string>;
+
+/**
+ * Lenient node resolution (VG-CLI-SPEC §3.3): resolve `<name>` by content-hash
+ * id, qualified name, `file:line`, short name, or glob. Returns candidates
+ * ranked by importance so the best match is first; ambiguity is surfaced (the
+ * caller offers `--pick`). Deterministic ordering throughout.
+ */
+declare function findNodes(graph: VgGraph, query: string): GraphNode[];
+/** Resolve to a single node, honoring a 1-based `--pick`. */
+declare function resolveOne(graph: VgGraph, query: string, pick?: number): {
+    node?: GraphNode;
+    candidates: GraphNode[];
+};
+declare function nodeById(graph: VgGraph, id: string): GraphNode | undefined;
+
+interface ImpactItem {
+    id: string;
+    name: string;
+    kind: string;
+    file: string;
+    line: number;
+    depth: number;
+    confidence: number;
+}
+interface ImpactResult {
+    root: {
+        id: string;
+        name: string;
+    };
+    depth: number;
+    affected: ImpactItem[];
+    direct: number;
+    transitive: number;
+    /** Lowest edge confidence encountered (e.g. a dynamic-dispatch edge). */
+    minEdgeConfidence: number;
+}
+declare function impactOf(graph: VgGraph, rootId: string, opts?: {
+    depth?: number;
+}): ImpactResult;
+
+/**
+ * Shortest connection between two nodes (`vg path`). Uses graphology's
+ * bidirectional BFS over the directed graph; falls back to the reverse direction
+ * so "how does A connect to B" still answers when the dependency arrow runs B→A.
+ */
+interface PathResult {
+    ids: string[];
+    direction: 'forward' | 'reverse';
+}
+declare function shortestPath(graph: VgGraph, srcId: string, dstId: string): PathResult | null;
+
+/** Indexes over a graph for O(1) neighbor lookups (built once per command). */
+declare class GraphIndex {
+    readonly graph: VgGraph;
+    readonly nodeById: Map<string, GraphNode>;
+    private outById;
+    private inById;
+    constructor(graph: VgGraph);
+    out(id: string, kind?: EdgeKind): GraphEdge[];
+    in(id: string, kind?: EdgeKind): GraphEdge[];
+    node(id: string): GraphNode | undefined;
+    /** Resolved nodes called by `id`. */
+    callees(id: string): {
+        edge: GraphEdge;
+        node: GraphNode;
+    }[];
+    /** Resolved nodes that call `id`. */
+    callers(id: string): {
+        edge: GraphEdge;
+        node: GraphNode;
+    }[];
+    private resolveTargets;
+}
+
+/**
+ * The read-only tool set for the LOCAL `vg serve` MCP. Every tool is
+ * side-effect-free and `readOnlyHint: true` (auto-approvable), and independent of
+ * Vibgrate's hosted cloud MCP. The server is local-first; network access is
+ * limited to the embedder's one-time model fetch, `upgrade_impact`'s `changelog`
+ * option, and `library_docs`' hosted-catalog fall-through on a thin/missing local
+ * doc — all disabled under `--local` (the hard airgap).
+ *
+ * Phase 2/3 add `tests_for`, `get_facts`, `guide_node`, `check_drift`,
+ * `list_models`, `resolve_library`, `library_docs`.
+ */
+interface ToolContext {
+    /** Project root (for filesystem-backed tools: drift, models). */
+    root: string;
+    /** `--local`: keep the server air-gapped — no model download, lexical only. */
+    local?: boolean;
+    /** `--dedup`: collapse a node's heavy relation lists on repeat reads this session. */
+    dedup?: boolean;
+    /** Per-session set of node ids already returned in full (drives `--dedup`). */
+    seen?: Set<string>;
+}
+interface VgTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (graph: VgGraph, args: Record<string, unknown>, ctx: ToolContext) => unknown | Promise<unknown>;
+}
+declare const TOOLS: VgTool[];
+
+interface ServeOptions {
+    /** Record local, counts-only usage savings (opt-in). */
+    savings?: boolean;
+    /** Air-gapped mode (no model downloads). */
+    local?: boolean;
+    /** Collapse repeat heavy relation lists within a session (opt-in). */
+    dedup?: boolean;
+    /** Auto-refresh the map when the working tree drifts (default true). */
+    refresh?: boolean;
+}
+declare class GraphSource {
+    readonly graphPath: string;
+    private readonly refresh;
+    /** Timing overrides (tests only). */
+    private readonly tuning;
+    private cachedMtimeMs;
+    private cached;
+    private readonly root;
+    private lastProbeAt;
+    private failedUntil;
+    private inflight;
+    /** Self-tuned: grows with measured probe cost so huge repos aren't penalized. */
+    private probeIntervalMs;
+    constructor(graphPath: string, refresh?: boolean, 
+    /** Timing overrides (tests only). */
+    tuning?: {
+        probeIntervalMs?: number;
+        refreshBudgetMs?: number;
+    });
+    /** Current graph: auto-refreshed if the tree drifted, reloaded if the file changed. */
+    get(): Promise<VgGraph>;
+    /**
+     * Debounced, single-flight refresh. Never throws — a refresh problem must
+     * degrade to "answer from the current map", not break the tool call.
+     */
+    private maybeRefresh;
+}
+declare function createServer(source: GraphSource, opts?: ServeOptions): Server;
+declare function serveStdio(graphPath: string, opts?: ServeOptions): Promise<void>;
+
+/** The graph-affecting discovery/build scope, replayed verbatim on refresh. */
+interface BuildScope {
+    only?: string[];
+    exclude?: string[];
+    paths?: string[];
+    deep?: boolean;
+    noGround?: boolean;
+    scip?: string;
+    noScip?: boolean;
+    noTsc?: boolean;
+    cluster?: string;
+    grammarsDir?: string;
+}
+interface SnapshotFile {
+    version: string;
+    /** corpusHash of the build this snapshot belongs to. */
+    corpusHash: string;
+    scope: BuildScope;
+    files: Record<string, {
+        size: number;
+        mtimeMs: number;
+        hash: string;
+    }>;
+}
+interface Drift {
+    /** Files whose *content* changed (stat moved AND hash differs). */
+    changed: string[];
+    /** Files present now but absent from the snapshot. */
+    added: string[];
+    /** Snapshot files no longer present. */
+    removed: string[];
+}
+interface ProbeResult {
+    drift: Drift;
+    /** The recorded build scope — what a refresh must replay. */
+    scope: BuildScope;
+    /** corpusHash the current map was built from. */
+    corpusHash: string;
+}
+/** Persist the snapshot after a successful build. Best-effort (cache-only). */
+declare function writeSnapshot(root: string, corpusHash: string, fileStats: FileStat[], scope?: BuildScope): void;
+declare function loadSnapshot(root: string): SnapshotFile | null;
+declare function hasDrift(drift: Drift): boolean;
+/** Total drifted files — the number shown to humans. */
+declare function driftCount(drift: Drift): number;
+/**
+ * Compare the working tree to the snapshot. Returns null when no snapshot
+ * exists (nothing was ever built on this machine — auto-refresh stays off
+ * rather than guessing the build scope). Stat-only except for files whose
+ * stat moved; touch-only moves are absorbed back into the snapshot.
+ */
+declare function probeFreshness(root: string): ProbeResult | null;
+
+/**
+ * Auto-refresh: bring the code map back in sync with the working tree when the
+ * freshness probe says it drifted. The rebuild is the ordinary incremental
+ * `buildGraph` (warm parse cache → only changed files re-parse), replaying the
+ * scope recorded at the last explicit build, guarded by a cross-process lock
+ * so a serving MCP process and a foreground command never write at once.
+ *
+ * Two properties keep this safe to run implicitly:
+ * - **No git churn**: if the rebuilt corpusHash equals the snapshot's (e.g. a
+ *   drift that reverted itself), `graph.json` is left untouched — the artifact
+ *   stays byte-identical.
+ * - **No surprise artifacts**: `GRAPH_REPORT.md`/`graph.html` are rewritten
+ *   only if they already exist; a refresh never adds files a user's explicit
+ *   build chose not to produce.
+ */
+interface RefreshOptions {
+    /** Force single-threaded parsing (tests / constrained hosts). */
+    inline?: boolean;
+    /** Worker count for the parse pool. */
+    jobs?: number;
+}
+type RefreshOutcome = 
+/** Map already matches the working tree. */
+{
+    status: 'fresh';
+}
+/** No freshness snapshot — no build ever ran here, so scope is unknown. */
+ | {
+    status: 'no-snapshot';
+}
+/** Another vg process is rebuilding right now; its write will land shortly. */
+ | {
+    status: 'locked';
+}
+/** Rebuilt. `wrote` is false when the corpus turned out unchanged. */
+ | {
+    status: 'refreshed';
+    drift: Drift;
+    ms: number;
+    reparsed: number;
+    totalFiles: number;
+    wrote: boolean;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Probe, and rebuild incrementally if the tree drifted from the map.
+ * Silent (no output) — callers own the messaging for their surface.
+ */
+declare function refreshIfStale(root: string, opts?: RefreshOptions): Promise<RefreshOutcome>;
+
+/**
+ * Test-awareness (VG-ENGINE-TEARDOWN §3.6) — the wedge Graphify has no answer to.
+ *
+ * Deterministic, two signals:
+ *  1. **Static linkage** — calls from a test file into product code become `test`
+ *     edges (test file → covered node), so we can answer "which tests exercise
+ *     this" from structure alone, no runner needed.
+ *  2. **Coverage** (coverage.ts) — runtime-grounded line coverage applied as
+ *     `coverage` on nodes (stronger than static linkage when present).
+ *
+ * A node's `tested` flag is true when it has any incoming test/coverage signal;
+ * false for analyzable code with none; null for non-analyzable kinds.
+ */
+declare function isTestFile(rel: string): boolean;
+interface TestAwarenessResult {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    testFiles: string[];
+    testEdgeCount: number;
+}
+/**
+ * Apply static test linkage. Adds `test` edges from each test file node to the
+ * product-code nodes its functions call, and sets `tested` on analyzable nodes.
+ */
+declare function applyStaticTestLinkage(nodes: GraphNode[], edges: GraphEdge[]): TestAwarenessResult;
+
+/**
+ * Answering the wedge questions: "which tests cover X" (`vg tests`) and "which
+ * tests must I run if I change X" (`vg impact --tests`). Deterministic, from the
+ * `test` edges + coverage produced at build time.
+ */
+interface CoveringTest {
+    file: string;
+    basis: 'call' | 'coverage';
+    confidence: number;
+}
+declare function coveringTests(graph: VgGraph, node: GraphNode, index?: GraphIndex): CoveringTest[];
+interface TestImpact {
+    affectedTestFiles: string[];
+    untestedAffected: {
+        id: string;
+        name: string;
+        file: string;
+    }[];
+}
+/** The test files that exercise any node in the impact set of `rootId`. */
+declare function testsToRun(graph: VgGraph, rootId: string, depth?: number): TestImpact;
+interface Runner {
+    name: string;
+    command: (testFiles: string[]) => string;
+}
+declare function detectRunner(root: string, lang?: string): Runner;
+
+/**
+ * Coverage ingestion (VG-ENGINE-TEARDOWN §3.6) — runtime-grounded test linkage.
+ * Parses LCOV (`coverage/lcov.info`) and Istanbul (`coverage-final.json`) into a
+ * per-file line→hits map, then sets each node's `coverage` (fraction of its span
+ * that ran) and `tested` flag. Stronger than static linkage where present.
+ */
+type LineHits = Map<number, number>;
+type CoverageMap = Map<string, LineHits>;
+/** Find and parse coverage reports under root. Returns null if none found. */
+declare function loadCoverage(root: string, explicit?: string[]): CoverageMap | null;
+/** Apply coverage to nodes: set `coverage` fraction over the node's span + `tested`. */
+declare function applyCoverage(nodes: GraphNode[], coverage: CoverageMap): GraphNode[];
+
+/**
+ * The open facts subset (VG-PACKAGE-AND-SCHEMA §5) — reimplemented fresh in the
+ * open engine: deterministic, no runtime, no corpus, no LLM, no hidden pipeline.
+ * Three commodity fact kinds, each epistemic-typed so it never claims more than
+ * the open layer can prove:
+ *
+ *  - **contract** — from a public signature/type        (declared → Observed)
+ *  - **invariant** — from a static assert/guard          (static → Derived)
+ *  - **characterization** — from existing test linkage   (static → Observed)
+ *
+ * Emitted with `--deep`.
+ */
+declare function buildFacts(parses: FileParse[], nodes: GraphNode[], edges: GraphEdge[]): Fact[];
+
+/**
+ * The free knowledge pack shipped in the open CLI (VG-PACKAGE-AND-SCHEMA §6):
+ * our own paraphrased guidance + openly-licensed standards (OWASP Top 10 2021,
+ * CWE). Never verbatim proprietary text; every entry cites a public source.
+ * Matching is deterministic (imports / called APIs / identifier keywords).
+ */
+interface MatchRule {
+    imports?: string[];
+    calls?: string[];
+    keywords?: string[];
+}
+interface PackEntry {
+    id: string;
+    topic: string;
+    summary: string;
+    citation: {
+        title: string;
+        url: string;
+    };
+    kind: GroundingKind;
+    rationale: 'recommended' | 'conjectured';
+    match: MatchRule;
+}
+interface KnowledgePack {
+    id: string;
+    version: string;
+    license: string;
+    entries: PackEntry[];
+}
+declare const FREE_PACK: KnowledgePack;
+
+/**
+ * Grounding (VG-PACKAGE-AND-SCHEMA §6) — match nodes to knowledge-pack entries by
+ * deterministic signals (file imports, called APIs, identifier keywords) and
+ * attach cited framing edges. Closed-world tools can't follow without building a
+ * corpus. Deterministic-first; the free pack ships in the open CLI.
+ */
+declare function groundGraph(nodes: GraphNode[], edges: GraphEdge[], parses: FileParse[], packs?: KnowledgePack[]): GroundingEdge[];
+
+/**
+ * Dependency currency (VG-LOCAL-MODELS §9 / VG-DEVELOPMENT-PLAN Phase 2.4).
+ *
+ * Default path is **offline and deterministic**: inventory dependencies from
+ * manifests and resolve installed versions from node_modules. Currency against
+ * "latest/EOL/CVE" needs data, so it is strictly **opt-in** (`--online`, which
+ * queries the public npm registry) — the offline core never touches the network.
+ * Full DriftScore/CVE/EOL governance is the Vibgrate platform (the funnel).
+ */
+/** Supported dependency ecosystems (manifest + lockfile). Extend this list to widen coverage. */
+declare const ECOSYSTEMS: readonly ["npm", "pypi", "go", "rust", "ruby", "php", "dotnet", "swift", "dart", "java"];
+type Ecosystem = (typeof ECOSYSTEMS)[number];
+interface DepRecord {
+    name: string;
+    ecosystem: Ecosystem;
+    declared: string;
+    installed?: string;
+    latest?: string;
+    drift?: 'major' | 'minor' | 'patch' | 'current' | 'unknown';
+}
+interface DriftInventory {
+    records: DepRecord[];
+    counts: {
+        total: number;
+    } & Record<Ecosystem, number>;
+}
+declare function inventory(root: string): DriftInventory;
+/** Opt-in online enrichment: query npm for `latest` and classify drift. */
+declare function enrichOnline(records: DepRecord[], fetchImpl?: typeof fetch): Promise<void>;
+
+/**
+ * Local-model discovery (VG-LOCAL-MODELS §9.2) — be a no-key *consumer* of the
+ * developer's local model fleet. Fully offline and deterministic: inspect the
+ * on-disk layouts of Ollama / LM Studio / llama.cpp, never the network. No
+ * runtime is built or launched.
+ */
+interface LocalModel {
+    runtime: 'ollama' | 'lm-studio' | 'gguf';
+    name: string;
+    path: string;
+}
+declare function discoverModels(home?: string): LocalModel[];
+
+interface SavingEntry {
+    ts: number;
+    tool: string;
+    vgTokens: number;
+    baselineTokens: number;
+}
+/** Whether a savings ledger exists for this repo (i.e. `vg serve --savings` has recorded). */
+declare function savingsRecorded(root: string): boolean;
+declare function recordSaving(root: string, entry: Omit<SavingEntry, 'ts'>, now: number): void;
+interface SavingsReport {
+    enabled: boolean;
+    days: number;
+    queries: number;
+    vgTokens: number;
+    baselineTokens: number;
+    ratio: number;
+    estCostVg: number;
+    estCostBaseline: number;
+    saved: number;
+    rateLabel: string;
+}
+declare function readSavings(root: string, days: number, now: number, ratePerM?: number): SavingsReport;
+
+/**
+ * `vg lib` — a deterministic, on-disk library-currency catalog: version-correct
+ * usage docs for the **exact version in your lockfile**, drift-annotated, from
+ * on-disk sources (no key).
+ *
+ * The catalog (`vibgrate.lib.json`) is small and committable; doc bodies live in
+ * `.vibgrate/lib/<id>.md` so the team shares them on pull. Ingestion is
+ * deterministic from local sources; URL/llms.txt ingestion is opt-in network.
+ */
+declare const LIB_SCHEMA: "vg-lib/1.0";
+interface LibSource {
+    type: 'local' | 'llms.txt' | 'website' | 'openapi' | 'git';
+    location: string;
+}
+interface LibEntry {
+    id: string;
+    name: string;
+    version: string;
+    source: LibSource;
+    docFile: string;
+    docHash: string;
+    bytes: number;
+}
+interface LibCatalog {
+    schemaVersion: typeof LIB_SCHEMA;
+    libraries: Record<string, LibEntry>;
+}
+declare function libId(name: string): string;
+declare function loadCatalog(root: string): LibCatalog;
+declare function saveCatalog(root: string, catalog: LibCatalog): void;
+/** Resolve a fuzzy name to a catalog entry (exact id, name, or substring). */
+declare function resolveLib(catalog: LibCatalog, name: string): LibEntry | undefined;
+interface DriftNote {
+    cataloged: string;
+    installed?: string;
+    drift: 'current' | 'behind' | 'ahead' | 'unknown';
+}
+declare function driftFor(root: string, entry: LibEntry): DriftNote;
+interface AddOptions {
+    root: string;
+    name?: string;
+    version?: string;
+    /** Allow network for URL/llms.txt sources. */
+    allowNetwork?: boolean;
+    fetchImpl?: typeof globalThis.fetch;
+}
+/** Ingest docs for a library from a local path, a git repo, or (opt-in) a URL. */
+declare function addLibrary(source: string, opts: AddOptions): Promise<LibEntry>;
+declare function readDoc(root: string, entry: LibEntry): string;
+
+interface ServeLaunch {
+    command: string;
+    args: string[];
+    /** Human-readable explanation when the launch is not the plain `vg serve`. */
+    note?: string;
+}
+
+/**
+ * Per-assistant install registry (a focused subset of VG-ASSISTANT-INSTALL §2;
+ * the remaining 20+ assistants are added in Phase 3). All paths are repo-local
+ * (the team-shareable, safe default); writes are idempotent.
+ */
+interface McpTarget {
+    file: string;
+    key: 'mcpServers' | 'servers';
+    vscode?: boolean;
+}
+interface NudgeTarget {
+    file: string;
+    kind: 'block' | 'file';
+}
+interface Assistant {
+    id: string;
+    label: string;
+    skill?: string;
+    mcp?: McpTarget;
+    nudge?: NudgeTarget;
+}
+declare const ASSISTANTS: Assistant[];
+declare function assistantById(id: string): Assistant | undefined;
+interface InstallOptions {
+    root: string;
+    hook?: boolean;
+    smallRepo: boolean;
+    /** Resolved MCP launch command; defaults to detectServeLaunch(). */
+    launch?: ServeLaunch;
+}
+interface InstallAction {
+    wrote: string[];
+    skipped: string[];
+    /** Explanation when the MCP entry is not the plain `vg serve` (e.g. PATH fallback). */
+    note?: string;
+}
+declare function installAssistant(a: Assistant, opts: InstallOptions): InstallAction;
+declare function uninstallAssistant(a: Assistant, root: string, purge: boolean): string[];
+
+/**
+ * Deterministic exporters (VG-CLI-SPEC §4.2). One `vg export <file>` verb, format
+ * inferred from the extension. Live graph-DB push is deliberately out (a file
+ * import covers the same need offline). CycloneDX/SPDX power the SBOM/AI-BOM seam
+ * (VG-LOCAL-MODELS §9.4).
+ */
+type ExportFormat = 'json' | 'ndjson' | 'graphml' | 'dot' | 'cypher' | 'md' | 'html' | 'cyclonedx' | 'spdx';
+declare function formatForExt(ext: string): ExportFormat | null;
+interface ExportContext {
+    graph: VgGraph;
+    deps?: DepRecord[];
+    models?: LocalModel[];
+    generatedAt: string;
+}
+declare function exportGraph(format: ExportFormat, ctx: ExportContext): string;
+
+/**
+ * The deferred, decoupled push envelope (VG-PACKAGE-AND-SCHEMA §7). In the open
+ * CLI `vg push` is **specified but not built**: it assembles and redacts the
+ * envelope and prints a notice, but performs **no network upload**. Nothing in
+ * the free path depends on it. Drift-over-time/governance is the separate
+ * commercial product.
+ */
+interface GraphUploadEnvelope {
+    schemaVersion: 'vg-graph/1.0';
+    artifactType: 'graph';
+    scanIngestId?: string;
+    vcs: {
+        sha: string;
+        shortSha: string;
+        branch: string;
+    };
+    repository?: {
+        name?: string;
+        remoteUrl?: string;
+    };
+    generatedAt: string;
+    graph: VgGraph;
+}
+declare function buildEnvelope(root: string, graph: VgGraph, scanIngestId?: string): GraphUploadEnvelope;
+/**
+ * Redaction pass (GUARDRAILS §1: redact before storage). The graph is structure,
+ * not content, but we defensively scrub any signature/name that matches a
+ * credential-shaped pattern, and strip credentials from the remote URL.
+ */
+declare function redactGraph(graph: VgGraph): VgGraph;
+
+/**
+ * The first existing directory that holds a grammar .wasm set. Skips the
+ * vendor overlays — they hold single replacement files, never a full set.
+ * For a complete per-language resolution use resolvedGrammarFiles().
+ */
+declare function grammarsSourceDir(): string | null;
+
+export { ASSISTANTS, type AnalyzeOptions, type AnalyzeResult, Area, type Assistant, type BuildOptions, type BuildResult, type BuildScope, type ClusterMode, type DepRecord, type DiscoverOptions, type DiscoveredFile, type Drift, type DriftInventory, type DriftNote, EdgeKind, type Embedder, type ExportContext, type ExportFormat, FREE_PACK, Fact, FileParse, GraphEdge, GraphIndex, GraphNode, GraphSource, type GraphUploadEnvelope, GroundingEdge, GroundingKind, type ImpactItem, type ImpactResult, type KnowledgePack, LANGUAGES, type LanguageDef, type LibCatalog, type LibEntry, type LibSource, type LoadEmbedderOptions, type LocalModel, type ModuleResolver, type PackEntry, type PathResult, type ProbeResult, type QueryMatch, type QueryOptions, type QueryResult, type RefreshOptions, type RefreshOutcome, ResolverKind, SKIP_DIRS, type SavingsReport, type ScipDocument, type ScipIndex, type ScipOccurrence, type SemanticQueryOptions, type ServeOptions, TOOLS, UsageError, VERSION, type VerifyResult, VgGraph, type VgTool, type WriteOptions, type WrittenArtifacts, addLibrary, allLanguageIds, analyze, applyCoverage, applyStaticTestLinkage, assistantById, buildEnvelope, buildFacts, buildGraph, buildModuleResolver, cosine, coveringTests, createServer, decodeScipIndex, defaultGraphPath, inventory as dependencyInventory, detectRunner, discover, discoverModels, driftCount, driftFor, enrichOnline, exportGraph, findNodes, formatForExt, getNodeEmbeddings, grammarsSourceDir, groundGraph, hasDrift, identifierParts, impactOf, installAssistant, isTestFile, langById, langForExtension, libId, loadCatalog, loadCoverage, loadEmbedder, loadGraph, loadSnapshot, nodeById, nodeEmbedText, parseGraph, parseJsonc, parseSource, probeFreshness, queryGraph, queryGraphSemantic, readDoc, readSavings, recordSaving, redactGraph, refreshIfStale, relativeResolver, renderHtml, renderReport, resolveLib, resolveOne, saveCatalog, savingsRecorded, scipEdges, serializeGraph, serveStdio, shortestPath, stableStringify, testsToRun, uninstallAssistant, verifyDeterminism, vibgrateDir, writeArtifacts, writeSnapshot };