# codesmell

Local CLI that turns a coding goal into ranked, token-budgeted repository context for AI agents.

```
agent → shell → codesmell JSON → agent reasoning
```

No daemon. No MCP. No network. Reads the local checkout, writes `.codesmell/` cache, exits.

## Usage

```sh
codesmell pack --root . --goal "fix refresh token bug" --budget 12000 --format json
```

All commands support `--format json` (agent contract) or plain terminal output (omit the flag).

| Command | Purpose |
|---------|---------|
| `init` | Bootstrap `.codesmell/` config and cache |
| `doctor` | Check local readiness |
| `map` | Repo structure, languages, public symbols |
| `search` | Ranked evidence for a query |
| `pack` | Budgeted context pack for a coding goal |
| `explain` | Deep-dive a file or symbol |
| `diff` | Changed files, symbols, risk hints |
| `test-plan` | Focused test suggestions |
| `review` | Deterministic findings with evidence |

## Agent Contract

`--format json` emits exactly one JSON object on stdout (`schema_version: "codesmell.agent.v1"`). Diagnostics go to stderr.

Key fields: `status`, `confidence`, `budget`, `coverage`, `guidance`, `evidence`, `findings`, `risks`, `test_hints`, `redactions`, `recommended_next`.

Status values:

- `ok` — actionable evidence, proceed.
- `partial` — evidence with caveats; run a follow-up before broad edits.
- `needs_refinement` — goal too broad; narrow via `recommended_next`.
- `error` — no evidence; check `warnings`.

Secrets are redacted before output. Only counts and kinds are reported — never raw values.

## Architecture

```
crates/
  codesmell-cli      clap commands, JSON/human output
  codesmell-core     domain types, config, errors
  codesmell-facts    language-neutral fact model, AST cache schema
  codesmell-engine   shared workspace analysis orchestration
  codesmell-scan     gitignore-aware walking, classification, fingerprints
  codesmell-parse    tree-sitter parsing, symbol/import extraction
  codesmell-index    lexical ranking, BM25-style scoring
  codesmell-pack     context budgeting, redaction, evidence selection
  codesmell-review   diff analysis, findings, test-plan
```

Rust is the only tree-sitter-parsed language today. Other languages are scanned and ranked lexically.

## Development

```sh
cargo build --workspace
cargo test
cargo fmt --check
cargo clippy --all-targets -- -D warnings
```

Run locally:

```sh
cargo run -p codesmell-cli -- pack --root . --goal "fix bug" --budget 12000 --format json
```

Test fixture: `tests/fixtures/rust-basic`. Integration tests synthesize ignored files, secrets, staged changes, renames, and mixed-language scenarios in temp repos.

Large-repo smoke (optional, ignored by default):

```sh
scripts/clone-bun-test-repo.sh
cargo test -p codesmell-cli core_commands_smoke_run_on_ignored_bun_test_repo -- --ignored
```

## Docs

Design and roadmap details live in [`docs/`](docs/):

- [`IDEA.md`](docs/IDEA.md) — product vision and positioning
- [`AST_ENGINE_DESIGN.md`](docs/AST_ENGINE_DESIGN.md) — engine internals and tree-sitter strategy
- [`ROADMAP.md`](docs/ROADMAP.md) — milestone tracking
- [`TGREP_DESIGN.md`](docs/TGREP_DESIGN.md) — tgrep relation-search design
- [`TGREP_ROADMAP.md`](docs/TGREP_ROADMAP.md) — tgrep milestones