tdepend 0.2.0

package/README.md

@@ -0,0 +1,167 @@
+# TDepend
+
+TDepend is a JDepend-inspired dependency analysis tool for the TypeScript ecosystem.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 📊 Compute architectural metrics (Ca, Ce, Abstractness, Instability, Distance)
+- 🔄 Detect circular dependencies
+- 📏 Threshold-based quality gates for CI/CD
+- 🎯 Scoped analysis (module/namespace/class)
+- ⚙️ Fully config-driven with sensible defaults
+- 🚀 CI mode with JSON output
+- 📦 Zero runtime dependencies for analysis
+
+## Installation
+
+```bash
+npm install -g tdepend
+# or
+pnpm add -g tdepend
+# or
+yarn global add tdepend
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Analyze your TypeScript project
+tdepend analyze
+
+# Use custom config file
+tdepend analyze --config my-config.json
+
+# CI mode with JSON output
+tdepend analyze --ci
+
+# Export full analysis to JSON file
+tdepend analyze --export analysis-result.json
+```
+
+### Library Usage
+
+TDepend can also be used programmatically as a library:
+
+```typescript
+import { analyze, exportToFile } from 'tdepend';
+
+// Analyze a project
+const result = await analyze({
+  rootDir: 'src',
+  include: ['src/**/*.ts'],
+  failOnCycle: true
+});
+
+console.log(`Analyzed ${result.modules.length} modules`);
+console.log(`Found ${result.cycles.length} cycles`);
+
+// Export results to JSON
+await exportToFile(result, 'architecture-snapshot.json');
+
+// Access detailed metrics
+for (const metric of result.metrics) {
+  if (metric.distance > 0.8) {
+    console.log(`${metric.filePath}: D=${metric.distance.toFixed(2)}`);
+  }
+}
+```
+
+#### API Reference
+
+**Main Functions:**
+- `analyze(options?)` - Analyze a TypeScript project
+- `analyzeWithConfig(config)` - Analyze using a full config object
+- `exportToFile(result, filePath, options?)` - Export analysis to JSON file
+- `exportToJson(result, options?)` - Convert analysis to JSON string
+
+**Core Building Blocks:**
+- `DependencyGraph` - Graph data structure
+- `detectCycles(graph)` - Cycle detection
+- `computeAllMetrics(graph, modules, cycles)` - Metric computation
+- `parseProject(files)` - Parse TypeScript files
+- `scanFiles(config)` - Scan files matching patterns
+
+See the [examples](./examples) directory for more usage patterns.
+
+## Configuration
+
+TDepend looks for `tdepend.config.json` in the current directory.
+
+### Config File Example
+
+```json
+{
+  "rootDir": "src",
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["**/*.test.ts", "**/*.spec.ts", "dist"],
+  "metrics": {
+    "enabled": ["coupling", "abstractness", "distance", "cycles"],
+    "thresholds": {
+      "distance": 0.6
+    }
+  },
+  "analysis": {
+    "target": null,
+    "value": null
+  },
+  "ci": {
+    "failOnThreshold": true,
+    "outputFormat": "json"
+  }
+}
+```
+
+### Configuration Options
+
+- **rootDir**: Root directory for analysis (default: `"src"`)
+- **include**: Glob patterns for files to include (default: `["src/**/*.ts", "src/**/*.tsx"]`)
+- **exclude**: Glob patterns for files to exclude (default: `["**/*.test.ts", "**/*.spec.ts", "dist"]`)
+- **metrics.enabled**: Array of metrics to compute (options: `"coupling"`, `"abstractness"`, `"distance"`, `"cycles"`)
+- **metrics.thresholds.distance**: Maximum allowed distance from main sequence (default: `0.6`)
+- **analysis.target**: Scope analysis to `"module"`, `"class"`, or `"namespace"` (default: `null`)
+- **analysis.value**: Value for the target scope (default: `null`)
+- **ci.failOnThreshold**: Exit with code 1 on threshold violations (default: `true`)
+- **ci.failOnCycle**: Exit with code 1 when cycles are detected (default: `false`)
+- **ci.outputFormat**: Output format - `"console"` or `"json"` (default: `"console"`)
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Format code
+pnpm format
+```
+
+## Project Structure
+```
+src/
+  api/           # Public library API
+  cli/           # CLI entry point
+  config/        # Configuration loading and validation
+  parser/        # TypeScript file parsing
+  graph/         # Dependency graph and cycle detection
+  metrics/       # Metric computation
+  analysis/      # Reporting
+  utils/         # Utilities
+  tests/         # Test files
+  types/         # Type definitions
+  index.ts       # Library entry point
+
+dist/            # Compiled output
+examples/        # Usage examples
+```
+
+## License
+MIT

package/dist/analysis/reporter.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedModule } from '../types/parser';
+import type { ModuleMetrics } from '../types/graph';
+import type { TDependConfig } from '../config/schema';
+export interface AnalysisReport {
+    summary: {
+        totalModules: number;
+        totalImports: number;
+        totalExports: number;
+        totalClasses: number;
+        totalInterfaces: number;
+        cyclesDetected: number;
+    };
+    metrics: ModuleMetrics[];
+    violations: {
+        cycles: string[][];
+        thresholdExceeded: ModuleMetrics[];
+    };
+    success: boolean;
+}
+export declare function generateReport(modules: ParsedModule[], metrics: ModuleMetrics[], cycles: string[][], config: TDependConfig): AnalysisReport;
+export declare function formatConsoleOutput(report: AnalysisReport, config: TDependConfig): void;
+export declare function formatJsonOutput(report: AnalysisReport): string;

package/dist/analysis/reporter.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateReport = generateReport;
+exports.formatConsoleOutput = formatConsoleOutput;
+exports.formatJsonOutput = formatJsonOutput;
+function generateReport(modules, metrics, cycles, config) {
+    const totalImports = modules.reduce((sum, m) => sum + m.imports.length, 0);
+    const totalExports = modules.reduce((sum, m) => sum + m.exports.length, 0);
+    const totalClasses = modules.reduce((sum, m) => sum + m.classes.length, 0);
+    const totalInterfaces = modules.reduce((sum, m) => sum + m.interfaces, 0);
+    const thresholdViolations = metrics.filter((m) => m.distance > config.metrics.thresholds.distance);
+    const hasCycleViolation = cycles.length > 0 && config.ci.failOnCycle;
+    const hasThresholdViolation = thresholdViolations.length > 0 && config.ci.failOnThreshold;
+    return {
+        summary: {
+            totalModules: modules.length,
+            totalImports,
+            totalExports,
+            totalClasses,
+            totalInterfaces,
+            cyclesDetected: cycles.length,
+        },
+        metrics,
+        violations: {
+            cycles,
+            thresholdExceeded: thresholdViolations,
+        },
+        success: !hasCycleViolation && !hasThresholdViolation,
+    };
+}
+function getZoneLabel(abstractness, instability) {
+    if (abstractness < 0.5 && instability < 0.5)
+        return ' (Zone of Pain)';
+    if (abstractness > 0.5 && instability > 0.5)
+        return ' (Zone of Uselessness)';
+    return '';
+}
+function displaySummary(summary) {
+    console.log('\n📊 Summary:');
+    console.log(`  Total imports: ${summary.totalImports}`);
+    console.log(`  Total exports: ${summary.totalExports}`);
+    console.log(`  Total classes: ${summary.totalClasses}`);
+    console.log(`  Total interfaces: ${summary.totalInterfaces}`);
+    console.log(`  Cycles detected: ${summary.cyclesDetected}`);
+}
+function displayCycles(cycles) {
+    if (cycles.length === 0)
+        return;
+    console.log('\n⚠️  Cycles:');
+    for (const cycle of cycles) {
+        const fileNames = cycle.map((p) => p.split('/').pop()).join(' → ');
+        console.log(`  - ${fileNames}`);
+    }
+}
+function displayTopMetrics(metrics) {
+    const sortedByCa = [...metrics].sort((a, b) => b.Ca - a.Ca);
+    const sortedByCe = [...metrics].sort((a, b) => b.Ce - a.Ce);
+    const sortedByDistance = [...metrics].sort((a, b) => b.distance - a.distance);
+    if (sortedByCa.length > 0) {
+        console.log('\n📥 Top modules by Ca (Afferent Coupling):');
+        for (const m of sortedByCa.slice(0, 3)) {
+            const fileName = m.filePath.split('/').pop();
+            console.log(`  - ${fileName}: Ca=${m.Ca}, Ce=${m.Ce}`);
+        }
+    }
+    if (sortedByCe.length > 0) {
+        console.log('\n📤 Top modules by Ce (Efferent Coupling):');
+        for (const m of sortedByCe.slice(0, 3)) {
+            const fileName = m.filePath.split('/').pop();
+            console.log(`  - ${fileName}: Ca=${m.Ca}, Ce=${m.Ce}`);
+        }
+    }
+    if (sortedByDistance.length > 0) {
+        console.log('\n📏 Modules by Distance from Main Sequence:');
+        for (const m of sortedByDistance.slice(0, 5)) {
+            const fileName = m.filePath.split('/').pop();
+            const zone = getZoneLabel(m.abstractness, m.instability);
+            console.log(`  - ${fileName}: D=${m.distance.toFixed(2)}, A=${m.abstractness.toFixed(2)}, I=${m.instability.toFixed(2)}${zone}`);
+        }
+    }
+}
+function displayThresholdViolations(violations, threshold) {
+    if (violations.length === 0)
+        return;
+    console.log(`\n⚠️  ${violations.length} module(s) exceed distance threshold (${threshold}):`);
+    for (const m of violations.slice(0, 5)) {
+        const fileName = m.filePath.split('/').pop();
+        console.log(`  - ${fileName}: D=${m.distance.toFixed(2)}`);
+    }
+    if (violations.length > 5) {
+        console.log(`  ... and ${violations.length - 5} more`);
+    }
+}
+function formatConsoleOutput(report, config) {
+    displaySummary(report.summary);
+    displayCycles(report.violations.cycles);
+    displayTopMetrics(report.metrics);
+    displayThresholdViolations(report.violations.thresholdExceeded, config.metrics.thresholds.distance);
+}
+function formatJsonOutput(report) {
+    return JSON.stringify({
+        success: report.success,
+        summary: report.summary,
+        metrics: report.metrics,
+        violations: {
+            cycles: report.violations.cycles,
+            thresholdExceeded: report.violations.thresholdExceeded.map((m) => ({
+                filePath: m.filePath,
+                distance: m.distance,
+                abstractness: m.abstractness,
+                instability: m.instability,
+            })),
+        },
+    }, null, 2);
+}
+//# sourceMappingURL=reporter.js.map

package/dist/analysis/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../../src/analysis/reporter.ts"],"names":[],"mappings":"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"}

package/dist/api/analyze.d.ts

@@ -0,0 +1,75 @@
+import type { TDependConfig } from '../config/schema';
+import type { AnalysisResult } from '../types/api';
+/**
+ * Options for the analyze() function.
+ * These options are merged with config file settings (if any).
+ */
+export interface AnalyzeOptions {
+    /** Root directory to analyze (default: 'src') */
+    rootDir?: string;
+    /** Glob patterns for files to include (default: ['src/**\/*.ts', 'src/**\/*.tsx']) */
+    include?: string[];
+    /** Glob patterns for files to exclude (default: ['**\/*.test.ts', '**\/*.spec.ts', 'dist']) */
+    exclude?: string[];
+    /** Path to config file. If not provided, looks for tdepend.config.json */
+    config?: string;
+    /** Fail analysis if cycles are detected (default: false) */
+    failOnCycle?: boolean;
+    /** Fail analysis if distance threshold is exceeded (default: true) */
+    failOnThreshold?: boolean;
+}
+/**
+ * Analyzes a TypeScript project and returns complete dependency analysis.
+ *
+ * This is the main entry point for programmatic usage of tdepend.
+ * It orchestrates the entire analysis pipeline:
+ * 1. Load and merge configuration
+ * 2. Scan files matching include/exclude patterns
+ * 3. Parse TypeScript modules
+ * 4. Build dependency graph
+ * 5. Detect cycles
+ * 6. Compute metrics (coupling, abstractness, instability, distance)
+ * 7. Generate report with violations
+ *
+ * @param options - Analysis options (merged with config file if present)
+ * @returns Complete analysis result with modules, graph, metrics, and report
+ *
+ * @example
+ * ```typescript
+ * import { analyze } from 'tdepend';
+ *
+ * const result = await analyze({
+ *   rootDir: 'src',
+ *   include: ['src/**\/*.ts'],
+ *   failOnCycle: true
+ * });
+ *
+ * console.log(`Analyzed ${result.modules.length} modules`);
+ * console.log(`Found ${result.cycles.length} cycles`);
+ * ```
+ */
+export declare function analyze(options?: AnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * Analyzes a TypeScript project using a provided configuration object.
+ *
+ * This is useful when you want full control over the configuration
+ * without loading from a file or merging with defaults.
+ *
+ * @param config - Complete TDependConfig object
+ * @returns Complete analysis result with modules, graph, metrics, and report
+ *
+ * @example
+ * ```typescript
+ * import { analyzeWithConfig, defaultConfig } from 'tdepend';
+ *
+ * const result = await analyzeWithConfig({
+ *   ...defaultConfig,
+ *   rootDir: 'src',
+ *   ci: {
+ *     ...defaultConfig.ci,
+ *     failOnCycle: true
+ *   }
+ * });
+ * ```
+ */
+export declare function analyzeWithConfig(config: TDependConfig): Promise<AnalysisResult>;

package/dist/api/analyze.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyze = analyze;
+exports.analyzeWithConfig = analyzeWithConfig;
+const loadConfig_1 = require("../config/loadConfig");
+const fileScanner_1 = require("../parser/fileScanner");
+const tsParser_1 = require("../parser/tsParser");
+const dependencyGraph_1 = require("../graph/dependencyGraph");
+const cycleDetector_1 = require("../graph/cycleDetector");
+const metrics_1 = require("../metrics");
+const reporter_1 = require("../analysis/reporter");
+const deepMerge_1 = require("../utils/deepMerge");
+/**
+ * Analyzes a TypeScript project and returns complete dependency analysis.
+ *
+ * This is the main entry point for programmatic usage of tdepend.
+ * It orchestrates the entire analysis pipeline:
+ * 1. Load and merge configuration
+ * 2. Scan files matching include/exclude patterns
+ * 3. Parse TypeScript modules
+ * 4. Build dependency graph
+ * 5. Detect cycles
+ * 6. Compute metrics (coupling, abstractness, instability, distance)
+ * 7. Generate report with violations
+ *
+ * @param options - Analysis options (merged with config file if present)
+ * @returns Complete analysis result with modules, graph, metrics, and report
+ *
+ * @example
+ * ```typescript
+ * import { analyze } from 'tdepend';
+ *
+ * const result = await analyze({
+ *   rootDir: 'src',
+ *   include: ['src/**\/*.ts'],
+ *   failOnCycle: true
+ * });
+ *
+ * console.log(`Analyzed ${result.modules.length} modules`);
+ * console.log(`Found ${result.cycles.length} cycles`);
+ * ```
+ */
+async function analyze(options = {}) {
+    // Load config from file (or use defaults if no file exists)
+    const baseConfig = options.config ? (0, loadConfig_1.loadConfig)(options.config) : (0, loadConfig_1.loadConfig)();
+    // Create partial config from options
+    const optionsConfig = {};
+    if (options.rootDir !== undefined) {
+        optionsConfig.rootDir = options.rootDir;
+    }
+    if (options.include !== undefined) {
+        optionsConfig.include = options.include;
+    }
+    if (options.exclude !== undefined) {
+        optionsConfig.exclude = options.exclude;
+    }
+    if (options.failOnCycle !== undefined || options.failOnThreshold !== undefined) {
+        optionsConfig.ci = {
+            ...baseConfig.ci,
+            ...(options.failOnCycle !== undefined && { failOnCycle: options.failOnCycle }),
+            ...(options.failOnThreshold !== undefined && { failOnThreshold: options.failOnThreshold }),
+        };
+    }
+    // Merge configs (options override file config)
+    const config = (0, deepMerge_1.deepMerge)(baseConfig, optionsConfig);
+    // Run analysis pipeline
+    const files = await (0, fileScanner_1.scanFiles)(config);
+    const modules = (0, tsParser_1.parseProject)(files);
+    const graph = new dependencyGraph_1.DependencyGraph(modules);
+    const cycles = (0, cycleDetector_1.detectCycles)(graph);
+    const metrics = (0, metrics_1.computeAllMetrics)(graph, modules, cycles);
+    const report = (0, reporter_1.generateReport)(modules, metrics, cycles, config);
+    return {
+        modules,
+        graph,
+        cycles,
+        metrics,
+        report,
+        config,
+    };
+}
+/**
+ * Analyzes a TypeScript project using a provided configuration object.
+ *
+ * This is useful when you want full control over the configuration
+ * without loading from a file or merging with defaults.
+ *
+ * @param config - Complete TDependConfig object
+ * @returns Complete analysis result with modules, graph, metrics, and report
+ *
+ * @example
+ * ```typescript
+ * import { analyzeWithConfig, defaultConfig } from 'tdepend';
+ *
+ * const result = await analyzeWithConfig({
+ *   ...defaultConfig,
+ *   rootDir: 'src',
+ *   ci: {
+ *     ...defaultConfig.ci,
+ *     failOnCycle: true
+ *   }
+ * });
+ * ```
+ */
+async function analyzeWithConfig(config) {
+    const files = await (0, fileScanner_1.scanFiles)(config);
+    const modules = (0, tsParser_1.parseProject)(files);
+    const graph = new dependencyGraph_1.DependencyGraph(modules);
+    const cycles = (0, cycleDetector_1.detectCycles)(graph);
+    const metrics = (0, metrics_1.computeAllMetrics)(graph, modules, cycles);
+    const report = (0, reporter_1.generateReport)(modules, metrics, cycles, config);
+    return {
+        modules,
+        graph,
+        cycles,
+        metrics,
+        report,
+        config,
+    };
+}
+//# sourceMappingURL=analyze.js.map

package/dist/api/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/api/analyze.ts"],"names":[],"mappings":";;AA6DA,0BA2CC;AAyBD,8CAgBC;AAjJD,qDAAkD;AAGlD,uDAAkD;AAClD,iDAAkD;AAClD,8DAA2D;AAC3D,0DAAsD;AACtD,wCAA+C;AAC/C,mDAAsD;AACtD,kDAA+C;AAsB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACI,KAAK,UAAU,OAAO,CAAC,UAA0B,EAAE;IACxD,4DAA4D;IAC5D,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAA,uBAAU,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAA,uBAAU,GAAE,CAAC;IAE9E,qCAAqC;IACrC,MAAM,aAAa,GAA2B,EAAE,CAAC;IAEjD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QAC/E,aAAa,CAAC,EAAE,GAAG;YACjB,GAAG,UAAU,CAAC,EAAE;YAChB,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;YAC9E,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC;SAC3F,CAAC;IACJ,CAAC;IAED,+CAA+C;IAC/C,MAAM,MAAM,GAAG,IAAA,qBAAS,EAAC,UAAU,EAAE,aAAa,CAAkB,CAAC;IAErE,wBAAwB;IACxB,MAAM,KAAK,GAAG,MAAM,IAAA,uBAAS,EAAC,MAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAA,uBAAY,EAAC,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,iCAAe,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAA,4BAAY,EAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAA,2BAAiB,EAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhE,OAAO;QACL,OAAO;QACP,KAAK;QACL,MAAM;QACN,OAAO;QACP,MAAM;QACN,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACI,KAAK,UAAU,iBAAiB,CAAC,MAAqB;IAC3D,MAAM,KAAK,GAAG,MAAM,IAAA,uBAAS,EAAC,MAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,IAAA,uBAAY,EAAC,KAAK,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG,IAAI,iCAAe,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAA,4BAAY,EAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAA,2BAAiB,EAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1D,MAAM,MAAM,GAAG,IAAA,yBAAc,EAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhE,OAAO;QACL,OAAO;QACP,KAAK;QACL,MAAM;QACN,OAAO;QACP,MAAM;QACN,MAAM;KACP,CAAC;AACJ,CAAC"}

package/dist/api/export.d.ts

@@ -0,0 +1,50 @@
+import type { AnalysisResult } from '../types/api';
+/**
+ * Options for exporting analysis results.
+ */
+export interface ExportOptions {
+    /**
+     * Whether to pretty-print the JSON output.
+     * @default true
+     */
+    pretty?: boolean;
+}
+/**
+ * Exports analysis results to a JSON file.
+ *
+ * This function converts the analysis result to a serializable format
+ * (fixing Set serialization issues) and writes it to the specified file.
+ *
+ * @param result - The analysis result to export
+ * @param filePath - Path where the JSON file should be written
+ * @param options - Export options (pretty-printing, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { analyze, exportToFile } from 'tdepend';
+ *
+ * const result = await analyze({ rootDir: 'src' });
+ * await exportToFile(result, 'architecture-snapshot.json');
+ * ```
+ */
+export declare function exportToFile(result: AnalysisResult, filePath: string, options?: ExportOptions): Promise<void>;
+/**
+ * Converts analysis results to a JSON string.
+ *
+ * This function converts the analysis result to a serializable format
+ * and returns it as a JSON string (does not write to file).
+ *
+ * @param result - The analysis result to export
+ * @param options - Export options (pretty-printing, etc.)
+ * @returns JSON string representation of the analysis result
+ *
+ * @example
+ * ```typescript
+ * import { analyze, exportToJson } from 'tdepend';
+ *
+ * const result = await analyze({ rootDir: 'src' });
+ * const json = exportToJson(result, { pretty: false }); // Compact JSON
+ * console.log(json);
+ * ```
+ */
+export declare function exportToJson(result: AnalysisResult, options?: ExportOptions): string;

package/dist/api/export.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exportToFile = exportToFile;
+exports.exportToJson = exportToJson;
+const promises_1 = require("fs/promises");
+const serialization_1 = require("./serialization");
+/**
+ * Exports analysis results to a JSON file.
+ *
+ * This function converts the analysis result to a serializable format
+ * (fixing Set serialization issues) and writes it to the specified file.
+ *
+ * @param result - The analysis result to export
+ * @param filePath - Path where the JSON file should be written
+ * @param options - Export options (pretty-printing, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { analyze, exportToFile } from 'tdepend';
+ *
+ * const result = await analyze({ rootDir: 'src' });
+ * await exportToFile(result, 'architecture-snapshot.json');
+ * ```
+ */
+async function exportToFile(result, filePath, options = {}) {
+    const json = exportToJson(result, options);
+    await (0, promises_1.writeFile)(filePath, json, 'utf-8');
+}
+/**
+ * Converts analysis results to a JSON string.
+ *
+ * This function converts the analysis result to a serializable format
+ * and returns it as a JSON string (does not write to file).
+ *
+ * @param result - The analysis result to export
+ * @param options - Export options (pretty-printing, etc.)
+ * @returns JSON string representation of the analysis result
+ *
+ * @example
+ * ```typescript
+ * import { analyze, exportToJson } from 'tdepend';
+ *
+ * const result = await analyze({ rootDir: 'src' });
+ * const json = exportToJson(result, { pretty: false }); // Compact JSON
+ * console.log(json);
+ * ```
+ */
+function exportToJson(result, options = {}) {
+    const serialized = (0, serialization_1.toSerializable)(result);
+    const indent = options.pretty !== false ? 2 : 0;
+    return JSON.stringify(serialized, null, indent);
+}
+//# sourceMappingURL=export.js.map

package/dist/api/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/api/export.ts"],"names":[],"mappings":";;AAiCA,oCAOC;AAqBD,oCAIC;AAjED,0CAAwC;AACxC,mDAAiD;AAcjD;;;;;;;;;;;;;;;;;GAiBG;AACI,KAAK,UAAU,YAAY,CAChC,MAAsB,EACtB,QAAgB,EAChB,UAAyB,EAAE;IAE3B,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,MAAM,IAAA,oBAAS,EAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,YAAY,CAAC,MAAsB,EAAE,UAAyB,EAAE;IAC9E,MAAM,UAAU,GAAG,IAAA,8BAAc,EAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/dist/api/serialization.d.ts

@@ -0,0 +1,28 @@
+import type { DependencyGraph } from '../graph/dependencyGraph';
+import type { AnalysisResult, SerializableAnalysisResult, SerializableDependencyGraph, SerializableCycle } from '../types/api';
+/**
+ * Converts a DependencyGraph with Sets to a serializable format with Arrays.
+ * @param graph - The dependency graph to serialize
+ * @returns Serializable graph with array-based relationships
+ */
+export declare function serializeGraph(graph: DependencyGraph): SerializableDependencyGraph;
+/**
+ * Normalizes a cycle for consistent identification across runs.
+ * Creates a unique ID based on the cycle's contents and rotates the cycle
+ * to start with the lexicographically smallest file path.
+ *
+ * @param cycle - Array of file paths forming a cycle
+ * @returns Normalized cycle with unique ID
+ */
+export declare function normalizeCycle(cycle: string[]): SerializableCycle;
+/**
+ * Converts an AnalysisResult with rich objects to a fully serializable format.
+ * This includes:
+ * - Converting Sets to Arrays in the dependency graph
+ * - Normalizing cycles with unique IDs
+ * - Adding version and timestamp metadata
+ *
+ * @param result - The analysis result to serialize
+ * @returns Fully serializable result ready for JSON.stringify
+ */
+export declare function toSerializable(result: AnalysisResult): SerializableAnalysisResult;