@omfalos/mokosh 0.4.4 → 0.5.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-BlN-U5AM.js';
-export { E as ExportedSymbol } from './types-BlN-U5AM.js';
-import { N as NormalizedToken } from './tokenizer-BaF1eUBQ.js';
-import { F as FileType, N as NodeCategory } from './parse-CAKctgb6.js';
-export { I as ImportType, T as TagKind } from './parse-CAKctgb6.js';
+import { F as FileNode, C as CallEdge, I as ImportEdge, P as ParseResult, S as StructuredTag } from './types-y90pqeDR.js';
+export { E as ExportedSymbol } from './types-y90pqeDR.js';
+import { N as NormalizedToken } from './tokenizer-DIbb0GLe.js';
+import { F as FileType, N as NodeCategory } from './parse-yamNoaoL.js';
+export { I as ImportType, T as TagKind } from './parse-yamNoaoL.js';
 
 interface SerializedGraph {
     nodes: FileNode[];
@@ -222,8 +222,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 +233,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 +247,10 @@ 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";
+/** 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 {
@@ -961,6 +966,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.
@@ -1027,32 +1043,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 +1221,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 +1593,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 +1695,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,6 +1704,7 @@ declare function createImportMap(rootDir: string, entryPoints: string[], previou
     coverageMap?: Map<string, number>;
     parallelParsing?: ParallelParsingOption | undefined;
     pathAliases?: Record<string, string[]> | undefined;
+    additionalIgnoreDirs?: string[] | undefined;
 }): Promise<Graph>;
 /**
  * @description Auto-detects the monorepo layout under `rootDir` and builds a per-package
@@ -1538,4 +1729,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, DEFAULT_BRANCH_GRAPH_CACHE_DIR, DEFAULT_CACHE_DIR, DEFAULT_DUPLICATION_TOKEN_CACHE_FILE, DEFAULT_EXTENSIONS, DEFAULT_GRAPH_CACHE_FILE, DEFAULT_IGNORE_DIRS, type DependencyGraph, type DocDriftDelta, type DuplicateFamily, type DuplicateGroup, type DuplicateOccurrence, 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 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, 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 WorkspacePackage, type WorkspacePackageSummary, type WorkspacePackagesSummary, applyConfig, applyTags, buildApiSurface, buildChangeImpactCache, buildFeatureGraph, buildGraphAtRef, buildResponsibilityGraph, buildTypeGraph, compareBranches, 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, summarizeBranchComparison, summarizeWorkspacePackages, toMermaid };