codereportcard

A zero-config code quality report card for React / JS / TS projects. Scans your codebase across 5 categories, scores each 0–100, and gives you an actionable health score — with an optional AI roast.

No remote server. No account. Runs entirely on your machine.

Table of Contents

• codereportcard
  • Table of Contents
  • Quick Start
  • Usage
  • Configuration
  • CI/CD Integration
  • Git Integration
  • What It Checks
  • Scoring
  • Contributing
    • Project Structure
    • Adding a New Rule
    • Reporting Bugs / Requesting Features
  • License

Quick Start

# No install needed
npx codereportcard .

Or install globally:

npm install -g codereportcard
codereportcard ./my-project

Usage

# Scan current directory
codereportcard .

# Scan a specific project
codereportcard ./path/to/project

# JSON output (for CI/CD)
codereportcard . --json

# Per-file issue breakdown
codereportcard . --verbose

# Export a shareable PNG report card
codereportcard . --share

# Custom PNG output path
codereportcard . --share --output report.png

# Disable the summary roast
codereportcard . --no-roast

# CI mode — fail if score is below threshold
codereportcard . --fail-under 80

# Only scan files changed vs a branch
codereportcard . --diff main

# Only scan staged files (pre-commit hook)
codereportcard . --staged

# Generate a config file
codereportcard init

# Auto-fix (coming soon)
codereportcard . --fix

Configuration

Run codereportcard init to scaffold a default config, or create one manually.

Supported config files (searched in order):

1. codereportcard.config.js / codereportcard.config.mjs
2. .codereportcardrc.json
3. "codereportcard" key in package.json

// codereportcard.config.js
export default {
    // Additional glob patterns to exclude
    exclude: ['**/generated/**', '**/migrations/**'],

    // Per-rule overrides
    rules: {
        'file-too-long': { limit: 400, severity: 'warning' },
        'high-complexity': { limit: 15, severity: 'error' },
    },

    // Per-category minimum score thresholds (CI fails if below)
    thresholds: {
        secretLeakage: 100,
        clarity: 80,
    },

    // Overall score threshold — exit code 1 if below
    failUnder: 70,

    // Category weight overrides (auto-normalized to sum to 1.0)
    weights: {
        clarity: 0.25,
        duplication: 0.15,
        deadCode: 0.20,
        secretLeakage: 0.25,
        aiSlop: 0.15,
    },
};

CI/CD Integration

Use --fail-under to enforce a minimum score in your pipeline:

# .github/workflows/code-quality.yml
name: Code Quality

on: [push, pull_request]

jobs:
  report-card:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Run Code Report Card
        run: npx codereportcard . --fail-under 75 --json

The CLI exits with code 1 if:

• The overall score is below --fail-under (or failUnder in config)
• Any category score is below its configured thresholds value

Git Integration

# Only check files changed in your feature branch
codereportcard . --diff main

# Pre-commit hook — only check staged files
codereportcard . --staged

Works great with husky:

# .husky/pre-commit
npx codereportcard . --staged --fail-under 70

What It Checks

| Category | Rules | |---|---| | Clarity | Cyclomatic complexity, file length, nested JSX depth, single-letter variables | | Duplication | Copy-pasted code blocks (10+ lines), duplicate useEffect bodies | | Dead Code | Unused imports, unused exports, unused variables | | Secrets | API keys, passwords, JWT tokens, .env files not in .gitignore | | AI Slop | Bloated useEffect deps, 80+ line functions, TODO clusters, console.log spam, prop drilling, comment-heavy files |

Scoring

Each category is weighted equally at 20% by default (configurable via weights). Diagnostics are scored by severity — errors weigh more than warnings.

| Grade | Score | Label | |---|---|---| | A+ | 97–100 | Immaculate | | A | 93–96 | Excellent | | A- | 90–92 | Very clean | | B+ | 87–89 | Solid | | B | 83–86 | Good | | B- | 80–82 | Decent | | C+ | 77–79 | Fair | | C | 73–76 | Needs work | | C- | 70–72 | Below average | | D+ | 67–69 | Poor | | D | 63–66 | Bad | | D- | 60–62 | Very bad | | F | 0–59 | Critical |

Contributing

Contributions are welcome! Here's how to get started:

# 1. Fork the repo and clone it
git clone https://github.com/AshutoshMore142k4/codereportcard.git
cd codereportcard

# 2. Install dependencies
npm install

# 3. Run in dev mode against the current directory
npm run dev

# 4. Run tests
npm test

# 5. Build
npm run build

Project Structure

src/
├── cli.ts              # CLI entry point (commander)
├── walker.ts           # File discovery + Babel parsing
├── scorer.ts           # Scoring engine + grade mapping
├── reporter.ts         # Terminal output renderer
├── roaster.ts          # Roast generator
├── exporter.ts         # PNG export (--share)
├── git.ts              # --diff / --staged helpers
├── config.ts           # Config file loader
├── types.ts            # Shared TypeScript types
├── rules/
│   ├── clarity.ts      # Complexity, file length, JSX depth
│   ├── duplication.ts  # Code block duplication
│   ├── deadCode.ts     # Unused imports/exports/vars
│   ├── secretLeakage.ts # Secret/key detection
│   └── aiSlop.ts       # AI-generated code patterns
└── utils/
    └── babel.ts        # Babel traverse helper

Adding a New Rule

1. Add detection logic to the relevant file in src/rules/
2. Export the new Issue objects from the category's analyze* function
3. Add a roast template to src/roaster.ts
4. Add the rule to the What It Checks table in this README
5. Open a pull request

Reporting Bugs / Requesting Features

• Open an issue
• Please include your Node.js version, OS, and the output of the failing scan

License

MIT © Ashutosh More