Metadata-Version: 2.5
Name: codebase-doctor
Version: 0.1.0
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.


## 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

PyPI publishing is planned; for now, install from source:

```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 .
```

This installs the `codebase-doctor` command into your environment.

## 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

- [ ] Publish to PyPI (`pip install codebase-doctor`)
- [ ] `--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.