@omfalos/mokosh 0.1.5 → 0.1.6

package/dist/index.d.mts

@@ -1,174 +1,5 @@
-/** Tag applier strategy interface — one implementation per testing framework. */
-type TagFramework = "vitest" | "playwright" | "cypress" | "jest";
-
-/**
- * @description Top-level configuration for mokosh. All fields are optional; unset fields
- *   fall back to built-in defaults. Load this object via `loadMokoshConfig`, then activate
- *   it with `applyConfig` before calling `createImportMap`.
- */
-interface MokoshConfig {
-    /** Additional directories to skip when scanning (merged with built-in defaults). */
-    ignoreDirs?: string[];
-    /** Additional file extensions to scan (merged with built-in defaults). */
-    extensions?: string[];
-    /** Override the default cache path (`mokosh-cache/graph.json`). */
-    cachePath?: string;
-    /** Default entry points used when none are provided on the CLI. */
-    entryPoints?: string[];
-    /** Additional basename substrings that mark a file as `"config"` category. */
-    configMatchers?: string[];
-    /** Additional basename substrings that mark a file as `"test"` category (e.g. `".unit."`). */
-    testPatterns?: string[];
-    /** Additional import specifiers that indicate a test file (e.g. `"@my-org/test-utils"`). */
-    testLibraries?: string[];
-    /** Ratio of export-statements to total statements required for `"barrel"` classification. Default: `0.8`. */
-    barrelThreshold?: number;
-    /** When true, enriches each node with `commitCount90d` and `lastAuthor` via git log. Only fetched for new/modified files. */
-    gitStats?: boolean;
-    /**
-     * Tag-applier configuration for `--apply-tags`. Controls which format is written into
-     * test files. Defaults to `{ framework: "vitest" }` when unset.
-     */
-    tagApplier?: {
-        /**
-         * Fallback test framework whose tag format to use for TS/JS files. Each file's actual
-         * framework is auto-detected from its imports (`@playwright/test`, `cypress`,
-         * `@jest/globals`, `vitest`), so a single repo can mix frameworks and each file is tagged
-         * in its own native format. This value is only used when a file has no detectable
-         * framework import (e.g. `globals: true` configs with no explicit import).
-         * - `"vitest"` — injects `{ tags: [...] }` in describe/test/it options (default)
-         * - `"playwright"` — injects `{ tag: ["@name"] }` with `@` prefix convention
-         * - `"cypress"` — injects `{ tags: ["@name"] }` for use with `@cypress/grep`
-         * - `"jest"` — writes a `/** @group name *\/` docblock for use with `jest-runner-groups`
-         */
-        framework?: TagFramework;
-        /**
-         * Path-glob pattern (project-relative, e.g. `"tests/e2e/**"`) to fallback framework. Checked
-         * in object key order, first match wins, before falling back further to `framework`. Only
-         * consulted when a file's own imports don't reveal a framework — lets different directories
-         * default to different frameworks (e.g. e2e tests using Playwright globals, unit tests using
-         * Jest globals) instead of sharing one project-wide default.
-         */
-        frameworkOverrides?: Record<string, TagFramework>;
-    };
-    /** Path to the Istanbul/v8 `coverage-summary.json` file, relative to the project root. When set, `coveragePct` is populated on each node after the graph is built. */
-    coverageReportPath?: string;
-    /** Default line-coverage threshold (0–100) used by `find_uncovered`. Defaults to `80` when not specified. */
-    coverageThreshold?: number;
-}
-/**
- * @description Loads a mokosh config file, probing standard filenames in `rootDirOrPath` or reading an explicit path when `isExplicitPath` is true.
- *   JS/CJS configs may export a plain object or a factory function; the MCP server passes `allowJs: false` to prevent arbitrary code execution.
- * @param {string} rootDirOrPath - Directory to probe for standard config filenames, or absolute path to the config file when `isExplicitPath` is true.
- * @param {{ allowJs?: boolean; isExplicitPath?: boolean }} options - `allowJs` (default `true`) controls whether `.js`/`.cjs` files are loaded; `isExplicitPath` treats the first arg as a direct file path.
- * @returns {MokoshConfig} The parsed config, or an empty object when no config file is found.
- */
-declare function loadMokoshConfig(rootDirOrPath: string, { allowJs, isExplicitPath }?: {
-    allowJs?: boolean;
-    isExplicitPath?: boolean;
-}): MokoshConfig;
-/**
- * @description Applies a `MokoshConfig` to the global registries that control classification and scanning.
- *   Call this after `loadMokoshConfig` and before `createImportMap`.
- * @param {MokoshConfig} config - The loaded config whose matchers, patterns, libraries, and thresholds are registered.
- */
-declare function applyConfig(config: MokoshConfig): void;
-
-declare const DEFAULT_IGNORE_DIRS: readonly string[];
-declare const DEFAULT_EXTENSIONS: readonly string[];
-interface ScanOptions {
-    /** Replaces the default ignore-dir list. Use `additionalIgnoreDirs` to extend instead. */
-    ignoreDirs?: string[];
-    /** Replaces the default extension list. Use `additionalExtensions` to extend instead. */
-    extensions?: string[];
-    /** Merged with `DEFAULT_IGNORE_DIRS` (additive). */
-    additionalIgnoreDirs?: string[];
-    /** Merged with `DEFAULT_EXTENSIONS` (additive). */
-    additionalExtensions?: string[];
-}
-
-/**
- * @description Reads an Istanbul/v8 `coverage-summary.json` file and returns a map of
- *   project-relative file paths to their line-coverage percentage (0–100).
- *   Returns an empty map when the file is missing, unreadable, or malformed — the
- *   caller can always proceed safely with no coverage data.
- * @param rootDir - Absolute path to the project root; used to make paths relative.
- * @param reportPath - Path to the coverage summary JSON, relative to `rootDir`.
- * @returns A map of `relativePath → lineCoveragePct`.
- */
-declare function loadCoverageMap(rootDir: string, reportPath: string): Map<string, number>;
-
-type FileType = "javascript" | "typescript" | "css" | "scss" | "less" | "stylus" | "coffeescript" | "livescript" | "lua" | "gherkin" | "python" | "go" | "unknown";
-type ImportType = "static" | "dynamic" | "require" | "re-export" | "side-effect";
-type NodeCategory = "logic" | "ui" | "type-only" | "config" | "test" | "barrel" | "other";
-type TagKind = "function" | "class" | "variable" | "type" | "import" | "library" | "comment-marker";
-
-interface StructuredTag {
-    name: string;
-    kind: TagKind;
-}
-interface ExportedSymbol {
-    name: string;
-    doc?: string;
-    flags?: string[];
-    signature?: string;
-}
-interface ImportEdge {
-    fromPath: string;
-    toPath: string;
-    isStyle: boolean;
-    rawSpecifier: string;
-    type: ImportType;
-    symbols?: string[] | undefined;
-    isExternal?: boolean | undefined;
-    version?: string | undefined;
-    /** True when this import resolves to a sibling workspace package rather than an external npm dep. */
-    isWorkspace?: boolean | undefined;
-    /** The workspace package name (e.g. `"@myorg/shared"`) when `isWorkspace` is true. */
-    workspacePackage?: string | undefined;
-    /** Fraction of the target's exports consumed by this import (0–1). Only present for internal non-side-effect imports where the target has at least one export. */
-    exportUsageRatio?: number;
-}
-interface CallEdge {
-    from: string;
-    to: string;
-    toFile: string;
-}
-interface FunctionComplexity {
-    name: string;
-    line: number;
-    complexity: number;
-    cognitiveComplexity: number;
-}
-interface GraphNode {
-    path: string;
-    type: FileType;
-    category: NodeCategory;
-    imports: ImportEdge[];
-    exports: ExportedSymbol[];
-    tags: StructuredTag[];
-}
-interface FileNode extends GraphNode {
-    mtime: number;
-    size: number;
-    description?: string;
-    testedBy?: string[];
-    commitCount90d?: number;
-    lastAuthor?: string;
-    callEdges?: CallEdge[];
-    /** Line coverage percentage (0–100) from the last coverage report. Undefined when no report was loaded. */
-    coveragePct?: number;
-    /** Average exportUsageRatio across all outgoing internal import edges that have a computable ratio. */
-    avgExportUsage?: number;
-    /** Highest single-edge exportUsageRatio for this file — identifies the dependency whose API surface is most consumed. */
-    maxExportUsage?: number;
-    /** McCabe cyclomatic complexity (base 1). Counts independent decision paths through the file. Only present for TypeScript/JavaScript files. */
-    complexity?: number;
-    /** Cognitive complexity — nesting-penalised difficulty score. Higher values indicate harder-to-read code. Only present for TypeScript/JavaScript files. */
-    cognitiveComplexity?: number;
-    /** Per-function complexity breakdown. Covers named function declarations, const-assigned arrow/function expressions, and class methods/constructors/accessors — anonymous inline callbacks are not included. Only present for TypeScript/JavaScript files. */
-    functions?: FunctionComplexity[];
-}
+import { F as FileNode, C as CallEdge, I as ImportEdge, a as FileType, P as ParseResult, S as StructuredTag } from './types-C9fLCS45.mjs';
+export { E as ExportedSymbol, b as ImportType, N as NodeCategory, T as TagKind } from './types-C9fLCS45.mjs';
 
 interface SerializedGraph {
     nodes: FileNode[];
@@ -283,6 +114,121 @@ declare class Graph {
     findCycles(): string[][];
 }
 
+/** Configures whether/how `parseFile` calls are offloaded to a `piscina` worker pool. `false` always parses in-process. */
+type ParallelParsingOption = boolean | {
+    minFiles?: number;
+    maxThreads?: number;
+};
+
+/** Tag applier strategy interface — one implementation per testing framework. */
+type TagFramework = "vitest" | "playwright" | "cypress" | "jest";
+
+/**
+ * @description Top-level configuration for mokosh. All fields are optional; unset fields
+ *   fall back to built-in defaults. Load this object via `loadMokoshConfig`, then activate
+ *   it with `applyConfig` before calling `createImportMap`.
+ */
+interface MokoshConfig {
+    /** Additional directories to skip when scanning (merged with built-in defaults). */
+    ignoreDirs?: string[];
+    /** Additional file extensions to scan (merged with built-in defaults). */
+    extensions?: string[];
+    /** Override the default cache path (`mokosh-cache/graph.json`). */
+    cachePath?: string;
+    /** Default entry points used when none are provided on the CLI. */
+    entryPoints?: string[];
+    /** Additional basename substrings that mark a file as `"config"` category. */
+    configMatchers?: string[];
+    /** Additional basename substrings that mark a file as `"test"` category (e.g. `".unit."`). */
+    testPatterns?: string[];
+    /** Additional import specifiers that indicate a test file (e.g. `"@my-org/test-utils"`). */
+    testLibraries?: string[];
+    /** Ratio of export-statements to total statements required for `"barrel"` classification. Default: `0.8`. */
+    barrelThreshold?: number;
+    /** When true, enriches each node with `commitCount90d` and `lastAuthor` via git log. Only fetched for new/modified files. */
+    gitStats?: boolean;
+    /**
+     * Tag-applier configuration for `--apply-tags`. Controls which format is written into
+     * test files. Defaults to `{ framework: "vitest" }` when unset.
+     */
+    tagApplier?: {
+        /**
+         * Fallback test framework whose tag format to use for TS/JS files. Each file's actual
+         * framework is auto-detected from its imports (`@playwright/test`, `cypress`,
+         * `@jest/globals`, `vitest`), so a single repo can mix frameworks and each file is tagged
+         * in its own native format. This value is only used when a file has no detectable
+         * framework import (e.g. `globals: true` configs with no explicit import).
+         * - `"vitest"` — injects `{ tags: [...] }` in describe/test/it options (default)
+         * - `"playwright"` — injects `{ tag: ["@name"] }` with `@` prefix convention
+         * - `"cypress"` — injects `{ tags: ["@name"] }` for use with `@cypress/grep`
+         * - `"jest"` — writes a `/** @group name *\/` docblock for use with `jest-runner-groups`
+         */
+        framework?: TagFramework;
+        /**
+         * Path-glob pattern (project-relative, e.g. `"tests/e2e/**"`) to fallback framework. Checked
+         * in object key order, first match wins, before falling back further to `framework`. Only
+         * consulted when a file's own imports don't reveal a framework — lets different directories
+         * default to different frameworks (e.g. e2e tests using Playwright globals, unit tests using
+         * Jest globals) instead of sharing one project-wide default.
+         */
+        frameworkOverrides?: Record<string, TagFramework>;
+    };
+    /** Path to the Istanbul/v8 `coverage-summary.json` file, relative to the project root. When set, `coveragePct` is populated on each node after the graph is built. */
+    coverageReportPath?: string;
+    /** Default line-coverage threshold (0–100) used by `find_uncovered`. Defaults to `80` when not specified. */
+    coverageThreshold?: number;
+    /**
+     * Controls worker-pool offloading of file parsing (see docs/adr-010-parallel-parsing.md).
+     * `true`/unset (default) enables it once a cheap pre-scan finds at least `minFiles`
+     * (default 20) files; parsing a file is fast enough in most repos that the pool's
+     * per-thread startup cost only pays off past roughly 600-700 files, so small/typical
+     * repos may see slightly slower builds under the default — set `false` to always parse
+     * in-process, or pass `{ minFiles, maxThreads }` to raise the threshold instead.
+     */
+    parallelParsing?: ParallelParsingOption;
+}
+/**
+ * @description Loads a mokosh config file, probing standard filenames in `rootDirOrPath` or reading an explicit path when `isExplicitPath` is true.
+ *   JS/CJS configs may export a plain object or a factory function; the MCP server passes `allowJs: false` to prevent arbitrary code execution.
+ * @param {string} rootDirOrPath - Directory to probe for standard config filenames, or absolute path to the config file when `isExplicitPath` is true.
+ * @param {{ allowJs?: boolean; isExplicitPath?: boolean }} options - `allowJs` (default `true`) controls whether `.js`/`.cjs` files are loaded; `isExplicitPath` treats the first arg as a direct file path.
+ * @returns {MokoshConfig} The parsed config, or an empty object when no config file is found.
+ */
+declare function loadMokoshConfig(rootDirOrPath: string, { allowJs, isExplicitPath }?: {
+    allowJs?: boolean;
+    isExplicitPath?: boolean;
+}): MokoshConfig;
+/**
+ * @description Applies a `MokoshConfig` to the global registries that control classification and scanning.
+ *   Call this after `loadMokoshConfig` and before `createImportMap`.
+ * @param {MokoshConfig} config - The loaded config whose matchers, patterns, libraries, and thresholds are registered.
+ */
+declare function applyConfig(config: MokoshConfig): void;
+
+declare const DEFAULT_IGNORE_DIRS: readonly string[];
+declare const DEFAULT_EXTENSIONS: readonly string[];
+interface ScanOptions {
+    /** Replaces the default ignore-dir list. Use `additionalIgnoreDirs` to extend instead. */
+    ignoreDirs?: string[];
+    /** Replaces the default extension list. Use `additionalExtensions` to extend instead. */
+    extensions?: string[];
+    /** Merged with `DEFAULT_IGNORE_DIRS` (additive). */
+    additionalIgnoreDirs?: string[];
+    /** Merged with `DEFAULT_EXTENSIONS` (additive). */
+    additionalExtensions?: string[];
+}
+
+/**
+ * @description Reads an Istanbul/v8 `coverage-summary.json` file and returns a map of
+ *   project-relative file paths to their line-coverage percentage (0–100).
+ *   Returns an empty map when the file is missing, unreadable, or malformed — the
+ *   caller can always proceed safely with no coverage data.
+ * @param rootDir - Absolute path to the project root; used to make paths relative.
+ * @param reportPath - Path to the coverage summary JSON, relative to `rootDir`.
+ * @returns A map of `relativePath → lineCoveragePct`.
+ */
+declare function loadCoverageMap(rootDir: string, reportPath: string): Map<string, number>;
+
 /**
  * Coarse kind of a public export derived from its type signature prefix.
  * Used to distinguish runtime values from type-only exports without parsing the full signature.
@@ -1033,26 +979,6 @@ declare function registerTestPattern(pattern: string): void;
  */
 declare function registerTestLibrary(lib: string): void;
 
-interface RawCallEdge {
-    from: string;
-    to: string;
-    toSpecifier: string;
-}
-interface ParseResult {
-    imports: ImportEdge[];
-    exports: ExportedSymbol[];
-    tags: StructuredTag[];
-    category: NodeCategory;
-    rawCallEdges?: RawCallEdge[];
-    description?: string;
-    /** McCabe cyclomatic complexity of the file (base 1, undefined for non-TS/JS files). */
-    complexity?: number;
-    /** Cognitive complexity — nesting-aware difficulty score (undefined for non-TS/JS files). */
-    cognitiveComplexity?: number;
-    /** Per-function complexity breakdown (undefined for non-TS/JS files). */
-    functions?: FunctionComplexity[];
-}
-
 /** Parser registry: maps FileType values to parser functions and provides lookup by file type. */
 
 type ParserFunction = (filePath: string, content: string) => ParseResult | Promise<ParseResult>;
@@ -1224,25 +1150,27 @@ 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.
+ * @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}).
  * @returns The fully-built Graph with all reachable nodes and import edges populated.
  */
 declare function createImportMap(rootDir: string, entryPoints: string[], previousGraph?: Graph | null, options?: {
     silent?: boolean;
     gitStats?: boolean;
     coverageMap?: Map<string, number>;
+    parallelParsing?: ParallelParsingOption | undefined;
 }): Promise<Graph>;
 /**
  * @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.
+ * @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}).
  * @returns A WorkspaceGraph where each package has its own Graph and cross-package edges are resolved.
  */
 declare function createWorkspaceGraph(rootDir: string, options?: {
     packages?: string[];
     silent?: boolean;
     gitStats?: boolean;
+    parallelParsing?: ParallelParsingOption | undefined;
 }): Promise<WorkspaceGraph>;
 /**
  * @description Recursively walks `rootDir` and returns paths of every file whose extension
@@ -1253,4 +1181,4 @@ declare function createWorkspaceGraph(rootDir: string, options?: {
  */
 declare function getAllProjectFiles(rootDir: string, options?: ScanOptions): string[];
 
-export { type ApiSurface, type ApplyTagsFileResult, type ApplyTagsResult, type CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type ComplexFunctionEntry, DEFAULT_EXTENSIONS, DEFAULT_IGNORE_DIRS, type DependencyGraph, type ExportKind, type ExportedSymbol, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, type FileNode, type FileType, type FindComplexFunctionsOptions, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, type CallerEntry as GraphCallerEntry, type GraphExporter, type ImportEdge, type ImportType, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, type NodeCategory, type NodeQuery, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, type StructuredTag, SymbolTraversalContext, type TagKind, 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, createImportMap, createWorkspaceGraph, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, filterGraph, findComplexFunctions, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, hasCoverageData, isChangeImpactCacheValid, loadChangeImpactCache, loadCoverageMap, loadMokoshConfig, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, saveChangeImpactCache, slimSerialize, summarizeWorkspacePackages, toMermaid };
+export { type ApiSurface, type ApplyTagsFileResult, type ApplyTagsResult, CallEdge, type CalleeEntry, type CallerEntry$1 as CallerEntry, type ChangeImpactCache, type ComplexFunctionEntry, DEFAULT_EXTENSIONS, DEFAULT_IGNORE_DIRS, type DependencyGraph, type ExportKind, type FeatureDetectionOptions, type FeatureDomain, type FeatureGraph, type FeatureGraphOptions, type FeatureInfo, FileNode, FileType, type FindComplexFunctionsOptions, type FunctionCallInfo, type GetAffectedOptions, type GetCallersOptions, Graph, type CallerEntry as GraphCallerEntry, type GraphExporter, ImportEdge, MermaidExporter, type ModuleResponsibility, type ModuleRole, type MokoshConfig, type MonorepoDetector, type MonorepoLayout, type NodeQuery, type ParallelParsingOption, type PathWithSymbols, type ProposeTagsOptions, type PublicExport, type ResponsibilityGraph, type ScanOptions, type SerializedGraph, type SerializedWorkspaceGraph, type SlimNode, type SlimSerializedGraph, StructuredTag, 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, createImportMap, createWorkspaceGraph, detectAllEntryPoints, detectEntryPoint, detectFeatures, detectMonorepo, filterGraph, findComplexFunctions, getAffected, getAllProjectFiles, getCallers, getDependencies, getDependents, hasCoverageData, isChangeImpactCacheValid, loadChangeImpactCache, loadCoverageMap, loadMokoshConfig, parseQuery, proposeAffectedTests, proposeTags, queryCallGraph, queryChangeImpact, queryTypeGraph, registerConfigMatcher, registerMonorepoDetector, registerParser, registerTestLibrary, registerTestPattern, saveChangeImpactCache, slimSerialize, summarizeWorkspacePackages, toMermaid };