@omfalos/mokosh 0.4.4 → 0.5.1

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-BtSqoqbZ.mjs';
-export { E as ExportedSymbol } from './types-BtSqoqbZ.mjs';
-import { N as NormalizedToken } from './tokenizer-BaF1eUBQ.mjs';
-import { F as FileType, N as NodeCategory } from './parse-CAKctgb6.mjs';
-export { I as ImportType, T as TagKind } from './parse-CAKctgb6.mjs';
+import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-Ba-BjVQG.mjs';
+export { E as ExportedSymbol } from './types-Ba-BjVQG.mjs';
+import { N as NormalizedToken } from './tokenizer-D9P-y7lH.mjs';
+import { F as FileType, N as NodeCategory } from './parse-yamNoaoL.mjs';
+export { I as ImportType, T as TagKind } from './parse-yamNoaoL.mjs';
 
 interface SerializedGraph {
     nodes: FileNode[];
@@ -17,6 +17,61 @@ interface TraversalOptions {
     direction?: "outgoing" | "incoming";
 }
 
+/** Analyzes a dependency graph node map for unused files, export-usage hotspots, and circular import chains. */
+
+/**
+ * Edge kinds that {@link GraphAnalyzer.findCycles} treats as *not* real import cycles and skips
+ * by default: `"samePackage"` for the synthetic JVM same-package sibling clique, `"docReference"`
+ * for Markdown link / code-span file references (ADR-009). Pass one via `includeKinds` to walk it
+ * anyway (e.g. a caller that genuinely wants to see doc cross-link loops).
+ */
+type CycleEdgeKind = "docReference" | "samePackage";
+/** Options for {@link GraphAnalyzer.findCycles}. */
+interface FindCyclesOptions {
+    /** Edge kinds to include in the walk that are otherwise skipped (see {@link CycleEdgeKind}). */
+    includeKinds?: CycleEdgeKind[] | undefined;
+}
+/**
+ * @description Utility for analyzing the dependency graph for cycles and unused files.
+ *   Operates on the raw node map rather than a `Graph` instance so it can be used
+ *   without the full traversal infrastructure.
+ */
+declare class GraphAnalyzer {
+    private nodes;
+    /**
+     * @param {Map<string, FileNode>} nodes - The full node map of the graph to analyze, keyed by project-relative file path.
+     */
+    constructor(nodes: Map<string, FileNode>);
+    /**
+     * @description Returns files from `allFiles` that are absent from the graph — meaning nothing
+     *   imports them directly or transitively from any entry point, making them deletion candidates.
+     * @param {string[]} allFiles - Complete list of project-relative file paths to test against the graph.
+     * @returns {string[]} Subset of `allFiles` whose paths do not appear as graph nodes.
+     */
+    findUnusedFiles(allFiles: string[]): string[];
+    /**
+     * @description Returns files whose highest single-edge export usage ratio meets or exceeds
+     *   `threshold`, sorted descending by `maxExportUsage`. Useful for identifying files
+     *   that consume a large fraction of one dependency's API surface.
+     * @param {number} threshold - Minimum `maxExportUsage` value (0–1) for a file to be included.
+     * @returns {Array<{ path: string; maxExportUsage: number; tightestDep: string }>} Entries sorted descending by `maxExportUsage`.
+     */
+    findHighExportUsage(threshold: number): Array<{
+        path: string;
+        maxExportUsage: number;
+        tightestDep: string;
+    }>;
+    /**
+     * @description Detects all circular import chains using DFS with a recursion-stack back-edge check.
+     *   Each returned array is one cycle as an ordered list of file paths ending at the entry that closes the loop.
+     *   Non-import edge kinds — the synthetic JVM same-package clique and Markdown doc references
+     *   (ADR-009) — are skipped by default; pass `includeKinds` to walk them anyway.
+     * @param {FindCyclesOptions} [opts] - `includeKinds` opts specific edge kinds back into the walk.
+     * @returns {string[][]} Array of cycles; each cycle is an ordered list of file paths forming a loop.
+     */
+    findCycles(opts?: FindCyclesOptions): string[][];
+}
+
 /** Graph class wrapping the raw node map with DFS traversal, cycle detection, serialization, and reverse-edge helpers. */
 
 /**
@@ -112,9 +167,12 @@ declare class Graph {
     /**
      * @description Detects all circular import chains in the graph using DFS
      *   with a back-edge check. Each returned array is one cycle as an ordered path.
+     *   Synthetic JVM same-package edges and Markdown doc references are skipped by default —
+     *   pass `opts.includeKinds` to walk them.
+     * @param {FindCyclesOptions} [opts] - Forwarded to {@link GraphAnalyzer.findCycles}.
      * @returns Array of cycles; each cycle is a list of file paths forming a loop.
      */
-    findCycles(): string[][];
+    findCycles(opts?: FindCyclesOptions): string[][];
 }
 
 /** Configures whether/how `parseFile` calls are offloaded to a `piscina` worker pool. `false` always parses in-process. */
@@ -197,6 +255,19 @@ interface MokoshConfig {
      * in-process, or pass `{ minFiles, maxThreads }` to raise the threshold instead.
      */
     parallelParsing?: ParallelParsingOption;
+    /** Duplicate-detection (`find_duplicates` / `--find-duplicates`) tuning. */
+    duplication?: {
+        /**
+         * Extra generated / vendored file patterns to exclude from duplicate scanning, merged with
+         * the built-in list (protobuf output, `*.generated.*`, `generated/` dirs, `@generated`
+         * markers). Two shapes only — `** /name/**` (any path segment equals `name`) and `*.suffix`
+         * (basename ends with `.suffix`) — not full glob syntax.
+         */
+        ignoreGlobs?: string[];
+        /** When true, scan generated / vendored files too (default false). Matches involving one are
+         *  tagged `signals: ["generated"]`. */
+        includeGenerated?: boolean;
+    };
 }
 /**
  * @description Loads a mokosh config file, probing standard filenames in `rootDirOrPath` or reading an explicit path when `isExplicitPath` is true.
@@ -222,8 +293,8 @@ declare function loadMokoshConfig(rootDirOrPath: string, { allowJs, isExplicitPa
 declare function applyConfig(config: MokoshConfig): void;
 /**
  * @description Extracts the subset of `MokoshConfig` fields that affect graph
- *   construction (`gitStats`, `parallelParsing`, `pathAliases`) into a plain options
- *   object, ready to spread into `createImportMap`/`createWorkspaceGraph` calls. Single
+ *   construction (`gitStats`, `parallelParsing`, `pathAliases`, `ignoreDirs`) into a plain
+ *   options object, ready to spread into `createImportMap`/`createWorkspaceGraph` calls. Single
  *   source of truth for this mapping so every graph-building call site — CLI, MCP,
  *   and secondary command-level rebuilds — stays in sync as new config fields are added.
  * @param config - The loaded config, or `undefined` when none has been loaded yet.
@@ -233,6 +304,7 @@ declare function configToGraphOptions(config: MokoshConfig | undefined): {
     gitStats: boolean;
     parallelParsing: ParallelParsingOption | undefined;
     pathAliases: Record<string, string[]> | undefined;
+    additionalIgnoreDirs: string[] | undefined;
 };
 
 /** Shared by the CLI's disk graph cache (`src/cli/graph-loader.ts`) and the MCP server's
@@ -246,6 +318,15 @@ declare const DEFAULT_DUPLICATION_TOKEN_CACHE_FILE = "duplication-tokens.json";
  *  (`src/cli/graph-loader.ts`) after every build; read by the MCP server (`src/mcp/cache.ts`) to
  *  seed a session's first `analyze` call so it reuses unchanged nodes instead of parsing cold. */
 declare const DEFAULT_GRAPH_CACHE_FILE = "graph.json";
+/** Filename for the disk-persisted *workspace* (monorepo) graph cache within `DEFAULT_CACHE_DIR`.
+ *  Written by the MCP server (`src/mcp/cache.ts`) after a `createWorkspaceGraph` build and hydrated
+ *  on the next session's first workspace query when the source-file digest still matches — so
+ *  repeat sessions against an unchanged monorepo skip the full per-package rebuild. */
+declare const DEFAULT_WORKSPACE_GRAPH_CACHE_FILE = "workspace-graph.json";
+/** Subdirectory of `DEFAULT_CACHE_DIR` holding one JSON file per commit sha — graphs built for
+ *  the "other" ref in a `compareBranches` call (`src/graph/branch-graph-cache.ts`). Keyed by sha
+ *  rather than branch name so entries are immutable and never need invalidation. */
+declare const DEFAULT_BRANCH_GRAPH_CACHE_DIR = "branch-graphs";
 declare const DEFAULT_IGNORE_DIRS: readonly string[];
 declare const DEFAULT_EXTENSIONS: readonly string[];
 interface ScanOptions {
@@ -492,6 +573,13 @@ interface DuplicateOccurrence {
     startLine: number;
     endLine: number;
 }
+/**
+ * Advisory tags on a {@link DuplicateGroup} that help a caller (and issue 6's query layer) judge
+ * whether a match is worth acting on: `"same-file"` — every occurrence is in one file (an
+ * internally repeated block); `"generated"` — at least one occurrence is in a file only scanned
+ * because `includeGenerated: true` was passed. Designed to grow (issue 7 adds more).
+ */
+type DuplicateSignal = "same-file" | "generated";
 interface DuplicateGroup {
     /** Every location sharing this duplicated block (two or more) — locations that pairwise
      *  chain-match are clustered into one group instead of being reported once per pair, so a
@@ -507,6 +595,9 @@ interface DuplicateGroup {
      *  matches across families — see docs/adr-013-duplicate-detection-noise-reduction.md).
      *  Absent when called directly with a token stream that isn't family-scoped, e.g. in tests. */
     family?: DuplicateFamily | undefined;
+    /** Advisory tags for filtering — see {@link DuplicateSignal}. Absent (not `[]`) when no
+     *  signal applies. */
+    signals?: DuplicateSignal[] | undefined;
 }
 
 /** One file's cached tokenize result, fingerprinted by `mtime`/`size`/`ignoreLiterals` — any
@@ -517,6 +608,10 @@ interface CachedFileTokens {
     mtime: number;
     size: number;
     ignoreLiterals: boolean;
+    /** Whether this file is generated / vendored (path heuristic or first-bytes marker) — cached
+     *  so a `includeGenerated: false` scan that gets a cache hit can still exclude it, and a
+     *  `includeGenerated: true` scan can still tag matches, without re-reading the file. */
+    generated: boolean;
     tokens: NormalizedToken[];
 }
 /** Caller-owned cache, keyed by project-relative path, reused across repeated `findDuplicates`
@@ -545,6 +640,24 @@ declare function loadTokenCacheFromDisk(cachePath: string): DuplicationTokenCach
  */
 declare function saveTokenCacheToDisk(cache: DuplicationTokenCache, cachePath: string): void;
 
+/**
+ * @description Whether a file's path alone marks it as generated — a known codegen basename
+ *   suffix, a generated-output directory segment, or a caller-supplied `ignoreGlobs` match.
+ *   Cheap and synchronous, so it runs before the file is read.
+ * @param relPath - Project-relative file path.
+ * @param ignoreGlobs - Extra patterns from `MokoshConfig.duplication.ignoreGlobs`.
+ * @returns Whether `relPath` should be treated as generated.
+ */
+declare function isGeneratedPath(relPath: string, ignoreGlobs?: readonly string[]): boolean;
+/**
+ * @description Whether the start of a file's source carries a generated-by marker
+ *   (`@generated`, `DO NOT EDIT`, `Code generated by …`, etc.). Only the first
+ *   {@link MARKER_SCAN_BYTES} characters are checked — codegen tools put the banner at the top.
+ * @param source - Full file source.
+ * @returns Whether a generated marker is present near the top of `source`.
+ */
+declare function hasGeneratedMarker(source: string): boolean;
+
 /** Configures whether/how tokenizing is offloaded to a `piscina` worker pool. `false` always
  *  tokenizes in-process. */
 type ParallelTokenizingOption = boolean | {
@@ -572,6 +685,16 @@ interface FindDuplicatesOptions {
     /** Directory names to exclude, matched against any path segment (default `DEFAULT_IGNORE_DIRS`
      *  — `node_modules`, `dist`, `.git`, `mokosh-cache`, `coverage`, etc.). Pass `[]` to disable. */
     ignoreDirs?: readonly string[] | undefined;
+    /** When false (default), skip generated / vendored files — protobuf output, `*.generated.*`,
+     *  codegen basenames, files under a `generated/` segment, and files whose first ~500 bytes
+     *  carry a `@generated` / `DO NOT EDIT` / `Code generated by` marker. Their repetition is not
+     *  actionable copy-paste. Set true to scan them anyway; matches involving one are tagged
+     *  `signals: ["generated"]`. See docs/adr-013-duplicate-detection-noise-reduction.md. */
+    includeGenerated?: boolean | undefined;
+    /** Extra generated-file patterns merged with the built-in list (from
+     *  `MokoshConfig.duplication.ignoreGlobs`). Two shapes only — `**​/name/**` (path segment) and
+     *  `*.suffix` (basename) — not full glob syntax. */
+    ignoreGlobs?: readonly string[] | undefined;
     /** Controls worker-pool offloading of per-file tokenizing (default `true`): offloads once the
      *  candidate file count reaches `minFiles` (default 20, matching `GraphBuilder`'s parse pool);
      *  `false` always tokenizes in-process; an object overrides `minFiles`/`maxThreads`. See
@@ -915,17 +1038,6 @@ interface MonorepoDetector {
  */
 declare function registerMonorepoDetector(detector: MonorepoDetector): void;
 
-/**
- * @description Runs all registered monorepo detectors against `rootDir` and merges
- *   their results into a single `MonorepoLayout`. All matching detectors contribute
- *   their `type` string and packages — so a Turborepo + pnpm repo will have
- *   `types: ["turborepo", "pnpm"]` and packages from the pnpm detector.
- *
- *   Packages are deduplicated by name: the first detector to emit a package name wins.
- *   Returns `type: "none"` when no detector fires.
- */
-declare function detectMonorepo(rootDir: string, detectors?: readonly MonorepoDetector[]): MonorepoLayout;
-
 /** WorkspaceGraph holds one per-package Graph for a monorepo and exposes cross-package blast-radius queries. */
 
 /** @description JSON-safe snapshot of a `WorkspaceGraph`, suitable for writing to disk and restoring via `WorkspaceGraph.deserialize`. */
@@ -961,6 +1073,17 @@ declare class WorkspaceGraph {
      * @param {Graph} graph - The fully-built dependency graph for this package.
      */
     addPackage(pkg: WorkspacePackage, graph: Graph): void;
+    /**
+     * @description Marks every local import edge that crosses a package boundary as a workspace
+     *   edge (`isWorkspace: true`, `workspacePackage` set to the target package name). JS
+     *   resolvers tag these at resolution time from the `workspaceMap`, but JVM (and any other
+     *   `LangResolver` that resolves cross-module by a project-wide index) returns concrete file
+     *   paths with no package awareness — so cross-module Gradle/sbt edges would otherwise be
+     *   invisible to `getPackageDependencies` and the cross-package step of
+     *   `getAffectedAcrossPackages`. Idempotent: edges already tagged are left untouched.
+     *   Call once after all packages are registered.
+     */
+    annotateCrossPackageEdges(): void;
     /**
      * @description Returns the workspace package whose `relativeRoot` is a path prefix of `relPath`.
      * @param {string} relPath - A monorepo-root-relative file path to look up.
@@ -1000,6 +1123,47 @@ declare class WorkspaceGraph {
     static deserialize(data: SerializedWorkspaceGraph): WorkspaceGraph;
 }
 
+interface WorkspaceLayoutPackageSummary {
+    name: string;
+    relativeRoot: string;
+    /** Sibling workspace packages this one depends on. Exact when `dependsOnResolved`, best-effort otherwise. */
+    dependsOn: string[];
+    /** Present only when a built workspace graph was available. */
+    nodeCount?: number;
+}
+interface WorkspaceLayoutSummary {
+    monorepoType: string;
+    monorepoTypes: string[];
+    packageCount: number;
+    packages: WorkspaceLayoutPackageSummary[];
+    /** `true` when `dependsOn` came from a built graph or every package exposed a manifest. */
+    dependsOnResolved: boolean;
+    /** `true` when per-package `nodeCount` is populated (a built graph was available). */
+    nodeCountsResolved: boolean;
+    note?: string;
+}
+/**
+ * @description Summarizes a monorepo from its detected layout alone — package names, relative
+ *   roots, and best-effort `dependsOn` from `package.json` manifests — without building any
+ *   dependency graph. When a built `WorkspaceGraph` is supplied, its exact per-package node
+ *   counts and cross-package edges are used instead.
+ * @param layout - The result of `detectMonorepo`. Must not be `type: "none"`.
+ * @param builtGraph - An already-built workspace graph for `layout.root`, if one is cached.
+ * @returns A layout summary suitable for the `get_workspace_packages` response.
+ */
+declare function summarizeWorkspaceLayout(layout: MonorepoLayout, builtGraph?: WorkspaceGraph): WorkspaceLayoutSummary;
+
+/**
+ * @description Runs all registered monorepo detectors against `rootDir` and merges
+ *   their results into a single `MonorepoLayout`. All matching detectors contribute
+ *   their `type` string and packages — so a Turborepo + pnpm repo will have
+ *   `types: ["turborepo", "pnpm"]` and packages from the pnpm detector.
+ *
+ *   Packages are deduplicated by name: the first detector to emit a package name wins.
+ *   Returns `type: "none"` when no detector fires.
+ */
+declare function detectMonorepo(rootDir: string, detectors?: readonly MonorepoDetector[]): MonorepoLayout;
+
 /**
  * @description Contract for graph serializers. Implement this to add a new export format
  *   (e.g. Graphviz DOT, JSON, SVG) without touching the core graph model.
@@ -1027,32 +1191,6 @@ declare const MermaidExporter: GraphExporter;
  */
 declare function toMermaid(graph: Graph): string;
 
-/** Single source of truth for which languages' parsers track which precision-relevant data. */
-
-/** File types whose parser ever populates `FileNode.exports`. */
-declare const EXPORT_TRACKING_TYPES: ReadonlySet<FileType>;
-/** File types whose parser records which named symbols each import edge pulls in (`ImportEdge.symbols`). */
-declare const IMPORT_SYMBOL_TYPES: ReadonlySet<FileType>;
-/** File types whose parser records function-level call edges (`FileNode.callEdges`). */
-declare const CALL_EDGE_TYPES: ReadonlySet<FileType>;
-interface LanguageCoverage {
-    type: FileType;
-    fileCount: number;
-    exportsTracked: boolean;
-    importSymbolsTracked: boolean;
-    callEdgesTracked: boolean;
-}
-/**
- * @description Reports which precision-relevant data mokosh actually tracks for each language
- *   present in `graph` — so a caller can tell upfront whether tools like `find_symbol` or
- *   `get_call_graph` will give call-level precision, degrade to import-level, or find nothing
- *   at all for a given file, before running a query and being surprised by the result.
- * @param graph - The graph to summarize.
- * @returns One entry per `FileType` actually present in `graph`, sorted by file count
- *   descending. Languages with zero files in this graph are omitted.
- */
-declare function getLanguageCoverage(graph: Graph): LanguageCoverage[];
-
 /** Pure graph query/shaping functions shared by the MCP handlers and the CLI, so both surfaces return identical JSON shapes. */
 
 interface PathWithSymbols {
@@ -1231,6 +1369,215 @@ interface RiskHotspotsResult {
  */
 declare function findRiskHotspots(graph: Graph, options?: FindRiskHotspotsOptions): RiskHotspotsResult;
 
+interface BuildGraphAtRefOptions {
+    silent?: boolean | undefined;
+    gitStats?: boolean | undefined;
+    parallelParsing?: ParallelParsingOption | undefined;
+    pathAliases?: Record<string, string[]> | undefined;
+    /** Extra directory names to skip during test/doc discovery, on top of the built-in list. Sourced from `MokoshConfig.ignoreDirs`. */
+    additionalIgnoreDirs?: string[] | undefined;
+}
+/**
+ * @description Builds the dependency graph as it existed at `ref`, rather than the current
+ *   working tree. Resolves `ref` to a commit sha and checks the sha-keyed disk cache
+ *   (`branch-graph-cache.ts`) before paying for a `git worktree` checkout + full parse — a given
+ *   commit's graph never changes, so the cache never needs invalidation.
+ * @param rootDir - Absolute path to the repository root.
+ * @param ref - Any git ref (branch, tag, sha, `HEAD~1`, …).
+ * @param entryPoints - Entry point files, relative to `rootDir`, to seed the build.
+ * @param options - Graph-build options, forwarded to `GraphBuilder` — same shape as `createImportMap`'s.
+ * @returns The resolved commit sha and the `Graph` built at that commit.
+ */
+declare function buildGraphAtRef(rootDir: string, ref: string, entryPoints: string[], options?: BuildGraphAtRefOptions): Promise<{
+    sha: string;
+    graph: Graph;
+}>;
+interface FileDiff {
+    added: string[];
+    removed: string[];
+    changed: string[];
+}
+interface StaleReference {
+    file: string;
+    symbol: string;
+    stillReferencedBy: string[];
+}
+interface DuplicationDelta {
+    base: {
+        groups: number;
+    };
+    head: {
+        groups: number;
+    };
+    newGroups: DuplicateGroup[];
+    resolvedGroups: DuplicateGroup[];
+}
+interface ComplexityDelta {
+    base: {
+        avgCognitiveComplexity: number;
+    };
+    head: {
+        avgCognitiveComplexity: number;
+    };
+    newHotspots: ComplexFunctionEntry[];
+    resolvedHotspots: ComplexFunctionEntry[];
+}
+interface DocDriftDelta {
+    base: {
+        staleCount: number;
+    };
+    head: {
+        staleCount: number;
+    };
+    newlyStale: string[];
+    resolved: string[];
+}
+interface CoverageDelta {
+    base: {
+        avgCoveragePct: number;
+    };
+    head: {
+        avgCoveragePct: number;
+    };
+    newHotspots: RiskHotspotEntry[];
+    resolvedHotspots: RiskHotspotEntry[];
+}
+interface BranchComparison {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    head: {
+        ref: string;
+        sha: string;
+    };
+    files: FileDiff;
+    staleReferences: StaleReference[];
+    duplication: DuplicationDelta;
+    complexity: ComplexityDelta;
+    docDrift: DocDriftDelta;
+    coverage: CoverageDelta | null;
+}
+/**
+ * @description Token-frugal projection of a {@link BranchComparison} for AI/PR-review consumers.
+ *   Each delta section carries the worst N items as compact `file:line name (score)` strings plus
+ *   a true total count, and "things that got better" collapse to a bare count. Sections with no
+ *   delta are omitted entirely; `staleReferences` (the one likely-a-real-bug signal) is never
+ *   truncated. `headline` + `verdict` are usually all a reviewer needs to read.
+ */
+interface BranchComparisonSummary {
+    /** `"<ref>@<short-sha>"` for the base side. */
+    base: string;
+    /** `"<ref>@<short-sha>"` for the head side. */
+    head: string;
+    verdict: "clean" | "review-worthy" | "attention";
+    headline: string[];
+    files: {
+        added: number;
+        changed: number;
+        removed: number;
+        /** Full path lists — omitted when the diff touches more than `maxPathList` files. */
+        paths?: {
+            added: string[];
+            changed: string[];
+            removed: string[];
+        };
+    };
+    /** Present (and complete) only when at least one stale reference was found. */
+    staleReferences?: StaleReference[];
+    complexity?: {
+        avgDelta: number;
+        /** Worst `maxItems`, `"file:line name (score)"`. */
+        newHotspots: string[];
+        /** True count of new hotspots (may exceed `newHotspots.length`). */
+        newHotspotCount: number;
+        resolvedCount: number;
+    };
+    duplication?: {
+        /** Worst `maxItems`, `"<lines>L x<occurrences>: file:a-b, file:c-d"`. */
+        newGroups: string[];
+        newGroupCount: number;
+        resolvedCount: number;
+        totalGroups: number;
+    };
+    docDrift?: {
+        /** Up to `maxItems`, `"doc → referencedFile"`. */
+        newlyStale: string[];
+        newlyStaleCount: number;
+        resolvedCount: number;
+    };
+    coverage?: {
+        avgDelta: number;
+        /** Worst `maxItems`, `"file:line name (score, cov N%)"`. */
+        newHotspots: string[];
+        newHotspotCount: number;
+        resolvedCount: number;
+    };
+}
+interface SummarizeOptions {
+    /** Which per-function score the complexity/coverage deltas were computed on — picks the number shown per entry. */
+    metric?: "cognitiveComplexity" | "complexity" | undefined;
+    /** Max items kept in each delta list (default 8). */
+    maxItems?: number | undefined;
+    /** Above this many changed+added+removed files, `files.paths` is dropped and only counts remain (default 100). */
+    maxPathList?: number | undefined;
+}
+/**
+ * @description Collapses a full {@link BranchComparison} into a {@link BranchComparisonSummary} —
+ *   see that interface for the shape. Pure function; does no I/O.
+ * @param comparison - The full comparison from {@link compareBranches}.
+ * @param options - `metric` must match the one `compareBranches` used; `maxItems`/`maxPathList` tune truncation.
+ * @returns The compact summary.
+ */
+declare function summarizeBranchComparison(comparison: BranchComparison, options?: SummarizeOptions): BranchComparisonSummary;
+interface CompareBranchesOptions extends BuildGraphAtRefOptions {
+    entryPoints?: string[] | undefined;
+    headRef?: string | undefined;
+    minDuplicateLines?: number | undefined;
+    complexityMetric?: "cognitiveComplexity" | "complexity" | undefined;
+    complexityThreshold?: number | undefined;
+    maxCoveragePct?: number | undefined;
+}
+/**
+ * @description Compares a base ref against an already-built head graph (typically the current
+ *   working tree / HEAD), reporting a file-level diff, likely-missed rename/removal call sites,
+ *   and deltas across every quality tool mokosh already runs on a single graph: duplication
+ *   (`find_duplicates`), complexity (`find_complex_functions`), doc drift (`check_doc_drift`),
+ *   and — when coverage data is loaded on both sides — risk hotspots (`find_risk_hotspots`).
+ * @param rootDir - Absolute path to the repository root.
+ * @param baseRef - The ref to compare against (e.g. `"main"`, `"origin/main"`, a commit sha).
+ * @param headGraph - The already-built graph for the head side of the comparison.
+ * @param options - `headRef` labels the head side in the result (defaults to `"HEAD"`); the rest tune the underlying tool calls and the base-graph build.
+ * @returns The full `BranchComparison`.
+ */
+declare function compareBranches(rootDir: string, baseRef: string, headGraph: Graph, options?: CompareBranchesOptions): Promise<BranchComparison>;
+
+/** Single source of truth for which languages' parsers track which precision-relevant data. */
+
+/** File types whose parser ever populates `FileNode.exports`. */
+declare const EXPORT_TRACKING_TYPES: ReadonlySet<FileType>;
+/** File types whose parser records which named symbols each import edge pulls in (`ImportEdge.symbols`). */
+declare const IMPORT_SYMBOL_TYPES: ReadonlySet<FileType>;
+/** File types whose parser records function-level call edges (`FileNode.callEdges`). */
+declare const CALL_EDGE_TYPES: ReadonlySet<FileType>;
+interface LanguageCoverage {
+    type: FileType;
+    fileCount: number;
+    exportsTracked: boolean;
+    importSymbolsTracked: boolean;
+    callEdgesTracked: boolean;
+}
+/**
+ * @description Reports which precision-relevant data mokosh actually tracks for each language
+ *   present in `graph` — so a caller can tell upfront whether tools like `find_symbol` or
+ *   `get_call_graph` will give call-level precision, degrade to import-level, or find nothing
+ *   at all for a given file, before running a query and being surprised by the result.
+ * @param graph - The graph to summarize.
+ * @returns One entry per `FileType` actually present in `graph`, sorted by file count
+ *   descending. Languages with zero files in this graph are omitted.
+ */
+declare function getLanguageCoverage(graph: Graph): LanguageCoverage[];
+
 /** Symbol-name lookup across the whole graph — generalizes queryCallGraph beyond TS/JS functions. */
 
 type SymbolPrecision = "call" | "file-level";
@@ -1394,15 +1741,6 @@ declare function filterGraph(graph: SerializedGraph, query: NodeQuery): Serializ
 
 /** Parses a key:value query string into a structured NodeQuery for use with filterGraph. */
 
-/**
- * @description Parses a `"key:value,key:value"` query string into a structured `NodeQuery`.
- *   String values support `"!"` prefix for negation. The `tag`/`tags` key may appear multiple
- *   times; values are OR-matched (negated entries act as exclusions). `tag:a+b` maps to `allTags`.
- *   A token of the form `any(key:val|key:val)` is parsed as an OR-group of single-key clauses
- *   and accumulates into `query.any`, ANDed with every other top-level key in the string.
- * @param {string} queryString - Comma-separated `key:value` pairs, e.g. `"category:logic,tag:auth"`.
- * @returns {NodeQuery} The structured query object ready for use with `filterGraph` or `matchNode`.
- */
 declare function parseQuery(queryString: string): NodeQuery;
 
 /**
@@ -1505,7 +1843,7 @@ declare function proposeAffectedTests(graph: Graph, changedFiles: string[], opti
  * @param rootDir - Absolute or relative path to the project root; resolved internally.
  * @param entryPoints - File paths (relative to `rootDir`) that seed the graph walk.
  * @param previousGraph - An earlier graph to diff against for incremental builds; pass `null` for a full build.
- * @param options - `silent` suppresses progress output; `gitStats` attaches git churn data; `coverageMap` maps file paths to line-coverage percentages; `parallelParsing` controls worker-pool offloading of file parsing (see {@link ParallelParsingOption}); `pathAliases` overrides/extends tsconfig path-alias resolution (see `MokoshConfig.pathAliases`).
+ * @param options - `silent` suppresses progress output; `gitStats` attaches git churn data; `coverageMap` maps file paths to line-coverage percentages; `parallelParsing` controls worker-pool offloading of file parsing (see {@link ParallelParsingOption}); `pathAliases` overrides/extends tsconfig path-alias resolution (see `MokoshConfig.pathAliases`); `additionalIgnoreDirs` skips extra directory names during test/doc discovery (see `MokoshConfig.ignoreDirs`).
  * @returns The fully-built Graph with all reachable nodes and import edges populated.
  */
 declare function createImportMap(rootDir: string, entryPoints: string[], previousGraph?: Graph | null, options?: {
@@ -1514,20 +1852,41 @@ declare function createImportMap(rootDir: string, entryPoints: string[], previou
     coverageMap?: Map<string, number>;
     parallelParsing?: ParallelParsingOption | undefined;
     pathAliases?: Record<string, string[]> | undefined;
+    additionalIgnoreDirs?: string[] | undefined;
+    docFiles?: string[] | null | undefined;
 }): Promise<Graph>;
+/**
+ * @description Computes a digest of every source file under `rootDir` (path + mtime + size),
+ *   used to decide whether a disk-persisted workspace graph is still valid. Changing, adding, or
+ *   removing any file changes the digest.
+ * @param rootDir - Absolute monorepo root.
+ * @returns A hex sha-256 digest, and the relative file list it was computed from (reused by the
+ *   caller so the directory tree is walked only once).
+ */
+declare function computeWorkspaceSourceDigest(rootDir: string): {
+    digest: string;
+    files: string[];
+};
 /**
  * @description Auto-detects the monorepo layout under `rootDir` and builds a per-package
  *   dependency graph, stitching them together into a single WorkspaceGraph.
  * @param rootDir - Absolute path to the monorepo root.
- * @param options - `packages` filters to a named subset of packages; `silent` suppresses progress; `gitStats` attaches git churn data per file; `parallelParsing` controls worker-pool offloading of file parsing per package (see {@link ParallelParsingOption}); `pathAliases` overrides/extends tsconfig path-alias resolution for every package (see `MokoshConfig.pathAliases`).
+ * @param options - `packages` filters to a named subset of packages; `silent` suppresses progress; `gitStats` attaches git churn data per file; `parallelParsing` controls worker-pool offloading of file parsing per package (see {@link ParallelParsingOption}); `pathAliases` overrides/extends tsconfig path-alias resolution for every package (see `MokoshConfig.pathAliases`); `layout` supplies a pre-computed `detectMonorepo` result so detection is not repeated by callers that already ran it.
  * @returns A WorkspaceGraph where each package has its own Graph and cross-package edges are resolved.
  */
 declare function createWorkspaceGraph(rootDir: string, options?: {
-    packages?: string[];
+    packages?: string[] | undefined;
     silent?: boolean;
     gitStats?: boolean;
     parallelParsing?: ParallelParsingOption | undefined;
     pathAliases?: Record<string, string[]> | undefined;
+    additionalIgnoreDirs?: string[] | undefined;
+    layout?: MonorepoLayout | undefined;
+    /** Pre-computed `getAllProjectFiles(rootDir)` result, so the caller's digest walk isn't repeated. */
+    projectFiles?: string[] | undefined;
+    /** A previously built workspace graph; each package reuses its prior graph as an incremental
+     *  base so unchanged files are not re-parsed (mtime+size match). */
+    previousWorkspace?: WorkspaceGraph | undefined;
 }): Promise<WorkspaceGraph>;
 /**
  * @description Recursively walks `rootDir` and returns paths of every file whose extension
@@ -1538,4 +1897,4 @@ declare function createWorkspaceGraph(rootDir: string, options?: {
  */
 declare function getAllProjectFiles(rootDir: string, options?: ScanOptions): string[];
 
-export { type ApiSurface, type ApplyTagsFileResult, type ApplyTagsResult, CALL_EDGE_TYPES, type CachedFileTokens, CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type ComplexFunctionEntry, DEFAULT_CACHE_DIR, DEFAULT_DUPLICATION_TOKEN_CACHE_FILE, DEFAULT_EXTENSIONS, DEFAULT_GRAPH_CACHE_FILE, DEFAULT_IGNORE_DIRS, type DependencyGraph, type DuplicateFamily, type DuplicateGroup, type DuplicateOccurrence, type DuplicationTokenCache, EXPORT_TRACKING_TYPES, type ExportKind, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, FileNode, FileType, type FindComplexFunctionsOptions, type FindDuplicatesOptions, type FindDuplicatesResult, type FindRiskHotspotsOptions, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, type CallerEntry as GraphCallerEntry, type GraphExporter, IMPORT_SYMBOL_TYPES, ImportEdge, type LanguageCoverage, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, NodeCategory, type NodeMeta, type NodeQuery, type ParallelParsingOption, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type RiskHotspotEntry, type RiskHotspotsResult, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, StructuredTag, type SymbolCaller, type SymbolImporter, type SymbolMatch, type SymbolPrecision, SymbolTraversalContext, type TestNodeIdentifier, type TraversalOptions, type TraversalVisitor, type TypeEdge, type TypeGraph, type TypeKind, type TypeNode, type TypeQueryResult, WorkspaceGraph, type WorkspacePackage, type WorkspacePackageSummary, type WorkspacePackagesSummary, applyConfig, applyTags, buildApiSurface, buildChangeImpactCache, buildFeatureGraph, buildResponsibilityGraph, buildTypeGraph, computeGraphHash, configToGraphOptions, createImportMap, createWorkspaceGraph, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, filterGraph, findComplexFunctions, findDuplicates, findRiskHotspots, findSymbol, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, getLanguageCoverage, getNodeMeta, hasChurnData, hasCoverageData, isChangeImpactCacheValid, loadChangeImpactCache, loadCoverageMap, loadMokoshConfig, loadTokenCacheFromDisk, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, resetClassifyRegistries, saveChangeImpactCache, saveTokenCacheToDisk, slimSerialize, summarizeWorkspacePackages, toMermaid };
+export { type ApiSurface, type ApplyTagsFileResult, type ApplyTagsResult, type BranchComparison, type BranchComparisonSummary, type BuildGraphAtRefOptions, CALL_EDGE_TYPES, type CachedFileTokens, CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type CompareBranchesOptions, type ComplexFunctionEntry, type ComplexityDelta, type CoverageDelta, type CycleEdgeKind, DEFAULT_BRANCH_GRAPH_CACHE_DIR, DEFAULT_CACHE_DIR, DEFAULT_DUPLICATION_TOKEN_CACHE_FILE, DEFAULT_EXTENSIONS, DEFAULT_GRAPH_CACHE_FILE, DEFAULT_IGNORE_DIRS, DEFAULT_WORKSPACE_GRAPH_CACHE_FILE, type DependencyGraph, type DocDriftDelta, type DuplicateFamily, type DuplicateGroup, type DuplicateOccurrence, type DuplicateSignal, type DuplicationDelta, type DuplicationTokenCache, EXPORT_TRACKING_TYPES, type ExportKind, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, type FileDiff, FileNode, FileType, type FindComplexFunctionsOptions, type FindCyclesOptions, type FindDuplicatesOptions, type FindDuplicatesResult, type FindRiskHotspotsOptions, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, GraphAnalyzer, type CallerEntry as GraphCallerEntry, type GraphExporter, IMPORT_SYMBOL_TYPES, ImportEdge, type LanguageCoverage, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, NodeCategory, type NodeMeta, type NodeQuery, type ParallelParsingOption, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type RiskHotspotEntry, type RiskHotspotsResult, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, type StaleReference, StructuredTag, type SummarizeOptions, type SymbolCaller, type SymbolImporter, type SymbolMatch, type SymbolPrecision, SymbolTraversalContext, type TestNodeIdentifier, type TraversalOptions, type TraversalVisitor, type TypeEdge, type TypeGraph, type TypeKind, type TypeNode, type TypeQueryResult, WorkspaceGraph, type WorkspaceLayoutPackageSummary, type WorkspaceLayoutSummary, type WorkspacePackage, type WorkspacePackageSummary, type WorkspacePackagesSummary, applyConfig, applyTags, buildApiSurface, buildChangeImpactCache, buildFeatureGraph, buildGraphAtRef, buildResponsibilityGraph, buildTypeGraph, compareBranches, computeGraphHash, computeWorkspaceSourceDigest, configToGraphOptions, createImportMap, createWorkspaceGraph, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, filterGraph, findComplexFunctions, findDuplicates, findRiskHotspots, findSymbol, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, getLanguageCoverage, getNodeMeta, hasChurnData, hasCoverageData, hasGeneratedMarker, isChangeImpactCacheValid, isGeneratedPath, loadChangeImpactCache, loadCoverageMap, loadMokoshConfig, loadTokenCacheFromDisk, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, resetClassifyRegistries, saveChangeImpactCache, saveTokenCacheToDisk, slimSerialize, summarizeBranchComparison, summarizeWorkspaceLayout, summarizeWorkspacePackages, toMermaid };