Output Formatting

/**
 * Formats cruise result with the given reporter and options
 * @param result - Result from cruise function adhering to cruise result schema
 * @param formatOptions - Options controlling output format and filtering
 * @returns Promise resolving to formatted output with exit code
 */
function format(
  result: ICruiseResult,
  formatOptions: IFormatOptions
): Promise<IReporterOutput>;

import { cruise, format } from "dependency-cruiser";

// Get analysis results
const cruiseResult = await cruise(["src"]);

// Format as HTML report
const htmlReport = await format(cruiseResult.output, {
  outputType: "html"
});

// Format as DOT graph with filtering
const dotGraph = await format(cruiseResult.output, {
  outputType: "dot",
  exclude: "node_modules",
  collapse: 2
});

// Format as error report with focus
const errorReport = await format(cruiseResult.output, {
  outputType: "err-long",
  focus: "src/main"
});

// Format as Mermaid diagram
const mermaidDiagram = await format(cruiseResult.output, {
  outputType: "mermaid",
  includeOnly: "^src/"
});

interface IFormatOptions {
  /** Output format type */
  outputType?: OutputType;
  
  /** Regular expression or conditions describing which dependencies to exclude */
  exclude?: string | string[] | IExcludeType;
  
  /** Regular expression describing which dependencies to include (others filtered out) */
  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;
  
  /** Collapse modules to folder depth or pattern */
  collapse?: string | number;
  
  /** Prefix to insert before links in dot/svg output */
  prefix?: string;
}

type OutputType = 
  // Structured data formats
  | "json"        // Raw JSON data
  | "csv"         // Comma-separated values
  | "baseline"    // Known violations baseline
  
  // Human-readable reports  
  | "html"        // Interactive HTML report
  | "text"        // Plain text summary
  | "markdown"    // Markdown formatted report
  | "metrics"     // Stability and coupling metrics
  
  // Error reports
  | "err"         // Concise error report
  | "err-long"    // Detailed error report  
  | "err-html"    // HTML error report
  
  // Visual diagrams
  | "dot"         // GraphViz dot format
  | "cdot"        // Compact dot format
  | "ddot"        // Directory-level dot format
  | "fdot"        // Folder-level dot format
  | "flat"        // Flat dependency list
  | "archi"       // Architecture-level diagram
  | "mermaid"     // Mermaid diagram format
  | "d2"          // D2 diagram format
  
  // CI/CD integration
  | "teamcity"    // TeamCity service messages
  | "anon"        // Anonymized output for sharing
  | "null"        // No output (exit code only)
  
  // Plugin formats
  | string;       // Custom plugin format (e.g., "plugin:stats-reporter-plugin.js")

interface IExcludeType {
  /** Path pattern to exclude */
  path?: string;
  
  /** Dependency types to exclude */
  dependencyTypes?: DependencyType[];
  
  /** Whether to exclude dynamic dependencies */
  dynamic?: boolean;
  
  /** Whether to exclude modules that could not be resolved */
  couldNotResolve?: boolean;
  
  /** Whether to exclude core modules */
  coreModule?: boolean;
  
  /** Whether to exclude orphaned modules */
  orphan?: boolean;
}

interface IIncludeOnlyType {
  /** Path pattern to include */
  path?: string;
  
  /** Dependency types to include */
  dependencyTypes?: DependencyType[];
  
  /** Whether to include only dynamic dependencies */
  dynamic?: boolean;
  
  /** Whether to include only modules that could not be resolved */
  couldNotResolve?: boolean;
  
  /** Whether to include only core modules */
  coreModule?: boolean;
  
  /** Whether to include only orphaned modules */
  orphan?: boolean;
}

interface IFocusType {
  /** Path pattern for modules to focus on */
  path?: string;
  
  /** Dependency types to focus on */
  dependencyTypes?: DependencyType[];
}

interface IReachesType {
  /** Path pattern for modules to show reachability for */
  path?: string;
  
  /** Dependency types for reachability analysis */
  dependencyTypes?: DependencyType[];
}

const htmlReport = await format(cruiseResult.output, {
  outputType: "html",
  // Optional: add prefix for source links
  prefix: "https://github.com/your-org/your-repo/blob/main/"
});

// Write to file
import fs from "fs/promises";
await fs.writeFile("dependency-report.html", htmlReport.output);

// Standard dot format - full detail
const dotGraph = await format(result, { outputType: "dot" });

// Compact dot format - reduced visual noise  
const compactDot = await format(result, { outputType: "cdot" });

// Directory-level dot - folders instead of files
const directoryDot = await format(result, { outputType: "ddot" });

// Folder-level dot - high-level folder dependencies
const folderDot = await format(result, { outputType: "fdot" });

// Architecture-level - shows major components
const archiDot = await format(result, { outputType: "archi" });

const mermaidDiagram = await format(result, {
  outputType: "mermaid",
  collapse: 2  // Collapse to folder level 2
});

// Result can be embedded in markdown:
// ```mermaid
// ${mermaidDiagram.output}
// ```

// Concise error list
const errors = await format(result, { outputType: "err" });

// Detailed error report with context
const detailedErrors = await format(result, { outputType: "err-long" });

// HTML error report with interactive features
const htmlErrors = await format(result, { outputType: "err-html" });

// TeamCity integration format
const teamcityOutput = await format(result, { outputType: "teamcity" });

// Stability and coupling metrics
const metricsReport = await format(result, { outputType: "metrics" });

// JSON data for custom processing
const jsonData = await format(result, { outputType: "json" });

// CSV for spreadsheet analysis
const csvData = await format(result, { outputType: "csv" });

// Markdown report for documentation
const markdownReport = await format(result, { outputType: "markdown" });

// Focus on specific module and its dependencies
const focusedView = await format(result, {
  outputType: "html",
  focus: "src/core/engine",
  exclude: ["test", "node_modules"]
});

// Show what reaches problematic modules
const reachabilityView = await format(result, {
  outputType: "dot",
  reaches: "src/legacy",
  includeOnly: "^src/"
});

// Architectural overview with collapsed folders
const architecturalView = await format(result, {
  outputType: "archi",
  collapse: "^src/[^/]+/",
  exclude: { dependencyTypes: ["npm-dev", "npm-optional"] }
});

// Error report for specific dependency types
const typeErrors = await format(result, {
  outputType: "err-long",
  includeOnly: { dependencyTypes: ["core", "npm"] }
});

// Custom plugin format
const customOutput = await format(result, {
  outputType: "plugin:my-custom-reporter.js"
});

// Built-in plugin examples
const statsOutput = await format(result, {
  outputType: "plugin:stats-reporter-plugin.js"
});