Output Formatting

/**
 * Format lint results for console output
 * @param report - Validation results to format
 * @param options - Formatting options for customization
 * @returns Formatted string ready for console output
 */
function format(
  report?: FormattableReport,
  options?: FormatOptions
): string;

interface FormatOptions {
  /** Enable colored output (default: true) */
  color?: boolean;
  /** Custom signs for different severity levels [input, warning, error] */
  signs?: readonly [string, string, string];
  /** Custom colors for different severity levels [input, warning, error] */
  colors?: readonly [ChalkColor, ChalkColor, ChalkColor];
  /** Enable verbose output showing valid commits (default: false) */
  verbose?: boolean;
  /** Help URL to include in error messages */
  helpUrl?: string;
}

interface FormattableReport {
  /** Array of validation results for individual commits */
  results?: (FormattableResult & WithInput)[];
  /** Overall validation status */
  valid?: boolean;
  /** Total number of errors across all results */
  errorCount?: number;
  /** Total number of warnings across all results */
  warningCount?: number;
}

interface FormattableResult {
  /** Individual validation result for a commit */
  valid: boolean;
  /** Error-level rule violations */
  errors: FormattableRuleOutcome[];
  /** Warning-level rule violations */
  warnings: FormattableRuleOutcome[];
}

interface WithInput {
  /** Original commit message that was validated */
  input: string;
}

interface FormattableRuleOutcome {
  /** Severity level of the rule violation */
  level: RuleConfigSeverity;
  /** Name of the rule that failed */
  name: string;
  /** Human-readable description of the violation */
  message: string;
  /** Whether the rule passed validation */
  valid: boolean;
}

type ChalkColor = 
  | "black" | "red" | "green" | "yellow" | "blue" 
  | "magenta" | "cyan" | "white" | "gray" | "grey"
  | "blackBright" | "redBright" | "greenBright" 
  | "yellowBright" | "blueBright" | "magentaBright" 
  | "cyanBright" | "whiteBright";

// Default color scheme
const defaultColors: readonly [ChalkColor, ChalkColor, ChalkColor] = [
  "gray",    // Input/valid commits
  "yellow",  // Warnings  
  "red"      // Errors
];

// Default signs
const defaultSigns: readonly [string, string, string] = [
  "⊢",  // Input/valid commits
  "⚠",  // Warnings
  "✖"   // Errors
];

✖   subject-case: 
    Subject must not have case:
    • sentence-case
    • start-case  
    • pascal-case
    • upper-case
✖   type-enum:
    type must be one of [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test]

✖   found 2 problems, 0 warnings
ⓘ   Get help: https://github.com/conventional-changelog/commitlint/#what-is-commitlint

⊢   type-enum ✔
⊢   type-case ✔
⊢   type-empty ✔
⊢   scope-case ✔
⊢   subject-case ✔
⊢   subject-empty ✔
⊢   subject-full-stop ✔
⊢   header-max-length ✔

✔   found 0 problems, 0 warnings

⚠   body-max-line-length:
    body's lines must not be longer than 100 characters

⚠   found 0 problems, 1 warnings

import format from "@commitlint/format";

const report = {
  valid: false,
  errorCount: 2,
  warningCount: 1,
  results: [{
    input: "Fix: Add new feature",
    valid: false,
    errors: [
      {
        level: 2,
        name: "subject-case",
        message: "Subject must not have case 'sentence-case'",
        valid: false
      },
      {
        level: 2,
        name: "type-case", 
        message: "Type must be lower-case",
        valid: false
      }
    ],
    warnings: [
      {
        level: 1,
        name: "body-max-length",
        message: "Body exceeds maximum length",
        valid: false
      }
    ]
  }]
};

const output = format(report);
console.log(output);

import format from "@commitlint/format";

const customOptions = {
  color: true,
  signs: ["→", "!", "×"] as const,
  colors: ["blue", "orange", "red"] as const,
  verbose: false
};

const output = format(report, customOptions);
console.log(output);

import format from "@commitlint/format";

const validReport = {
  valid: true,
  errorCount: 0,
  warningCount: 0,
  results: [{
    input: "feat: add user authentication",
    valid: true,
    errors: [],
    warnings: []
  }]
};

// Verbose mode shows successful rule checks
const verboseOutput = format(validReport, { verbose: true });
console.log(verboseOutput);

import format from "@commitlint/format";

const output = format(report, {
  helpUrl: "https://mycompany.com/commit-guidelines"
});

// Output will include custom help URL at the bottom
console.log(output);

import format from "@commitlint/format";

// For CI environments or plain text output
const plainOutput = format(report, { color: false });
console.log(plainOutput);

import { load } from "@commitlint/load";
import lint from "@commitlint/lint";
import format from "@commitlint/format";

async function validateAndFormat(message: string, options = {}) {
  // Load configuration
  const config = await load();
  
  // Lint message
  const result = await lint(message, config.rules);
  
  // Create report structure
  const report = {
    valid: result.valid,
    errorCount: result.errors.length,
    warningCount: result.warnings.length,
    results: [{
      input: result.input,
      valid: result.valid,
      errors: result.errors,
      warnings: result.warnings
    }]
  };
  
  // Format output
  const output = format(report, {
    color: options.color ?? true,
    verbose: options.verbose ?? false,
    helpUrl: config.helpUrl
  });
  
  return output;
}

// Usage
const formatted = await validateAndFormat("Fix: add feature", {
  color: true,
  verbose: false
});
console.log(formatted);

// Custom formatter function
function customFormat(report, options = {}) {
  const { color = true, verbose = false } = options;
  
  if (!report.results) return "";
  
  let output = "";
  
  for (const result of report.results) {
    if (!result.valid) {
      output += `❌ Commit: ${result.input}\n`;
      
      result.errors.forEach(error => {
        output += `   • ${error.name}: ${error.message}\n`;
      });
      
      result.warnings.forEach(warning => {
        output += `   ⚠ ${warning.name}: ${warning.message}\n`;
      });
    } else if (verbose) {
      output += `✅ Commit: ${result.input}\n`;
    }
  }
  
  // Summary
  if (report.errorCount > 0 || report.warningCount > 0) {
    output += `\nSummary: ${report.errorCount} errors, ${report.warningCount} warnings\n`;
  }
  
  return output;
}

// Use custom formatter
const customOutput = customFormat(report, { verbose: true });

// Create JSON formatter for CI integration
function jsonFormat(report) {
  return JSON.stringify({
    valid: report.valid,
    errorCount: report.errorCount,
    warningCount: report.warningCount,
    results: report.results?.map(result => ({
      input: result.input,
      valid: result.valid,
      issues: [
        ...result.errors.map(e => ({ ...e, severity: 'error' })),
        ...result.warnings.map(w => ({ ...w, severity: 'warning' }))
      ]
    })) || []
  }, null, 2);
}

// Usage for CI/CD pipelines
const jsonOutput = jsonFormat(report);
console.log(jsonOutput);

import format from "@commitlint/format";

function smartFormat(report, isCI = false, isTTY = true) {
  const options = {
    color: !isCI && isTTY,  // Colors only in interactive terminals
    verbose: !isCI,         // Verbose only outside CI
    helpUrl: isCI ? undefined : "https://docs.company.com/commits"
  };
  
  return format(report, options);
}

// Usage
const ciOutput = smartFormat(report, process.env.CI, process.stdout.isTTY);
console.log(ciOutput);