# @coderefine/cli

React & Next.js tech debt scanner. Find code quality issues, get a health score, and track improvements over time.

## Quick Start

```bash
npx @coderefine/cli scan
```

## Features

- **Framework Detection** — Automatically detects React, Next.js (pages/app router)
- **Health Score** — 0-100 score based on code quality findings
- **Offline First** — Runs entirely locally, no network required
- **Multiple Outputs** — JSON, SARIF, or human-readable console

## Usage

### Basic Scan

```bash
# Scan current directory
npx @coderefine/cli scan

# Scan specific directory
npx @coderefine/cli scan --root ./my-project

# Output to console (human-readable)
npx @coderefine/cli scan -f console

# Save report to file
npx @coderefine/cli scan -o report.json
```

### CI Mode

```bash
# Exit with code 1 if any warnings or errors found
npx @coderefine/cli scan --ci --fail-on warning

# Exit with code 1 only for errors
npx @coderefine/cli scan --ci --fail-on error
```

### Output Formats

| Format | Flag | Description |
|--------|------|-------------|
| JSON | `-f json` (default) | Full scan results as JSON |
| Console | `-f console` | Human-readable summary |
| SARIF | `-f sarif` | Static Analysis Results Interchange Format |

## Example Output

```
CodeRefine scan
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Framework: Next.js (app-router)
Files scanned: 847
Health score: 64/100
Versions: scanner 0.1.0 | scoring 1.0 | rules 1.0

Findings (10 of 127)
  ERR  react/no-direct-state-mutation
       src/components/Form.tsx:23
       Do not mutate state directly

  WRN  react/no-array-index-key
       src/components/List.tsx:45
       Avoid using array index as key

  … 117 more findings (login to see all)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
See the full picture
Login to unlock all findings, track progress, and integrate with your PR workflow.

Get started: https://app.coderefine.co.uk
Or run: coderefine auth login
```

## Guest vs Authenticated

| Feature | Guest | Free (logged in) |
|---------|-------|------------------|
| Health score | ✓ Full | ✓ Full |
| Findings preview | 10 findings | Unlimited |
| Offline scans | ✓ | ✓ |
| Upload & tracking | — | ✓ |

## Commands

| Command | Description |
|---------|-------------|
| `scan` | Run a local scan |
| `upload` | Upload scan results to CodeRefine dashboard |
| `init` | Create config file in current directory |
| `doctor` | Diagnose environment and configuration |
| `auth login` | Login to unlock full features |
| `auth logout` | Remove stored credentials |
| `auth status` | Check authentication status |

### Upload Command

Upload scan results to the CodeRefine dashboard for tracking and team visibility:

```bash
# Upload a scan report
npx @coderefine/cli upload \
  --api-key "$CODEREFINE_TOKEN" \
  --repo-name "my-org/my-repo" \
  --file coderefine-report.json

# With branch and commit info (for CI)
npx @coderefine/cli upload \
  --api-key "$CODEREFINE_TOKEN" \
  --repo-name "$GITHUB_REPOSITORY" \
  --branch "$GITHUB_REF_NAME" \
  --commit "$GITHUB_SHA" \
  --file coderefine-report.json
```

| Flag | Description |
|------|-------------|
| `--api-key <key>` | Organisation API key (required) |
| `--api-url <url>` | API base URL (default: `https://api.coderefine.co.uk`) |
| `-f, --file <path>` | Scan JSON file (or pipe via stdin) |
| `--repository-id <uuid>` | Existing repository ID |
| `--repo-name <name>` | Repository name (e.g., `org/repo`) |
| `--branch <name>` | Branch label |
| `--commit <sha>` | Commit SHA |

### Scan Options

| Flag | Description |
|------|-------------|
| `-r, --root <dir>` | Project root directory (default: cwd) |
| `-f, --format <fmt>` | Output: `json` (default), `console`, `sarif` |
| `-o, --output <file>` | Write report to file |
| `--ci` | CI mode (use with --fail-on) |
| `--fail-on <level>` | Exit 1 if findings at level: `info`, `warning`, `error` |
| `--plan` | Include refactor plan (requires login) |

## Configuration

Create a `.coderefinerc.json` in your project root:

```json
{
  "rules": {
    "react/no-array-index-key": "warning",
    "nextjs/no-img-element": "error"
  },
  "include": ["src/**/*.{ts,tsx}"],
  "exclude": ["**/*.test.ts", "**/node_modules/**"]
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `CODEREFINE_TOKEN` | API token for `upload` command |
| `CODEREFINE_API_URL` | Override API URL (default: `https://api.coderefine.co.uk`) |

## Requirements

- Node.js 18+

## Links

- [Website](https://coderefine.co.uk)
- [Documentation](https://coderefine.co.uk/docs)

## License

MIT
