Formatters

Formatters transform lint results into human-readable or machine-parseable output.

Built-in Formatters

stylish

Human-readable output with colors. Best for terminal display.

CLAUDE.md (1 error, 1 warning)
  10  error    File exceeds 40KB limit                  claude-md-size
  25  warning  Missing examples section                 claude-md-content-too-many-sections

skills/test/SKILL.md (1 error)
   5  error    Missing description field                skill-description

3 problems (2 errors, 1 warning)

Features: color-coded severity, grouped by file, line numbers, rule IDs, summary totals.

json

Machine-parseable JSON output. Best for programmatic consumption and CI/CD artifacts.

[
  {
    "filePath": "CLAUDE.md",
    "messages": [
      {
        "ruleId": "claude-md-size",
        "severity": "error",
        "message": "File exceeds 40KB limit",
        "line": 10
      }
    ],
    "errorCount": 1,
    "warningCount": 0,
    "fixableErrorCount": 0,
    "fixableWarningCount": 0
  }
]

compact

One violation per line. Best for grep-able output and log files.

CLAUDE.md: line 10, error - File exceeds 40KB limit (claude-md-size)
CLAUDE.md: line 25, warning - Missing examples section (claude-md-content-too-many-sections)
skills/test/SKILL.md: line 5, error - Missing description field (skill-description)

sarif

SARIF (Static Analysis Results Interchange Format) output. Best for GitHub Code Scanning, VS Code SARIF Viewer, and other SARIF-compatible tools.

See the SARIF Integration Guide for setup instructions.

github

GitHub Actions workflow command format. Produces ::error and ::warning annotations that appear inline on PR diffs.

::error file=CLAUDE.md,line=12,title=claude-md-size::File exceeds 40KB limit (66669 bytes)
::warning file=.claude/skills/deploy/SKILL.md,line=5,title=skill-description::Missing description field

Lightweight alternative to SARIF — no upload step, no security-events permission needed. Use github for quick annotations; use sarif when you need Code Scanning integration and persistent results.

See the CI/CD Integration Guide for workflow setup.

Loading Formatters

Class API

const linter = new ClaudeLint();
const results = await linter.lintFiles(['**/*.md']);

const formatter = await linter.loadFormatter('stylish');
console.log(formatter.format(results));

Functional API

import { lint, formatResults } from 'claude-code-lint';

const results = await lint(['**/*.md']);
const output = await formatResults(results, 'json');

Custom Formatters

Custom formatters must implement the Formatter interface:

interface Formatter {
  format(results: LintResult[]): string;
}

You can also extend BaseFormatter for access to getRelativePath() and getSummary() helpers.

Basic Example

// formatters/summary.ts
import type { Formatter, LintResult } from 'claude-code-lint';

const summaryFormatter: Formatter = {
  format(results: LintResult[]): string {
    const totalErrors = results.reduce((sum, r) => sum + r.errorCount, 0);
    const totalWarnings = results.reduce((sum, r) => sum + r.warningCount, 0);
    return `${results.length} files checked: ${totalErrors} errors, ${totalWarnings} warnings`;
  }
};

export default summaryFormatter;

Load a custom formatter by path:

// Class API
const formatter = await linter.loadFormatter('./formatters/summary.ts');

// Functional API
const output = await formatResults(results, './formatters/summary.ts');

For more custom formatter examples (Markdown report, group-by-rule), see Recipes.

Choosing a Formatter

Use Case	Formatter
Terminal display	stylish
CI/CD artifacts	json or sarif
GitHub Code Scanning	sarif
GitHub Actions PR annotations	github
Log files	compact
Programmatic parsing	json
Custom reporting	Create a custom formatter

See Also

• ClaudeLint Class - loadFormatter() method
• Functional API - formatResults() function
• Types - Formatter, BaseFormatter, FormatterOptions types
• Recipes - Custom formatter examples