# Scorecard

> Scorecard (`sc`) is a local-first, deterministic code quality gate. One run checks that a project builds, tests pass, complex code is covered (CRAP), no secrets are committed, the linter is clean, and every import is a declared dependency. It prints a verdict for people and a JSON scorecard for agents and CI. Ten language packs are built in. `sc-mcp` is a stdio MCP server for agents.

This file is for agents. Full docs: https://scorecardcli.com/llms-full.txt. Tool list: https://scorecardcli.com/agents.json. Source: https://github.com/moonbase2090/Scorecard (MIT).

## Prerequisites

- macOS (Apple silicon or Intel) or Linux (x86_64 or arm64) for release binaries. No Windows release archive is published.
- `git` (diff scoring and the secrets scan use it).
- The toolchain of the project you analyze (each pack runs that language's own build, test and lint tools). Rust coverage needs `rustup component add llvm-tools` and `cargo install cargo-llvm-cov`; without them coverage is reported as not measured.
- Rust 1.88 or newer to build from source.

## Install

Latest release: v0.1.10 — https://github.com/moonbase2090/Scorecard/releases/tag/v0.1.10. Each archive contains `sc` and `sc-mcp`.

### macOS

- `sc-v0.1.10-macos.pkg` or `sc-v0.1.10-universal-apple-darwin.dmg` installs `sc` and `sc-mcp` to `/usr/local/bin`.
- Or a tarball: `sc-v0.1.10-aarch64-apple-darwin.tar.gz` (Apple silicon), `sc-v0.1.10-x86_64-apple-darwin.tar.gz` (Intel).

### Linux

```sh
TARGET=x86_64-unknown-linux-gnu   # or aarch64-unknown-linux-gnu
curl -fsSLO https://github.com/moonbase2090/Scorecard/releases/download/v0.1.10/sc-v0.1.10-$TARGET.tar.gz
curl -fsSLO https://github.com/moonbase2090/Scorecard/releases/download/v0.1.10/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS      # macOS: shasum -a 256 -c --ignore-missing SHA256SUMS
tar -xzf sc-v0.1.10-$TARGET.tar.gz
install -m 755 sc-v0.1.10-$TARGET/sc sc-v0.1.10-$TARGET/sc-mcp ~/.local/bin/
```

### Windows

No Windows binary is published. Build from source (below) where a Rust toolchain is available.

### Build from source

```sh
git clone https://github.com/moonbase2090/Scorecard.git && cd Scorecard
cargo install --locked --path crates/sc-cli
cargo install --locked --path crates/sc-mcp
```

## Configuration

- Config file: `--config PATH`, else `./analyzer.toml`, else `~/.config/sc/analyzer.toml`. `sc config init` writes a starter user config; `sc config path` prints its path.
- Add `.sc/` to `.gitignore`; `sc` keeps its last report and caches there.
- `sc setup` installs the agent skill and registers the `sc-mcp` server for this user. `sc skills install --agent detected` installs only the skill instructions.
- MCP: run `sc-mcp` (stdio) in the project directory, e.g. `{"mcpServers": {"scorecard": {"command": "sc-mcp"}}}`.

## Tools

### MCP tools (`sc-mcp`)

- `analyze_paths` — analyze explicit source paths and return a scorecard. Params: `paths` (array of strings, required), `spec_ref`. Example: `{"paths": ["src/lib.rs"]}`
- `analyze_diff` — analyze a git diff and return a scorecard. Params: `base`, `head`, `spec_ref`. Example: `{"base": "main"}`
- `explain` — explain one finding from the last scorecard. Params: `finding_id` (required).
- `list_findings` — list findings from the last scorecard. Params: `scorecard_id`, `severity`.

### CLI (`sc`)

- `sc analyze [PATH]` — analyze a project tree (default `.`). Flags:
  - `--format json|pretty|md|sarif|html|all` (default: `pretty` on a terminal, else `json`)
  - `--out PATH` — also write the report there; stdout prints a summary
  - `--fail-on LIST` — gates that set exit 1 (default `types,tests,crap,secrets,lint`; `none` suppresses)
  - `--pack rust|node|python|bash|go|java|csharp|php|cpp|web|command`
  - `--diff [BASE]` (bare = auto: `HEAD~1`, else `main`, else `master`), `--diff-head COMMIT`, `--paths LIST` (newline-separated; exclusive with `--diff`)
  - `--spec FILE`, `--mutation off|diff|full`, `--llm off|on` (optional spec review against a configured endpoint), `--intent TEXT`
  - `--budget-seconds N` (default 120), `--config PATH`, `--quiet`
  - Examples: `sc analyze .`, `sc analyze . --diff main --format json`, `sc analyze . --format sarif --out sc.sarif`
- `sc config path` | `sc config init`.
- `sc setup` — install the agent skill and register `sc-mcp`.
- `sc skills install [--agent AGENT] [--check] [--force]` — `--agent` defaults to `all`; `detected` targets only agents already configured or on PATH. Run `sc skills install --help` for the identifiers.
- `sc --version`.

Exit codes: `0` no `--fail-on` gate failed; `1` a selected gate failed; `2` `sc` could not run.

## Usage workflows

1. Before committing: `sc analyze . --diff --format json` and read `verdict`, gates and findings.
2. Agents via MCP: `analyze_diff` (or `analyze_paths`), then `list_findings` and `explain` for each finding to fix.
3. CI / code scanning: `sc analyze . --format sarif --out sc.sarif`. Only `secrets.*` findings are level `error`.
4. Full reports: `sc analyze . --format all --out report` writes every format.
5. Cargo workspace: analyze the root for every member, or a member directory for one package.

## Troubleshooting

- `--diff` exits 2 in CI: shallow clone or missing base; fetch full history (`fetch-depth: 0`) or pass an explicit base.
- Coverage "not measured" on Rust: install `llvm-tools` and `cargo-llvm-cov`.
- `secrets.empty_scope`: the scope selected no files; check the path and exclusions.
- Exit 0 but an enforced gate failed: `--fail-on` excluded it; `sc` prints a stderr warning naming it.
- Several manifests match: choose with `--pack`.
- More: https://github.com/moonbase2090/Scorecard/blob/main/docs/troubleshooting.md

## Links

- [Full agent docs](https://scorecardcli.com/llms-full.txt)
- [agents.json](https://scorecardcli.com/agents.json)
- [Wiki](https://scorecardcli.com/wiki/)
- [Source](https://github.com/moonbase2090/Scorecard)
- [Releases](https://github.com/moonbase2090/Scorecard/releases)
- [CLI reference](https://github.com/moonbase2090/Scorecard/blob/main/docs/reference/cli.md)
- [Gates](https://github.com/moonbase2090/Scorecard/blob/main/docs/reference/gates.md)