Reporters

Output formats for analysis results.

Available Formats

Format	Flag	Use Case
Console	`--format console`	Human-readable terminal output
JSON	`--format json`	Programmatic access, APIs
SARIF	`--format sarif`	GitHub Security, CI/CD
HTML	`--format html`	Reports, sharing
CSV	`--format csv`	Spreadsheets, data analysis

Console (Default)

Human-readable output with colors and formatting.

capyseo analyze ./dist
# or
capyseo analyze ./dist --format console

Output:

📊 SEO Analysis Results

/index.html (Score: 85/100)
├── [x] [meta-description] Missing meta description
│       Add <meta name="description" content="...">
├── [!] [image-alt] Image missing alt: hero.jpg
│       Add descriptive alt text for accessibility
└── [i] [heading-keywords] Consider adding keywords to H1

/about.html (Score: 92/100)
└── [!] [open-graph] Missing og:image

Summary:
  Pages analyzed: 2
  Average score: 88.5/100
  Errors: 1 | Warnings: 2 | Info: 1

Severity Icons

Icon	Severity
`[x]`	Error
`[!]`	Warning
`[i]`	Info

Options

# Quiet mode (minimal output)
capyseo analyze ./dist --quiet

# Verbose mode (detailed output)
capyseo analyze ./dist --verbose

# No colors
capyseo analyze ./dist --no-color

JSON

Machine-readable JSON output.

capyseo analyze ./dist --format json
capyseo analyze ./dist --format json -o report.json

Output:

{
  "score": 85,
  "pages": [
    {
      "url": "/index.html",
      "score": 85,
      "issues": [
        {
          "ruleId": "meta-description",
          "message": "Missing meta description",
          "severity": "error",
          "suggestion": "Add <meta name=\"description\" content=\"...\">"
        }
      ]
    }
  ],
  "summary": {
    "totalPages": 1,
    "averageScore": 85,
    "errors": 1,
    "warnings": 0,
    "info": 0
  },
  "metadata": {
    "version": "1.0.0",
    "timestamp": "2024-01-15T10:30:00Z",
    "config": {}
  }
}

Schema

interface AnalysisResult {
  score: number;
  pages: PageResult[];
  summary: Summary;
  metadata: Metadata;
}

interface PageResult {
  url: string;
  score: number;
  issues: Issue[];
}

interface Issue {
  ruleId: string;
  message: string;
  severity: 'error' | 'warning' | 'info';
  suggestion?: string;
  selector?: string;
  context?: Record<string, unknown>;
}

interface Summary {
  totalPages: number;
  averageScore: number;
  errors: number;
  warnings: number;
  info: number;
}

Usage in Scripts

# Extract score
capyseo analyze ./dist --format json | jq '.score'

# Count errors
capyseo analyze ./dist --format json | jq '.summary.errors'

# List pages below threshold
capyseo analyze ./dist --format json | jq '.pages[] | select(.score < 80)'

SARIF

Static Analysis Results Interchange Format for CI/CD integration.

capyseo analyze ./dist --format sarif -o seo-report.sarif

Output:

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Capyseo",
          "version": "1.0.0",
          "rules": [
            {
              "id": "meta-description",
              "name": "Meta Description",
              "shortDescription": {
                "text": "Page should have a meta description"
              }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "meta-description",
          "level": "error",
          "message": {
            "text": "Missing meta description"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {
                  "uri": "index.html"
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

GitHub Integration

Upload to GitHub Security tab:

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: seo-report.sarif

SARIF Viewers

GitHub Security tab
VS Code SARIF Viewer extension
JFrog Xray
SonarQube

HTML

Interactive HTML report for sharing.

capyseo analyze ./dist --format html -o report.html

Features:

Sortable tables
Filterable by severity
Expandable details
Score charts
Print-friendly

Customization

// capyseo.config.js
export default {
  reporters: {
    html: {
      title: 'My Site SEO Report',
      showAI: true,
      theme: 'light', // 'light' | 'dark'
    },
  },
};

Serving

# Generate and serve
capyseo analyze ./dist --format html -o report.html
python -m http.server 8000

# Open in browser
open http://localhost:8000/report.html

CSV

Spreadsheet-compatible format for data analysis.

capyseo analyze ./dist --format csv -o report.csv

Output:

url,rule,severity,message,suggestion
/index.html,meta-description,error,Missing meta description,Add <meta name="description">
/index.html,image-alt,warning,Image missing alt: hero.jpg,Add alt text
/about.html,open-graph,warning,Missing og:image,Add Open Graph image

Columns

Column	Description
`url`	Page URL or path
`rule`	Rule ID
`severity`	error/warning/info
`message`	Issue description
`suggestion`	How to fix

Import to Spreadsheet

Open in Excel/Google Sheets
Filter by severity
Sort by page
Create pivot tables

Analysis

# Count issues per page
capyseo analyze ./dist --format csv | cut -d, -f1 | sort | uniq -c

# Count issues per rule
capyseo analyze ./dist --format csv | cut -d, -f2 | sort | uniq -c

Multiple Outputs

Generate multiple formats at once:

# Console + JSON
capyseo analyze ./dist | tee >(jq . > report.json)

# All formats
capyseo analyze ./dist --format json -o report.json && \
capyseo analyze ./dist --format sarif -o report.sarif && \
capyseo analyze ./dist --format html -o report.html

Custom Reporters

Create custom reporters programmatically:

import { SEOAnalyzer } from '@capyseo/core';

const analyzer = new SEOAnalyzer();
const results = await analyzer.analyze('./dist');

// Custom format
const custom = results.pages.map(page => ({
  page: page.url,
  grade: getGrade(page.score),
  critical: page.issues.filter(i => i.severity === 'error').length,
}));

console.log(JSON.stringify(custom, null, 2));

function getGrade(score: number): string {
  if (score >= 90) return 'A';
  if (score >= 80) return 'B';
  if (score >= 70) return 'C';
  if (score >= 60) return 'D';
  return 'F';
}

Reporter Comparison

Feature	Console	JSON	SARIF	HTML	CSV
Human-readable	✅	❌	❌	✅	⚠️
Machine-readable	❌	✅	✅	❌	✅
CI Integration	⚠️	✅	✅	❌	⚠️
Shareable	❌	⚠️	❌	✅	✅
GitHub Security	❌	❌	✅	❌	❌
Spreadsheet	❌	❌	❌	❌	✅

Best Practices

Development: Use console (default)
CI/CD: Use sarif for GitHub, json otherwise
Sharing: Use html for stakeholders
Analysis: Use csv for data exploration
APIs: Use json for programmatic access

Output Examples

Console (Quiet)

capyseo analyze ./dist --quiet

Score: 85/100 | Errors: 1 | Warnings: 2 | Info: 1

Console (Verbose)

capyseo analyze ./dist --verbose

Analyzing: /index.html
  Running rule: meta-title... ✓
  Running rule: meta-description... ✗ (error)
  Running rule: image-alt... ✗ (warning)
  ...

JSON (Pretty)

capyseo analyze ./dist --format json | jq .

JSON (Compact)

capyseo analyze ./dist --format json | jq -c .