or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@commitlint/format

@commitlint/format is a TypeScript library that formats commitlint reports into human-readable output with colored text and symbols. It processes lint results containing errors and warnings from commit message validation, applying appropriate visual formatting including colored signs, bold text for emphasis, and structured summary information.

Package Information

Package Name: @commitlint/format
Package Type: npm
Language: TypeScript
Installation: npm install @commitlint/format

Core Imports

import format from "@commitlint/format";
import { format, formatResult } from "@commitlint/format";

For CommonJS:

const format = require("@commitlint/format");
const { format, formatResult } = require("@commitlint/format");

Basic Usage

import format from "@commitlint/format";

// Format a complete report
const report = {
  results: [
    {
      errors: [
        {
          level: 2,
          name: "type-empty",
          message: "type may not be empty"
        }
      ],
      warnings: [
        {
          level: 1,
          name: "subject-case",
          message: "subject must be in sentence-case"
        }
      ],
      input: "fix: resolve issue with validation"
    }
  ]
};

const formattedOutput = format(report, {
  color: true,
  verbose: true,
  helpUrl: "https://commitlint.js.org/"
});

console.log(formattedOutput);
// Output: colored formatted text with symbols and summary

Architecture

@commitlint/format follows a simple two-stage formatting pipeline:

Input Processing: For each result, formats the input commit message (when verbose or problems exist)
Result Formatting: Processes errors and warnings, applying appropriate colors, symbols, and generates summary lines

The library uses chalk for terminal colors and provides sensible defaults while allowing full customization of signs, colors, and verbosity levels.

Capabilities

Main Formatting Function

Formats complete commitlint reports into human-readable strings with colors and symbols.

/**
 * Format a commitlint report into a human-readable string
 * @param report - The commitlint report containing results
 * @param options - Formatting options for colors, symbols, and verbosity
 * @returns Formatted string output
 */
function format(
  report?: FormattableReport,
  options?: FormatOptions
): string;

Usage Example:

import format from "@commitlint/format";

const output = format({
  results: [
    {
      errors: [{ level: 2, name: "type-empty", message: "type may not be empty" }],
      input: "add new feature"
    }
  ]
}, {
  color: true,
  verbose: true,
  helpUrl: "https://commitlint.js.org/"
});

Individual Result Formatting

Formats a single result into an array of formatted strings for custom processing.

/**
 * Format a single result into an array of formatted strings
 * @param result - Individual result with errors and warnings
 * @param options - Formatting options for colors, symbols, and verbosity
 * @returns Array of formatted string lines
 */
function formatResult(
  result?: FormattableResult,
  options?: FormatOptions
): string[];

Usage Example:

import { formatResult } from "@commitlint/format";

const lines = formatResult({
  errors: [{ level: 2, name: "type-empty", message: "type may not be empty" }],
  warnings: [{ level: 1, name: "subject-case", message: "subject must be lowercase" }]
}, {
  color: false,
  signs: ["INFO", "WARN", "ERROR"]
});

// lines contains formatted text lines without colors

Types

Core Interfaces

interface FormattableReport {
  results?: (FormattableResult & WithInput)[];
}

interface FormattableResult {
  errors?: FormattableProblem[];
  warnings?: FormattableProblem[];
}

interface FormattableProblem {
  level: RuleConfigSeverity;
  name: keyof QualifiedRules;
  message: string;
}

// QualifiedRules represents the commitlint rule configuration
type QualifiedRules = Partial<RulesConfig<RuleConfigQuality.Qualified>>;

interface WithInput {
  input?: string;
}

Configuration Options

interface FormatOptions {
  /** Enable/disable colored output (default: true) */
  color?: boolean;
  /** Custom signs for different severity levels (default: [" ", "⚠", "✖"]) */
  signs?: readonly [string, string, string];
  /** Custom colors for different severity levels (default: ["white", "yellow", "red"]) */
  colors?: readonly [ChalkColor, ChalkColor, ChalkColor];
  /** Show verbose output including successful results (default: false) */
  verbose?: boolean;
  /** Help URL to display when problems are found */
  helpUrl?: string;
}

type ChalkColor = ColorName | ModifierName;

Severity Types

enum RuleConfigSeverity {
  Disabled = 0,
  Warning = 1,
  Error = 2
}
// 0 = disabled, 1 = warning, 2 = error

Default Configuration

The library uses these default settings:

Signs: [" ", "⚠", "✖"] for disabled/warning/error levels
Colors: ["white", "yellow", "red"] for disabled/warning/error levels
Color: true (colored output enabled)
Verbose: false (only show problems, not successes)

Error Handling

The functions are designed to handle missing or malformed data gracefully:

Empty or undefined reports return empty strings
Missing errors/warnings arrays are treated as empty
Invalid severity levels fall back to default signs/colors
Functions never throw exceptions for malformed input

Output Format

The formatted output includes:

Input line (when verbose or problems exist): Shows the commit message being validated
Problem lines: Each error/warning with appropriate symbol, message, and rule name
Summary line: Count of problems and warnings with appropriate symbol and color
Help line (when problems exist and helpUrl provided): Link to documentation

Example output:

⧗   input: add new feature
✖   type may not be empty [type-empty]
⚠   subject must be lowercase [subject-case]

✖   found 1 problems, 1 warnings
ⓘ   Get help: https://commitlint.js.org/