stock-bot/tools/coverage-cli/README.md

Stock Bot Coverage CLI

A custom coverage tool for the Stock Bot monorepo that provides advanced coverage reporting with support for excluding directories (like dist/) and beautiful reporting options.

Features

• 🚫 Exclusion Support: Exclude directories like dist/, node_modules/, and test files from coverage
• 📊 Multiple Reporters: Terminal, HTML, JSON, and Markdown reports
• 🎯 Threshold Enforcement: Set and enforce coverage thresholds
• 📦 Monorepo Support: Works seamlessly with workspace packages
• 🎨 Beautiful Reports: Interactive HTML reports and colored terminal output
• 🔧 Configurable: Use .coveragerc.json or CLI flags

Installation

The tool is already part of the Stock Bot monorepo. Just run:

bun install

Usage

Basic Usage

Run coverage for all packages:

bun run coverage

Generate HTML Report

bun run coverage:html

CI Mode

Generate markdown and JSON reports, fail if below threshold:

bun run coverage:ci

Run for Specific Packages

bun run coverage --packages core utils

Custom Exclusions

bun run coverage --exclude "**/dist/**" "**/generated/**" "**/vendor/**"

Set Thresholds

bun run coverage --threshold 85 --threshold-functions 80

Configuration

Create a .coveragerc.json file in your project root:

{
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/coverage/**",
    "**/*.test.ts",
    "**/*.test.js",
    "**/test/**",
    "**/tests/**"
  ],
  "reporters": ["terminal", "html"],
  "thresholds": {
    "lines": 80,
    "functions": 80,
    "branches": 80,
    "statements": 80
  },
  "outputDir": "coverage"
}

Or create one with:

bun run coverage init

Reporters

Terminal Reporter

Beautiful colored output in your terminal:

═══════════════════════════════════════════════════════════
          Stock Bot Coverage Report
═══════════════════════════════════════════════════════════

┌────────────────┬──────────┬──────────┬──────────┬────────────┐
│ Package        │ Lines    │ Functions│ Branches │ Statements │
├────────────────┼──────────┼──────────┼──────────┼────────────┤
│ @stock-bot/core│ 85.3% ✓  │ 82.1% ✓  │ 79.2% ⚠  │ 84.7% ✓    │
│ @stock-bot/utils│ 92.1% ✓  │ 90.5% ✓  │ 88.3% ✓  │ 91.8% ✓    │
├────────────────┼──────────┼──────────┼──────────┼────────────┤
│ Overall        │ 88.7% ✓  │ 86.3% ✓  │ 83.8% ✓  │ 88.3% ✓    │
└────────────────┴──────────┴──────────┴──────────┴────────────┘

✓ 15 packages meet coverage thresholds
⚠ 2 packages below threshold

HTML Reporter

Interactive HTML report with:

• Package breakdown
• File-level coverage
• Beautiful charts and visualizations
• Responsive design

Markdown Reporter

Perfect for CI/CD comments on pull requests:

• Summary tables
• Package details
• Threshold status
• File breakdowns

JSON Reporter

Machine-readable format for:

• Custom tooling integration
• Historical tracking
• CI/CD pipelines

CLI Options

Option	Description
-p, --packages <packages...>	Run coverage for specific packages
-e, --exclude <patterns...>	Glob patterns to exclude from coverage
-i, --include <patterns...>	Glob patterns to include in coverage
-r, --reporters <reporters...>	Coverage reporters to use
-t, --threshold <number>	Set coverage threshold for all metrics
--threshold-lines <number>	Set line coverage threshold
--threshold-functions <number>	Set function coverage threshold
--threshold-branches <number>	Set branch coverage threshold
--threshold-statements <number>	Set statement coverage threshold
-o, --output-dir <path>	Output directory for reports
-c, --config <path>	Path to coverage config file
--fail-under	Exit with non-zero code if below threshold

How It Works

1. Test Execution: Runs bun test for each package
2. Data Collection: Currently simulates coverage data based on test results (Bun's coverage feature is not yet fully implemented)
3. Filtering: Applies exclusion patterns to remove unwanted files
4. Processing: Merges coverage data across packages
5. Reporting: Generates reports in requested formats

Note

: This tool currently generates simulated coverage data based on test results because Bun's --coverage flag doesn't yet produce LCOV output. Once Bun's coverage feature is fully implemented, the tool will be updated to use actual coverage data.

Why This Tool?

Bun's built-in coverage tool lacks several features needed for large monorepos:

• No way to exclude directories like dist/
• Limited reporting options
• No per-package thresholds
• Basic terminal output

This tool addresses these limitations while maintaining compatibility with Bun's test runner.

Contributing

The coverage tool is located in tools/coverage-cli/. To work on it:

1. Make changes in tools/coverage-cli/src/
2. Test with bun run coverage
3. Build with bun build tools/coverage-cli/src/index.ts

License

Part of the Stock Bot Trading Platform - MIT License