Core analysis functionality that examines project files, builds comprehensive dependency graphs, and validates dependencies against configured rules.
Performs comprehensive dependency analysis of files and directories, building dependency graphs and validating against rules.
/**
* Cruises the specified files and directories and returns analysis results
* @param fileAndDirectoryArray - Array of files, directories, or glob patterns to analyze
* @param cruiseOptions - Options controlling analysis behavior and rule validation
* @param resolveOptions - Options controlling how dependencies are resolved to disk
* @param transpileOptions - Options for underlying transpilers like TypeScript or Babel
* @returns Promise resolving to analysis results with exit code
*/
function cruise(
fileAndDirectoryArray: string[],
cruiseOptions?: ICruiseOptions,
resolveOptions?: Partial<IResolveOptions>,
transpileOptions?: ITranspileOptions
): Promise<IReporterOutput>;Usage Examples:
import { cruise } from "dependency-cruiser";
// Basic analysis
const result = await cruise(["src"]);
// Analysis with rule validation
const result = await cruise(
["src", "test"],
{
validate: true,
ruleSet: {
forbidden: [
{
name: "no-circular",
from: {},
to: { circular: true }
}
]
}
}
);
// Analysis with TypeScript support
const result = await cruise(
["src"],
{ tsPreCompilationDeps: true },
{ extensions: [".ts", ".tsx", ".js"] },
{ tsConfig: { fileName: "./tsconfig.json" } }
);
// Analysis with caching for performance
const result = await cruise(
["src"],
{
cache: {
folder: "node_modules/.cache/dependency-cruiser",
strategy: "metadata"
}
}
);Configuration options that control how the dependency analysis is performed.
interface ICruiseOptions {
/** Enable rule validation against the ruleSet */
validate?: boolean;
/** Rules to validate dependencies against */
ruleSet?: IFlattenedRuleSet;
/** Path to configuration file containing rules */
rulesFile?: string;
/** Output format for results */
outputType?: OutputType;
/** Regular expression or conditions describing which dependencies not to follow */
doNotFollow?: string | string[] | IDoNotFollowType;
/** Regular expression describing which dependencies to exclude from analysis */
exclude?: string | string[] | IExcludeType;
/** Regular expression describing which dependencies to include (others skipped) */
includeOnly?: string | string[] | IIncludeOnlyType;
/** Include modules matching this pattern and their neighbors */
focus?: string | string[] | IFocusType;
/** Include modules matching this pattern and any modules that reach them */
reaches?: string | string[] | IReachesType;
/** Highlight modules matching this pattern in output */
highlight?: string | string[] | IHighlightType;
/** Maximum depth to cruise (0 = infinite) */
maxDepth?: number | string;
/** Module systems to follow for dependencies */
moduleSystems?: ModuleSystemType[];
/** Detect dependencies in JSDoc-style import statements */
detectJSDocImports?: boolean;
/** Base directory to run cruise from */
baseDir?: string;
/** Detect TypeScript pre-compilation dependencies */
tsPreCompilationDeps?: boolean | "specify";
/** Additional file extensions to scan */
extraExtensionsToScan?: string[];
/** Preserve symlinks instead of following to real paths */
preserveSymlinks?: boolean;
/** Calculate stability metrics for modules and folders */
metrics?: boolean;
/** Calculate experimental statistics (performance impact) */
experimentalStats?: boolean;
/** Skip analysis that doesn't serve any rules (performance optimization) */
skipAnalysisNotInRules?: boolean;
/** Caching configuration for performance */
cache?: boolean | string | Partial<ICacheOptions>;
/** Progress reporting configuration */
progress?: {
type: ProgressType;
maximumLevel?: -1 | 40 | 50 | 60 | 70 | 80 | 99;
};
/** TypeScript configuration to use */
tsConfig?: ITsConfig;
/** Webpack configuration to extract resolve options from */
webpackConfig?: IWebpackConfig;
/** Babel configuration to use */
babelConfig?: IBabelConfig;
/** Override parser selection (experimental) */
parser?: ParserType;
/** Enhanced resolve options */
enhancedResolveOptions?: IEnhancedResolveOptions;
}Options controlling how module dependencies are resolved to actual files.
interface IResolveOptions {
/** File extensions to resolve */
extensions?: string[];
/** Main fields to check in package.json */
mainFields?: string[];
/** Main files to look for when resolving directories */
mainFiles?: string[];
/** Module directories to search */
modules?: string[];
/** Alias configuration for module resolution */
alias?: { [key: string]: string };
}Options passed to underlying transpilers like TypeScript or Babel.
interface ITranspileOptions {
/** TypeScript configuration object */
tsConfig?: any;
/** Babel configuration object */
babelConfig?: any;
}The result structure returned by the cruise function.
interface IReporterOutput {
/** Analysis results or formatted string output */
output: ICruiseResult | string;
/** Exit code indicating success (0) or errors found */
exitCode: number;
}
interface ICruiseResult {
/** Array of analyzed modules with their dependencies */
modules: IModule[];
/** Folder-level metrics (when metrics enabled) */
folders?: IFolder[];
/** Summary statistics and violation information */
summary: ISummary;
/** Caching and revision information */
revisionData?: IRevisionData;
}
interface IModule {
/** Resolved file path of the module */
source: string;
/** Whether module passes all rule validations */
valid: boolean;
/** Array of dependencies this module has */
dependencies: IDependency[];
/** Array of modules that depend on this module */
dependents: string[];
/** Whether this is a Node.js core module */
coreModule?: boolean;
/** Whether dependency-cruiser could resolve this module */
couldNotResolve?: boolean;
/** Classification of dependency types */
dependencyTypes?: DependencyType[];
/** Whether this module can be followed further */
followable?: boolean;
/** License information (for npm modules) */
license?: string;
/** Whether module matches doNotFollow pattern */
matchesDoNotFollow?: boolean;
/** Whether module matches focus filter pattern */
matchesFocus?: boolean;
/** Whether module matches reaches filter pattern */
matchesReaches?: boolean;
/** Whether module matches highlight pattern */
matchesHighlight?: boolean;
/** Whether module is orphaned (no dependencies or dependents) */
orphan?: boolean;
/** Reachability information based on rules */
reachable?: IReachable[];
/** Modules this module reaches based on rules */
reaches?: IReaches[];
/** Rule violations for this module */
rules?: IRuleSummary[];
/** Stability metric (when metrics enabled) */
instability?: number;
/** Experimental statistics (when experimentalStats enabled) */
experimentalStats?: ExperimentalStatsType;
}
interface IDependency {
/** Module name as it appears in source code */
module: string;
/** Resolved file path */
resolved: string;
/** Whether following this dependency creates a circular reference */
circular: boolean;
/** Whether this dependency could not be resolved */
couldNotResolve: boolean;
/** Whether this is a TypeScript pre-compilation only dependency */
preCompilationOnly?: boolean;
/** Whether this is a TypeScript type-only import */
typeOnly?: boolean;
/** Circular path if circular is true */
cycle?: IMiniDependency[];
/** Classification of dependency types */
dependencyTypes: DependencyType[];
/** Whether this is a dynamic import */
dynamic: boolean;
/** Whether this is an exotic require (non-standard require) */
exoticallyRequired: boolean;
/** The exotic require string used */
exoticRequire?: string;
/** Whether this dependency can be followed further */
followable: boolean;
/** License information */
license?: string;
/** Whether dependency matches doNotFollow pattern */
matchesDoNotFollow?: boolean;
/** Module system used for this dependency */
moduleSystem: ModuleSystemType;
/** Protocol if URI-based module specification */
protocol: ProtocolType;
/** MIME type if URI-based module specification */
mimeType: string;
/** Rule violations for this dependency */
rules?: IRuleSummary[];
/** Whether dependency passes all rule validations */
valid: boolean;
/** Stability metric of the dependency */
instability: number;
}Summary statistics and information about the analysis results.
interface ISummary {
/** Number of error-level violations found */
error: number;
/** Number of ignored violations */
ignore: number;
/** Number of informational violations */
info: number;
/** Number of warning-level violations */
warn: number;
/** Total number of modules analyzed */
totalCruised: number;
/** Total number of dependencies analyzed */
totalDependenciesCruised?: number;
/** Options used for the analysis */
optionsUsed: IOptions;
/** Rule set used for validation */
ruleSetUsed?: IFlattenedRuleSet;
/** Detailed list of all violations found */
violations: IViolation[];
}Options for optimizing analysis performance through caching and selective analysis.
interface ICacheOptions {
/** Cache storage folder */
folder: string;
/** Caching strategy - 'metadata' (fast) or 'content' (thorough) */
strategy: "metadata" | "content";
/** Whether to compress cached data */
compress?: boolean;
}
type ProgressType = "cli-feedback" | "performance-log" | "ndjson" | "none";
type ParserType = "acorn" | "tsc" | "swc";