preflight-scan 0.1.0

Is your vibe-coded project ready to ship? A zero-dependency architecture and cleanliness scanner.

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

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

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.