Metadata-Version: 2.4
Name: preflight-scan
Version: 0.1.0
Summary: Is your vibe-coded project ready to ship? A zero-dependency architecture and cleanliness scanner.
Author: preflight
License: MIT
Keywords: code-quality,vibe-coding,static-analysis,cleanup,refactoring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Preflight

**Is your vibe-coded project ready to ship?**

You built something with AI — it works on your machine, and now you want it to
be a real product. `preflight` reads your codebase the way a senior engineer
skims it on day one and tells you, concretely, what stands between "it runs"
and "it ships": dead code, copy-paste forks, hardcoded keys, missing licenses
and tests, leftover `final_v2.py` files, functions nobody can review.

- **Zero dependencies.** Pure Python stdlib. Nothing to break.
- **Zero LLM calls. Runs entirely offline.** Your code never leaves your machine.
- **Every finding comes with a concrete fix**, not just a complaint.
- **A ship-readiness score (0–100)** you can put in CI and watch improve.

```
SHIP-READINESS SCORE: 21/100 — not ready to ship

[HIGH] 1 possible hardcoded secret(s)
       config.py:1 — OpenAI/Anthropic-style key
       fix -> Move secrets to environment variables NOW, rotate any real
              key that was committed, and add the files to .gitignore.

[HIGH] 2 module(s) appear unreachable
       fix -> Verify with your test suite, then delete them.

[HIGH] Version strings disagree across files
       myapp/__init__.py = 1.0.0; setup.py = 1.2.0
       fix -> Pick one source of truth (pyproject.toml).
```

## One-click (no terminal)

Download this repo, open the `launchers/` folder, and double-click:

- **Mac:** `Check My Code (Mac).command` — first run may need right-click → Open
- **Windows:** `Check My Code (Windows).bat`

It installs itself the first time, asks you to drag your project folder in,
and writes `preflight_report.md` next to your project with everything it
found and how to fix each one. That's it.

## 30 seconds in a terminal

```bash
pip install preflight-scan
preflight demo          # builds a deliberately messy project and scans it
preflight path/to/your/project
```

The terminal shows the summary; the full report (with file lists and fixes)
is written to `preflight_report.md` in the scanned folder.

## One line in CI

```bash
preflight . --fail-under 75    # exit nonzero if the score drops below 75
```

## What it checks

| Check | What it catches |
|---|---|
| Dead modules | Files no code path can reach (verified by import graph) |
| Hardcoded secrets | OpenAI/Anthropic/AWS/GitHub/Slack/Google keys, private key blocks |
| Copy-paste forks | Substantial duplicated blocks across files; byte-identical files |
| Dependency hygiene | Imports you never declared; no manifest at all |
| Version truth | Version strings that disagree (or are duplicated) across files |
| Error-handling slop | Bare `except:`; `except Exception: pass` silent failures |
| Circular imports | Module-level import cycles (lazy in-function imports excluded — that's the fix, not the bug) |
| Oversized units | 700+ line files, 80+ line functions, deeply nested control flow |
| Leftover working files | `final_v2.py`, `untitled3.py`, `.DS_Store`, `*.pyc`, editor swap files |
| Ship essentials | Missing README, LICENSE, .gitignore, tests, CI |
| Broken files | Python that doesn't even parse |
| TODO debt | Heavy TODO/FIXME/HACK density |

False-positive suppression for known-fake fixtures: append `# preflight:ignore`
to the line.

## Honesty notes (read before trusting the score)

- These are **static heuristics**, deliberately conservative. A finding is a
  prompt for human judgment, not a verdict; the absence of findings is not a
  security audit or a code review.
- Python gets the deepest analysis (AST-based). JavaScript/TypeScript gets
  duplication, secrets, junk, size, and debug-residue checks — not import
  graphs.
- preflight flags its own test suite's fake keys when scanned. A scanner that
  special-cased itself would be lying; use `# preflight:ignore` like everyone
  else (we do).
- Dogfooded for real: preflight's first run against a 17,500-line production
  package found 3 dead modules, an undeclared-extras parser gap (in itself —
  fixed), and a core scoring function duplicated across two entry points that
  had already begun to drift. All fixed; that package went 62 → 90/100.

## License

MIT.
