Metadata-Version: 2.5
Name: codebase-doctor
Version: 0.1.2
Summary: Run one command and find what's wrong with your codebase — locally, for free.
Project-URL: Homepage, https://github.com/Saksham364-gif/codebase-doctor
Project-URL: Repository, https://github.com/Saksham364-gif/codebase-doctor
Project-URL: Issues, https://github.com/Saksham364-gif/codebase-doctor/issues
Author: Saksham
License: MIT
License-File: LICENSE
Keywords: cli,code-quality,linter,secrets-detection,security,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1.42
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli>=2.0.1; python_version < '3.11'
Requires-Dist: tree-sitter-javascript>=0.23.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter-typescript>=0.23.0
Requires-Dist: tree-sitter>=0.23.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# codebase-doctor

> Run one command and find what's wrong with your codebase — locally, for free.

`codebase-doctor` is a local-first static analysis CLI that scans a codebase for hardcoded secrets, insecure code patterns, duplicate logic, unused dependencies, and more. No API key, no cloud, no signup — everything runs on your machine. An optional local LLM mode (via [Ollama](https://ollama.com)) can explain findings and suggest fixes, also entirely offline.

```
📋 Codebase Doctor Report
   142 files scanned in /Users/you/my-project

  🔴 4 critical   🟠 2 high   🟡 3 medium   🔵 1 low

  4 issue(s) can be auto-fixed locally. Run codebase-doctor fix . to preview changes.
```

## Why this exists

Most "codebase health" tools are either narrow (a linter only checks style, `npm audit` only checks known CVEs) or require a paid SaaS signup and send your code to someone else's servers. `codebase-doctor` is a single command that catches secrets, insecure patterns, and code-quality issues at once, runs 100% locally, and is free and open source.

## Install

```bash
pip install codebase-doctor
```

That's it — `codebase-doctor` is now available as a command.

**Installing from source instead** (for development or contributing):

```bash
git clone https://github.com/Saksham364-gif/codebase-doctor.git
cd codebase-doctor
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```

## Usage

### Scan a codebase

```bash
codebase-doctor scan .
```

Scans the given directory (defaults to the current one) and prints a report grouped by scanner, with severity-colored output.

```bash
codebase-doctor scan . --json
```

Outputs machine-readable JSON instead — useful for CI pipelines. `scan` exits with code `1` if any issues are found, `0` on a clean repo, so it can gate a build.

### Fix issues automatically (no API key needed)

```bash
codebase-doctor fix .
```

Shows a dry-run preview of every issue that can be fixed mechanically — currently, hardcoded secrets (extracted to `.env` with the source patched to read from the environment) and unused dependencies (removed from `requirements.txt` / `package.json`). Nothing is written to disk in this mode.

```bash
codebase-doctor fix . --apply
```

Actually writes the changes shown in the preview.

### Get AI-powered explanations (local LLM, still no API key)

```bash
codebase-doctor fix . --ai
```

For issues that need human judgment rather than a mechanical fix (insecure code patterns, duplicate functions, circular imports), this sends the finding to a locally-running [Ollama](https://ollama.com) model for a plain-language explanation and suggested fix. Requires Ollama installed and a model pulled:

```bash
ollama pull qwen2.5-coder
```

If Ollama isn't running, `codebase-doctor` tells you and skips this step — it never fails the rest of the command.

## What it checks

| Scanner | Severity | What it catches |
|---|---|---|
| **secrets** | 🔴 Critical | 25+ patterns: AWS/GCP/Azure keys, GitHub/GitLab/npm tokens, Stripe/Twilio/SendGrid keys, JWTs, private key blocks, hardcoded passwords, DB connection strings with credentials |
| **sensitive_files** | 🔴 Critical | `.env` files, SSH private keys, GCP service account JSON, `.pem`/`.pfx` certs, AWS credentials files committed to the repo |
| **insecure_code** | 🟠 High | `eval()`/`exec()`, command injection (`os.system`, `subprocess` with `shell=True`), insecure deserialization (`pickle.loads`, unsafe `yaml.load`), weak crypto (MD5/SHA1), XSS via `innerHTML`/`dangerouslySetInnerHTML` |
| **vulnerable_deps** | 🟠 High | Dependencies with well-documented, permanent CVEs (offline curated list — see note below) |
| **duplicate_functions** | 🟡 Medium | Structurally identical function bodies across files (AST-based, survives renaming) |
| **circular_deps** | 🟡 Medium | Import cycles between files (Python relative imports and JS/TS relative imports) |
| **huge_files** | 🔵 Low | Files exceeding a configurable line threshold (default 400) |
| **unused_deps** | 🔵 Low | Dependencies declared in `requirements.txt`/`package.json` but never imported anywhere |

**A note on `vulnerable_deps`:** accurate CVE data requires a live, constantly-updated database. This scanner intentionally stays offline by default and checks against a small, curated list of well-documented, permanent vulnerabilities rather than pretending to have full coverage. For live CVE scanning, run `pip-audit` or `npm audit` directly alongside `codebase-doctor`.

## Configuration

Drop a `.codebasedoctorrc.toml` in your project root to customize behavior. Every field is optional:

```toml
ignore_patterns = ["tests/**", "*.generated.ts"]
respect_gitignore = true
max_file_size_bytes = 2000000
huge_file_line_threshold = 400

[scanners]
secrets = true
insecure_code = true
vulnerable_deps = true
duplicate_functions = true
huge_files = true
unused_deps = true
circular_deps = true
```

Set any scanner to `false` to disable it entirely.

## Security & safety design

- **Never executes scanned code.** Every scanner only reads files as text or parses them into an AST — nothing in this tool ever `eval`s or imports code from the repository being scanned.
- **Never follows symlinks outside the scan root** — protects against a crafted symlink exfiltrating files from elsewhere on disk.
- **Fix is dry-run by default, always.** `--apply` is required to write anything, and every fix is shown as a diff before it happens.
- **Secrets are redacted in all output.** Findings show the first few characters plus asterisks, never the full value.
- **Config files can't execute code.** `.codebasedoctorrc.toml` is parsed as plain TOML data — a malformed or malicious config can only fail validation, never run anything.

## Architecture

```
codebase-doctor/
├── src/codebase_doctor/
│   ├── cli.py                  Typer CLI: scan, fix, version
│   ├── scan_runner.py          Orchestrates all scanners into one ScanResult
│   ├── core/
│   │   ├── walker.py           .gitignore-aware, symlink/binary/size-safe file walker
│   │   ├── gitignore.py        From-scratch .gitignore pattern matcher
│   │   ├── config.py           Pydantic-validated TOML config loader
│   │   ├── report.py           Console (rich) and JSON report rendering
│   │   ├── types.py            Shared Finding / ScanResult data structures
│   │   └── ast_utils.py        Shared tree-sitter AST traversal helper
│   ├── parsers/
│   │   └── tree_sitter_registry.py   Python/JS/TS/TSX parsing via tree-sitter
│   ├── scanners/                One file per detector, each a pure function
│   └── fixers/
│       ├── local_fix.py         Mechanical fixes (no API): secrets → .env, unused deps
│       └── local_llm_fix.py     Local LLM explanations via Ollama (no API key)
└── tests/                       171 tests, mirroring the src/ structure
```

Every scanner is a pure function: `(file_path, content) -> list[Finding]`. That makes each one independently testable and easy to extend — adding a new check means adding one file to `scanners/` and wiring it into `scan_runner.py`.

## Development

```bash
pip install -e ".[dev]"
pytest -v
ruff check src/ tests/
```

CI runs both on every push via GitHub Actions.

## Roadmap

- [ ] `--online` flag for live CVE scanning via `pip-audit`/`npm audit`
- [ ] Codebase health score dashboard (Security/Architecture/Performance/Maintainability, 0-100)
- [ ] `codebase-doctor restructure` — suggest (and eventually, with confirmation, apply) folder structure improvements
- [ ] Git integration: diff-aware scanning (`--staged`, `--since <branch>`), pre-commit hook installer
- [ ] Support for more languages beyond Python/JS/TS

## License

MIT — see [LICENSE](LICENSE).

## Contributing

Issues and pull requests welcome. This project intentionally keeps every scanner as an independent, pure function with its own test file — see any file in `src/codebase_doctor/scanners/` for the pattern to follow when adding a new check.