preflight-scan 0.1.0__py3-none-any.whl

preflight/__init__.py

@@ -0,0 +1,13 @@
+"""preflight — is your vibe-coded project ready to ship?
+
+A zero-dependency static scanner that reads a codebase the way a senior
+engineer skims it on day one: where's the dead weight, what's duplicated,
+what's going to break in production, and what's missing before this can be
+deployed as a real product.
+
+Runs entirely offline. No LLM calls. Nothing leaves your machine.
+"""
+__version__ = "0.1.0"
+
+from .checks import scan_project, Finding, ScanResult  # noqa: F401
+from .report import render_markdown, render_terminal   # noqa: F401

preflight/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

preflight/checks.py

@@ -0,0 +1,764 @@
+"""All analyzers. Each check reads the shared FileIndex and yields Findings.
+
+Design rules (the same ones the report enforces on your code):
+  - stdlib only, no network, no LLM;
+  - conservative by default — a finding should be worth a human's time;
+  - every finding carries concrete advice, not just a complaint.
+"""
+from __future__ import annotations
+
+import ast
+import hashlib
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+
+# Directories that are never the user's source code.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "__pycache__", ".pytest_cache", ".mypy_cache",
+    ".ruff_cache", ".tox", ".venv", "venv", "env", "node_modules", "dist",
+    "build", ".next", ".nuxt", "coverage", ".idea", ".vscode", ".eggs",
+    "site-packages", ".cache", "htmlcov",
+}
+TEXT_EXTS = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".json",
+             ".md", ".txt", ".toml", ".cfg", ".ini", ".yml", ".yaml", ".env",
+             ".sh", ".bat", ".html", ".css"}
+CODE_EXTS = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"}
+MAX_TEXT_BYTES = 1_500_000
+
+SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2, "info": 3}
+SEVERITY_PENALTY = {"high": 10, "medium": 4, "low": 1, "info": 0}
+
+
+@dataclass
+class Finding:
+    check: str
+    severity: str        # high | medium | low | info
+    title: str
+    detail: str
+    advice: str
+    paths: list = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"check": self.check, "severity": self.severity,
+                "title": self.title, "detail": self.detail,
+                "advice": self.advice, "paths": list(self.paths)}
+
+
+@dataclass
+class ScanResult:
+    root: str
+    findings: list
+    files_scanned: int
+    code_files: int
+    total_lines: int
+    score: int
+    grade: str
+
+    def to_dict(self) -> dict:
+        return {"root": self.root, "files_scanned": self.files_scanned,
+                "code_files": self.code_files, "total_lines": self.total_lines,
+                "score": self.score, "grade": self.grade,
+                "findings": [f.to_dict() for f in self.findings]}
+
+
+# ── File index ────────────────────────────────────────────────────────────────
+
+class FileIndex:
+    """One walk of the tree; everything else reads from here."""
+
+    def __init__(self, root: str):
+        self.root = os.path.abspath(root)
+        self.files: list = []          # rel paths, all files
+        self.text: dict = {}           # rel path -> str content (text files)
+        self.py_ast: dict = {}         # rel path -> ast.Module (parse ok)
+        self.py_bad: list = []         # rel paths that fail to parse
+        self.total_lines = 0
+        self._walk()
+
+    def _walk(self) -> None:
+        for dirpath, dirnames, filenames in os.walk(self.root):
+            dirnames[:] = [d for d in sorted(dirnames) if d not in SKIP_DIRS]
+            for name in sorted(filenames):
+                full = os.path.join(dirpath, name)
+                rel = os.path.relpath(full, self.root).replace(os.sep, "/")
+                self.files.append(rel)
+                ext = os.path.splitext(name)[1].lower()
+                if ext not in TEXT_EXTS:
+                    continue
+                try:
+                    if os.path.getsize(full) > MAX_TEXT_BYTES:
+                        continue
+                    with open(full, encoding="utf-8", errors="replace") as fh:
+                        content = fh.read()
+                except OSError:
+                    continue
+                self.text[rel] = content
+                if ext in CODE_EXTS:
+                    self.total_lines += content.count("\n") + 1
+                if ext == ".py":
+                    try:
+                        self.py_ast[rel] = ast.parse(content)
+                    except SyntaxError:
+                        self.py_bad.append(rel)
+
+    def code_paths(self) -> list:
+        return [p for p in self.text
+                if os.path.splitext(p)[1].lower() in CODE_EXTS]
+
+    def is_testish(self, rel: str) -> bool:
+        low = rel.lower()
+        return ("test" in low.split("/")[-1] or low.startswith("tests/")
+                or "/tests/" in low or "conftest" in low)
+
+
+# ── Python import graph (dead modules + cycles) ───────────────────────────────
+
+def _py_module_name(rel: str) -> str:
+    return rel[:-3].replace("/", ".").removesuffix(".__init__")
+
+
+def _build_import_graph(idx: FileIndex, top_level_only: bool = False) -> dict:
+    """module name -> set of imported module names (only project-local).
+
+    top_level_only=True ignores imports inside functions/methods — those are
+    the *standard fix* for circular imports, so the cycle check must not
+    count them. The dead-module check uses the full graph (a lazy import
+    still keeps a module alive)."""
+    local = {_py_module_name(p): p for p in idx.py_ast}
+    graph: dict = {m: set() for m in local}
+    for rel, tree in idx.py_ast.items():
+        me = _py_module_name(rel)
+        # for __init__.py the module name IS the package, so relative imports
+        # resolve against it directly; for plain modules, against the parent.
+        pkg_parts = me.split(".") if rel.endswith("__init__.py") \
+            else me.split(".")[:-1]
+        if top_level_only:
+            nodes = []
+            stack = list(ast.iter_child_nodes(tree))
+            while stack:
+                n = stack.pop()
+                if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    continue
+                nodes.append(n)
+                stack.extend(ast.iter_child_nodes(n))
+        else:
+            nodes = list(ast.walk(tree))
+        for node in nodes:
+            targets = []
+            if isinstance(node, ast.Import):
+                targets = [a.name for a in node.names]
+            elif isinstance(node, ast.ImportFrom):
+                if node.level:                      # relative import
+                    base = pkg_parts[: len(pkg_parts) - node.level + 1]
+                    mod = ".".join(base + ([node.module] if node.module else []))
+                    targets = [mod] + [f"{mod}.{a.name}" for a in node.names]
+                elif node.module:
+                    targets = [node.module] + \
+                        [f"{node.module}.{a.name}" for a in node.names]
+            for t in targets:
+                while t:
+                    if t in local and t != me:
+                        graph[me].add(t)
+                        break
+                    t = t.rpartition(".")[0]
+    return graph
+
+
+_ENTRYISH = {"__init__", "__main__", "cli", "main", "app", "setup",
+             "conftest", "manage", "wsgi", "asgi", "run", "server"}
+
+
+def check_dead_modules(idx: FileIndex) -> list:
+    graph = _build_import_graph(idx)
+    imported = set()
+    for deps in graph.values():
+        imported |= deps
+    # entry points declared in pyproject count as roots
+    entry_strings = ""
+    for rel in ("pyproject.toml", "setup.py", "setup.cfg", "package.json"):
+        entry_strings += idx.text.get(rel, "")
+    dead = []
+    for mod, rel in sorted({_py_module_name(p): p for p in idx.py_ast}.items()):
+        base = mod.split(".")[-1]
+        if mod in imported or base in _ENTRYISH:
+            continue
+        if idx.is_testish(rel) or "/" not in rel:       # repo-root scripts: skip
+            continue
+        if "examples/" in rel or "scripts/" in rel or "tools/" in rel:
+            continue
+        if base in entry_strings or mod in entry_strings:
+            continue
+        dead.append(rel)
+    if not dead:
+        return []
+    return [Finding(
+        check="dead_modules", severity="high",
+        title=f"{len(dead)} module(s) appear unreachable",
+        detail="No other module imports these, they are not entry points, "
+               "tests, or examples. Dead modules confuse contributors, hide "
+               "in security audits, and rot silently.",
+        advice="Verify with your test suite, then delete them (keep them in "
+               "git history or an attic/ folder outside the package).",
+        paths=dead)]
+
+
+def check_import_cycles(idx: FileIndex) -> list:
+    graph = _build_import_graph(idx, top_level_only=True)
+    # iterative DFS strongly-connected detection (small graphs: simple approach)
+    cycles, seen = [], set()
+    for start in graph:
+        if start in seen:
+            continue
+        stack, path, on_path = [(start, iter(graph[start]))], [start], {start}
+        while stack:
+            node, it = stack[-1]
+            advanced = False
+            for nxt in it:
+                if nxt in on_path:
+                    cyc = path[path.index(nxt):] + [nxt]
+                    key = frozenset(cyc)
+                    if key not in {frozenset(c) for c in cycles}:
+                        cycles.append(cyc)
+                elif nxt not in seen:
+                    stack.append((nxt, iter(graph[nxt])))
+                    path.append(nxt)
+                    on_path.add(nxt)
+                    advanced = True
+                    break
+            if not advanced:
+                seen.add(node)
+                stack.pop()
+                path.pop()
+                on_path.discard(node)
+    if not cycles:
+        return []
+    shown = [" -> ".join(c) for c in cycles[:5]]
+    return [Finding(
+        check="import_cycles", severity="medium",
+        title=f"{len(cycles)} circular import chain(s)",
+        detail="Cycles: " + "; ".join(shown) +
+               (" (more not shown)" if len(cycles) > 5 else ""),
+        advice="Break each cycle by moving the shared piece into its own "
+               "module, or defer one import into the function that needs it.")]
+
+
+# ── Duplication ───────────────────────────────────────────────────────────────
+
+def _normalized_lines(content: str, ext: str) -> list:
+    out = []
+    for line in content.splitlines():
+        s = line.strip()
+        if not s:
+            continue
+        if ext == ".py" and s.startswith("#"):
+            continue
+        if ext != ".py" and (s.startswith("//") or s.startswith("*")):
+            continue
+        out.append(s)
+    return out
+
+
+WINDOW = 8
+
+
+def check_duplication(idx: FileIndex) -> list:
+    occurrences: dict = {}
+    for rel in idx.code_paths():
+        ext = os.path.splitext(rel)[1].lower()
+        lines = _normalized_lines(idx.text[rel], ext)
+        for i in range(len(lines) - WINDOW + 1):
+            h = hashlib.md5("\n".join(lines[i:i + WINDOW]).encode()).hexdigest()
+            occurrences.setdefault(h, []).append(rel)
+    pair_hits: dict = {}
+    for paths in occurrences.values():
+        uniq = sorted(set(paths))
+        if len(uniq) >= 2:
+            for a in range(len(uniq)):
+                for b in range(a + 1, len(uniq)):
+                    pair_hits[(uniq[a], uniq[b])] = \
+                        pair_hits.get((uniq[a], uniq[b]), 0) + 1
+        elif len(paths) >= 3:                       # heavy self-duplication
+            pair_hits[(uniq[0], uniq[0])] = \
+                pair_hits.get((uniq[0], uniq[0]), 0) + 1
+    findings = []
+    serious = {k: v for k, v in pair_hits.items() if v >= 3}
+    if serious:
+        top = sorted(serious.items(), key=lambda kv: -kv[1])[:10]
+        lines = [(f"{a} <-> {b}" if a != b else f"{a} (within itself)") +
+                 f": ~{n * WINDOW}+ duplicated lines" for (a, b), n in top]
+        findings.append(Finding(
+            check="duplication", severity="medium",
+            title=f"{len(serious)} file pair(s) share substantial copy-paste",
+            detail="\n".join(lines),
+            advice="Extract the shared logic into one function/module and "
+                   "import it. Copy-paste forks silently: the next bug fix "
+                   "will land in one copy and not the other.",
+            paths=sorted({p for pair in serious for p in pair})))
+    # byte-identical files
+    by_hash: dict = {}
+    for rel in idx.code_paths():
+        by_hash.setdefault(
+            hashlib.md5(idx.text[rel].encode()).hexdigest(), []).append(rel)
+    twins = [sorted(v) for v in by_hash.values() if len(v) > 1]
+    if twins:
+        findings.append(Finding(
+            check="identical_files", severity="medium",
+            title=f"{len(twins)} set(s) of byte-identical code files",
+            detail="; ".join(" == ".join(t) for t in twins[:5]),
+            advice="Keep one canonical copy; delete or symlink the rest.",
+            paths=[p for t in twins for p in t]))
+    return findings
+
+
+# ── Junk, stale artifacts, vibe-residue filenames ────────────────────────────
+
+_JUNK_BASENAMES = {".DS_Store", "Thumbs.db", "desktop.ini"}
+_JUNK_EXTS = {".pyc", ".pyo", ".swp", ".swo", ".orig", ".rej", ".tmp", ".bak"}
+_VIBE_NAME_RE = re.compile(
+    r"(copy ?\d*|final|final_v\d+|v\d+_final|untitled\d*|new\d+|test123|"
+    r"asdf|temp|old|backup|deleteme|donotuse)", re.IGNORECASE)
+
+
+def check_junk_files(idx: FileIndex) -> list:
+    junk, vibey = [], []
+    for rel in idx.files:
+        base = os.path.basename(rel)
+        stem, ext = os.path.splitext(base)
+        if base in _JUNK_BASENAMES or ext.lower() in _JUNK_EXTS:
+            junk.append(rel)
+        elif (ext.lower() in CODE_EXTS and _VIBE_NAME_RE.fullmatch(stem)):
+            vibey.append(rel)
+    out = []
+    if junk:
+        out.append(Finding(
+            check="junk_files", severity="low",
+            title=f"{len(junk)} junk/OS artifact file(s) in the tree",
+            detail=", ".join(junk[:15]) + (" …" if len(junk) > 15 else ""),
+            advice="Delete them and add the patterns to .gitignore.",
+            paths=junk))
+    if vibey:
+        out.append(Finding(
+            check="leftover_names", severity="medium",
+            title=f"{len(vibey)} file(s) with leftover working names",
+            detail=", ".join(vibey[:15]),
+            advice="'final_v2.py' and friends are how the wrong file gets "
+                   "deployed. Rename to what the file actually does, or "
+                   "delete it.",
+            paths=vibey))
+    return out
+
+
+# ── Oversized units / deep nesting (Python AST; line counts for JS) ──────────
+
+def check_oversized(idx: FileIndex) -> list:
+    big_files, big_funcs, deep = [], [], []
+    for rel in idx.code_paths():
+        n = idx.text[rel].count("\n") + 1
+        if n > 700 and not idx.is_testish(rel):
+            big_files.append(f"{rel} ({n} lines)")
+    for rel, tree in idx.py_ast.items():
+        if idx.is_testish(rel):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                span = (getattr(node, "end_lineno", node.lineno) - node.lineno)
+                if span > 80:
+                    big_funcs.append(f"{rel}:{node.lineno} "
+                                     f"{node.name}() ({span} lines)")
+        depth = _max_nesting(tree)
+        if depth > 5:
+            deep.append(f"{rel} (nesting depth {depth})")
+    out = []
+    if big_files:
+        out.append(Finding(
+            check="oversized_files", severity="low",
+            title=f"{len(big_files)} very large source file(s)",
+            detail=", ".join(big_files[:10]),
+            advice="Split by responsibility. A 1,000-line file is where "
+                   "duplicate logic and dead code go to hide.",
+            paths=[b.split(" ")[0] for b in big_files]))
+    if big_funcs:
+        out.append(Finding(
+            check="oversized_functions", severity="medium",
+            title=f"{len(big_funcs)} function(s) over 80 lines",
+            detail="\n".join(big_funcs[:10]) +
+                   ("\n…" if len(big_funcs) > 10 else ""),
+            advice="Extract the distinct phases into named helpers — "
+                   "long functions are untestable and unreviewable.",
+            paths=[b.split(":")[0] for b in big_funcs]))
+    if deep:
+        out.append(Finding(
+            check="deep_nesting", severity="low",
+            title=f"{len(deep)} file(s) with deeply nested control flow",
+            detail=", ".join(deep[:10]),
+            advice="Invert conditions and return early; extract inner loops.",
+            paths=[d.split(" ")[0] for d in deep]))
+    return out
+
+
+def _max_nesting(tree: ast.AST) -> int:
+    worst = 0
+
+    def walk(node, depth):
+        nonlocal worst
+        for child in ast.iter_child_nodes(node):
+            d = depth + isinstance(child, (ast.If, ast.For, ast.While,
+                                           ast.With, ast.Try))
+            worst = max(worst, d)
+            walk(child, d)
+    walk(tree, 0)
+    return worst
+
+
+# ── Error-handling slop + debug residue (Python AST / JS regex) ──────────────
+
+def check_error_handling(idx: FileIndex) -> list:
+    bare, swallowed = [], []
+    for rel, tree in idx.py_ast.items():
+        if idx.is_testish(rel):
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ExceptHandler):
+                is_bare = node.type is None
+                body_is_pass = (len(node.body) == 1
+                                and isinstance(node.body[0], ast.Pass))
+                broad = (isinstance(node.type, ast.Name)
+                         and node.type.id in ("Exception", "BaseException"))
+                if is_bare:
+                    bare.append(f"{rel}:{node.lineno}")
+                elif broad and body_is_pass:
+                    swallowed.append(f"{rel}:{node.lineno}")
+    out = []
+    if bare:
+        out.append(Finding(
+            check="bare_except", severity="high",
+            title=f"{len(bare)} bare `except:` clause(s)",
+            detail=", ".join(bare[:10]),
+            advice="Catch the specific exception you expect. Bare except "
+                   "swallows KeyboardInterrupt, SystemExit, and every bug "
+                   "you'll ever need to see.",
+            paths=[b.split(":")[0] for b in bare]))
+    if swallowed:
+        out.append(Finding(
+            check="swallowed_exceptions", severity="medium",
+            title=f"{len(swallowed)} `except Exception: pass` block(s)",
+            detail=", ".join(swallowed[:10]),
+            advice="At minimum log the exception. Silent failure in "
+                   "production is the most expensive bug class there is.",
+            paths=[s.split(":")[0] for s in swallowed]))
+    return out
+
+
+_CONSOLE_RE = re.compile(r"^\s*console\.log\(", re.MULTILINE)
+
+
+def check_debug_residue(idx: FileIndex) -> list:
+    js_hits = []
+    for rel in idx.code_paths():
+        ext = os.path.splitext(rel)[1].lower()
+        if ext in (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs") \
+                and not idx.is_testish(rel):
+            n = len(_CONSOLE_RE.findall(idx.text[rel]))
+            if n >= 5:
+                js_hits.append(f"{rel} ({n}x console.log)")
+    if not js_hits:
+        return []
+    return [Finding(
+        check="debug_residue", severity="low",
+        title=f"{len(js_hits)} file(s) full of console.log debugging",
+        detail=", ".join(js_hits[:10]),
+        advice="Replace with a real logger (or remove). Shipping debug spew "
+               "leaks internals and drowns real errors.",
+        paths=[h.split(" ")[0] for h in js_hits])]
+
+
+# ── Secrets ───────────────────────────────────────────────────────────────────
+
+_SECRET_PATTERNS = [
+    ("OpenAI/Anthropic-style key", re.compile(r"\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}")),
+    ("AWS access key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
+    ("GitHub token", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{30,}\b")),
+    ("Slack token", re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}")),
+    ("Google API key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
+    ("Private key block", re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----")),
+]
+_PLACEHOLDER_RE = re.compile(
+    r"(your|example|placeholder|changeme|dummy|xxx+|<.*>|\.\.\.)", re.IGNORECASE)
+
+
+def check_secrets(idx: FileIndex) -> list:
+    hits = []
+    for rel, content in idx.text.items():
+        lines = content.splitlines()
+        for label, pat in _SECRET_PATTERNS:
+            for m in pat.finditer(content):
+                window = content[max(0, m.start() - 40): m.end() + 10]
+                if _PLACEHOLDER_RE.search(window):
+                    continue
+                line = content.count("\n", 0, m.start()) + 1
+                # inline suppression for known-fake fixtures:
+                #   KEY = "sk-..."  # preflight:ignore
+                src_line = lines[line - 1] if line <= len(lines) else ""
+                if "preflight:ignore" in src_line:
+                    continue
+                hits.append((rel, line, label))
+    if not hits:
+        return []
+    return [Finding(
+        check="secrets", severity="high",
+        title=f"{len(hits)} possible hardcoded secret(s)",
+        detail="\n".join(f"{r}:{ln} — {lbl}" for r, ln, lbl in hits[:10]),
+        advice="Move secrets to environment variables NOW, rotate any real "
+               "key that was committed (git history remembers), and add the "
+               "files to .gitignore.",
+        paths=sorted({r for r, _, _ in hits}))]
+
+
+# ── Dependency hygiene (Python) ───────────────────────────────────────────────
+
+_IMPORT_TO_DIST = {
+    "pil": "pillow", "cv2": "opencv-python", "sklearn": "scikit-learn",
+    "yaml": "pyyaml", "dotenv": "python-dotenv", "bs4": "beautifulsoup4",
+    "attr": "attrs", "dateutil": "python-dateutil", "jose": "python-jose",
+    "opentelemetry": "opentelemetry-api", "google": "google-api-core",
+}
+
+
+def _declared_deps(idx: FileIndex) -> set:
+    """Every package name declared anywhere in pyproject (core deps AND
+    optional extras — an extra is still a declaration) or requirements files.
+    Deliberately permissive: this set only ever *suppresses* findings."""
+    declared = set()
+    py = idx.text.get("pyproject.toml", "")
+    for m in re.finditer(r'"([A-Za-z][A-Za-z0-9_.-]*)\s*(?:[><=~!^\[ ]|")', py):
+        name = m.group(1)
+        if ":" not in name and "/" not in name:
+            declared.add(name.lower().replace("-", "_"))
+    for req in ("requirements.txt", "requirements-dev.txt", "requirements.in"):
+        for raw in idx.text.get(req, "").splitlines():
+            line = raw.split("#")[0].strip()
+            m = re.match(r"([A-Za-z0-9_.-]+)", line)
+            if m:
+                declared.add(m.group(1).lower().replace("-", "_"))
+    return declared
+
+
+def check_dependencies(idx: FileIndex) -> list:
+    if not idx.py_ast:
+        return []
+    has_manifest = any(p in idx.text for p in
+                       ("pyproject.toml", "requirements.txt", "setup.py"))
+    local_tops = {p.split("/")[0] for p in idx.py_ast} | \
+                 {_py_module_name(p).split(".")[0] for p in idx.py_ast}
+    stdlib = getattr(sys, "stdlib_module_names", set())
+    used = set()
+    for rel, tree in idx.py_ast.items():
+        # tests, examples, tools, and packaging scripts have their own dep
+        # conventions (pytest, setuptools, demo-only libs) — library code is
+        # what install-time declarations must cover.
+        if (idx.is_testish(rel) or rel.startswith(("examples/", "tools/",
+                                                   "scripts/", "docs/"))
+                or rel in ("setup.py", "conftest.py")):
+            continue
+        # imports wrapped in try/except are the deliberate optional-dependency
+        # pattern — they must not count as hard requirements.
+        guarded: list = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Try) and node.handlers and node.body:
+                start = node.body[0].lineno
+                end = getattr(node.body[-1], "end_lineno", start)
+                guarded.append((start, end))
+
+        def _is_guarded(n):
+            ln = getattr(n, "lineno", None)
+            return ln is not None and any(s <= ln <= e for s, e in guarded)
+
+        for node in ast.walk(tree):
+            if _is_guarded(node):
+                continue
+            if isinstance(node, ast.Import):
+                used |= {a.name.split(".")[0] for a in node.names}
+            elif isinstance(node, ast.ImportFrom) and node.module \
+                    and not node.level:
+                used.add(node.module.split(".")[0])
+    third_party = {u for u in used
+                   if u not in stdlib and u not in local_tops and u != "__future__"}
+    if not third_party:
+        return []
+    declared = _declared_deps(idx)
+    undeclared = sorted(
+        u for u in third_party
+        if u.lower() not in declared
+        and _IMPORT_TO_DIST.get(u.lower(), u.lower()).replace("-", "_")
+        not in declared)
+    out = []
+    if undeclared and has_manifest:
+        out.append(Finding(
+            check="undeclared_deps", severity="high",
+            title=f"{len(undeclared)} imported package(s) not declared",
+            detail="Imported but missing from pyproject/requirements: "
+                   + ", ".join(undeclared),
+            advice="Declare them with versions. 'Works on my machine' is "
+                   "exactly this bug.",
+            paths=[]))
+    elif third_party and not has_manifest:
+        out.append(Finding(
+            check="no_dependency_manifest", severity="high",
+            title="Third-party imports but no dependency manifest",
+            detail="Uses " + ", ".join(sorted(third_party)[:10]) +
+                   " but there is no pyproject.toml or requirements.txt.",
+            advice="Add a pyproject.toml (preferred) listing dependencies "
+                   "with version bounds so anyone can install and run this.",
+            paths=[]))
+    return out
+
+
+# ── Single source of truth ────────────────────────────────────────────────────
+
+_VERSION_RE = re.compile(
+    r"""(?:__version__|version)\s*[=:]\s*["'](\d+\.\d+[^"']*)["']""")
+
+
+def check_version_truth(idx: FileIndex) -> list:
+    seen: dict = {}
+    for rel in ("pyproject.toml", "setup.py", "setup.cfg", "package.json"):
+        if rel in idx.text:
+            m = _VERSION_RE.search(idx.text[rel])
+            if m:
+                seen[rel] = m.group(1)
+    for rel, tree in idx.py_ast.items():
+        if rel.endswith("__init__.py"):
+            m = _VERSION_RE.search(idx.text[rel])
+            if m:
+                seen[rel] = m.group(1)
+    if len(seen) <= 1:
+        return []
+    values = set(seen.values())
+    if len(values) > 1:
+        return [Finding(
+            check="version_mismatch", severity="high",
+            title="Version strings disagree across files",
+            detail="; ".join(f"{k} = {v}" for k, v in sorted(seen.items())),
+            advice="Pick one source of truth (pyproject.toml) and read it "
+                   "everywhere else. A mismatched release is a support "
+                   "nightmare.",
+            paths=sorted(seen))]
+    if len(seen) > 2:
+        return [Finding(
+            check="version_duplication", severity="low",
+            title=f"Version string duplicated in {len(seen)} files",
+            detail="; ".join(sorted(seen)) + f" (all = {values.pop()})",
+            advice="They agree today; they won't forever. Single-source it.",
+            paths=sorted(seen))]
+    return []
+
+
+# ── Ship essentials ───────────────────────────────────────────────────────────
+
+def check_ship_essentials(idx: FileIndex) -> list:
+    has = {f.lower() for f in idx.files}
+    tops = {f.split("/")[0].lower() for f in idx.files}
+    missing = []
+    if not any(h.startswith("readme") for h in tops):
+        missing.append(("README", "No README — the first thing every user, "
+                        "contributor, and future-you needs."))
+    if not any(h.startswith("license") for h in tops):
+        missing.append(("LICENSE", "No license file — legally, nobody can "
+                        "use or contribute to this."))
+    if ".gitignore" not in tops:
+        missing.append((".gitignore", "No .gitignore — caches, venvs, and "
+                        "secrets will end up committed."))
+    has_tests = any(idx.is_testish(p) and p.endswith((".py", ".js", ".ts"))
+                    for p in idx.files)
+    if idx.code_paths() and not has_tests:
+        missing.append(("tests", "No tests found anywhere. Untested code "
+                        "can't be changed safely, which means it can't be "
+                        "maintained."))
+    has_ci = any(p.startswith(".github/workflows/") for p in idx.files)
+    if has_tests and not has_ci:
+        missing.append(("CI workflow", "Tests exist but nothing runs them "
+                        "automatically — they will rot."))
+    out = []
+    for name, why in missing:
+        sev = "high" if name in ("LICENSE", "tests", "README") else "medium"
+        out.append(Finding(
+            check=f"missing_{name.lower().replace(' ', '_').lstrip('.')}",
+            severity=sev, title=f"Missing: {name}", detail=why,
+            advice=f"Add {name} before sharing or deploying this project."))
+    return out
+
+
+# ── TODO debt + broken Python ─────────────────────────────────────────────────
+
+_TODO_RE = re.compile(r"\b(TODO|FIXME|HACK|XXX)\b")
+
+
+def check_todo_debt(idx: FileIndex) -> list:
+    count, files = 0, set()
+    for rel in idx.code_paths():
+        n = len(_TODO_RE.findall(idx.text[rel]))
+        if n:
+            count += n
+            files.add(rel)
+    if count < 10:
+        return []
+    return [Finding(
+        check="todo_debt", severity="low",
+        title=f"{count} TODO/FIXME/HACK markers across {len(files)} files",
+        detail="High marker density usually means known problems are being "
+               "carried instead of fixed or ticketed.",
+        advice="Triage: fix the quick ones, file issues for the real ones, "
+               "delete the stale ones.",
+        paths=sorted(files)[:15])]
+
+
+def check_broken_python(idx: FileIndex) -> list:
+    if not idx.py_bad:
+        return []
+    return [Finding(
+        check="syntax_errors", severity="high",
+        title=f"{len(idx.py_bad)} Python file(s) do not even parse",
+        detail=", ".join(idx.py_bad[:10]),
+        advice="These can't run. Fix or delete them — shipped trees should "
+               "contain only working code.",
+        paths=idx.py_bad)]
+
+
+# ── Orchestration ─────────────────────────────────────────────────────────────
+
+ALL_CHECKS = [
+    check_broken_python, check_secrets, check_dead_modules,
+    check_dependencies, check_version_truth, check_error_handling,
+    check_duplication, check_import_cycles, check_oversized,
+    check_junk_files, check_debug_residue, check_ship_essentials,
+    check_todo_debt,
+]
+
+
+def scan_project(root: str) -> ScanResult:
+    idx = FileIndex(root)
+    findings: list = []
+    for check in ALL_CHECKS:
+        try:
+            findings.extend(check(idx))
+        except Exception as exc:                       # a check must never kill the scan
+            findings.append(Finding(
+                check="scanner_error", severity="info",
+                title=f"Check {check.__name__} failed on this tree",
+                detail=f"{type(exc).__name__}: {exc}",
+                advice="Please report this at the preflight issue tracker."))
+    findings.sort(key=lambda f: (SEVERITY_ORDER.get(f.severity, 9), f.check))
+    score = 100
+    for f in findings:
+        score -= SEVERITY_PENALTY.get(f.severity, 0)
+    score = max(5, score)
+    grade = ("ready to ship" if score >= 90 else
+             "close — one cleanup pass" if score >= 75 else
+             "needs real cleanup before shipping" if score >= 50 else
+             "not ready to ship")
+    return ScanResult(root=idx.root, findings=findings,
+                      files_scanned=len(idx.files),
+                      code_files=len(idx.code_paths()),
+                      total_lines=idx.total_lines, score=score, grade=grade)

preflight/cli.py

@@ -0,0 +1,102 @@
+"""preflight CLI.
+
+    preflight                 # scan the current directory
+    preflight path/to/project # scan a project
+    preflight demo            # build a deliberately messy demo project & scan it
+    preflight . --json out.json --out report.md
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+
+from . import __version__
+from .checks import scan_project
+from .report import render_markdown, render_terminal
+
+
+def _make_demo_project() -> str:
+    """A tiny, deliberately messy project so `preflight demo` shows real output."""
+    root = tempfile.mkdtemp(prefix="preflight_demo_")
+    pkg = os.path.join(root, "myapp")
+    os.makedirs(pkg)
+    w = lambda rel, s: open(os.path.join(root, rel), "w").write(s)
+    w("myapp/__init__.py", "__version__ = '1.0.0'\n")
+    w("myapp/main.py",
+      "from . import utils\n\ndef run():\n    try:\n        utils.go()\n"
+      "    except:\n        pass\n")
+    w("myapp/utils.py", "def go():\n    return 1\n")
+    w("myapp/old_helpers.py", "def forgotten():\n    return 'dead code'\n")
+    w("myapp/final_v2.py", "x = 1\n")
+    # the demo project deliberately contains a fake committed key so the
+    # secrets check has something to find  (preflight:ignore on THIS line
+    # only — the generated file itself must be flagged)
+    w("config.py",
+      "API_KEY = 'sk-" + "demo0" * 6 + "'\n")  # preflight:ignore
+    w("setup.py", "version='1.2.0'\n")
+    open(os.path.join(root, ".DS_Store"), "w").close()
+    return root
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="preflight",
+        description="Scan a codebase the way a senior engineer skims it: "
+                    "dead weight, duplication, slop, and what's missing "
+                    "before it can ship. Offline, zero dependencies, no LLM.")
+    ap.add_argument("path", nargs="?", default=".",
+                    help="project directory to scan (or 'demo')")
+    ap.add_argument("--out", default=None,
+                    help="markdown report path "
+                         "(default: preflight_report.md in the scanned dir)")
+    ap.add_argument("--json", dest="json_path", default=None,
+                    help="also write machine-readable JSON here")
+    ap.add_argument("--quiet", action="store_true",
+                    help="print only the score line")
+    ap.add_argument("--fail-under", type=int, default=None, metavar="N",
+                    help="exit nonzero if score < N (for CI gates)")
+    ap.add_argument("--version", action="version",
+                    version=f"preflight {__version__}")
+    args = ap.parse_args(argv)
+
+    target = args.path
+    if target == "demo":
+        target = _make_demo_project()
+        print(f"Built a deliberately messy demo project at {target}\n")
+
+    if not os.path.isdir(target):
+        print(f"preflight: not a directory: {target}", file=sys.stderr)
+        return 2
+
+    result = scan_project(target)
+
+    out_path = args.out or os.path.join(result.root, "preflight_report.md")
+    try:
+        with open(out_path, "w", encoding="utf-8") as fh:
+            fh.write(render_markdown(result))
+        wrote = out_path
+    except OSError as exc:
+        wrote = None
+        print(f"preflight: could not write report ({exc})", file=sys.stderr)
+
+    if args.json_path:
+        with open(args.json_path, "w", encoding="utf-8") as fh:
+            json.dump(result.to_dict(), fh, indent=2)
+
+    if args.quiet:
+        print(f"{result.score}/100 — {result.grade}")
+    else:
+        print(render_terminal(result))
+        if wrote:
+            print(f"\n  Markdown report written to: {wrote}\n")
+
+    if args.fail_under is not None and result.score < args.fail_under:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

preflight/report.py

@@ -0,0 +1,79 @@
+"""Render a ScanResult for terminals and as a markdown report file."""
+from __future__ import annotations
+
+from .checks import ScanResult
+
+_SEV_LABEL = {"high": "HIGH", "medium": "MED ", "low": "low ", "info": "info"}
+_SEV_EMOJI = {"high": "🔴", "medium": "🟠", "low": "🟡", "info": "ℹ️"}
+
+
+def render_terminal(result: ScanResult) -> str:
+    lines = []
+    lines.append("")
+    lines.append(f"preflight — {result.root}")
+    lines.append(f"{result.files_scanned} files · {result.code_files} code "
+                 f"files · {result.total_lines:,} lines of code")
+    lines.append("")
+    lines.append(f"  SHIP-READINESS SCORE: {result.score}/100 — {result.grade}")
+    lines.append("")
+    if not result.findings:
+        lines.append("  No findings. Genuinely clean tree — ship it.")
+        return "\n".join(lines)
+    for f in result.findings:
+        lines.append(f"  [{_SEV_LABEL.get(f.severity, '????')}] {f.title}")
+        for d in f.detail.splitlines():
+            lines.append(f"         {d}")
+        lines.append(f"         fix -> {f.advice}")
+        lines.append("")
+    high = sum(1 for f in result.findings if f.severity == "high")
+    med = sum(1 for f in result.findings if f.severity == "medium")
+    lines.append(f"  {len(result.findings)} finding(s): {high} high, {med} "
+                 f"medium. Full report: see the markdown file.")
+    return "\n".join(lines)
+
+
+def render_markdown(result: ScanResult) -> str:
+    out = []
+    out.append("# preflight report")
+    out.append("")
+    out.append(f"**Project:** `{result.root}`  ")
+    out.append(f"**Scanned:** {result.files_scanned} files, "
+               f"{result.code_files} code files, "
+               f"{result.total_lines:,} lines of code")
+    out.append("")
+    out.append(f"## Ship-readiness: {result.score}/100 — {result.grade}")
+    out.append("")
+    if not result.findings:
+        out.append("No findings. Clean tree.")
+        return "\n".join(out) + "\n"
+    out.append("| Severity | Finding |")
+    out.append("|---|---|")
+    for f in result.findings:
+        out.append(f"| {_SEV_EMOJI.get(f.severity, '')} {f.severity} | "
+                   f"{f.title} |")
+    out.append("")
+    out.append("## Findings and how to fix them")
+    for f in result.findings:
+        out.append("")
+        out.append(f"### {_SEV_EMOJI.get(f.severity, '')} {f.title}")
+        out.append("")
+        out.append(f.detail)
+        out.append("")
+        out.append(f"**Fix:** {f.advice}")
+        if f.paths:
+            out.append("")
+            shown = f.paths[:20]
+            out.append("<details><summary>Files "
+                       f"({len(f.paths)})</summary>\n")
+            for p in shown:
+                out.append(f"- `{p}`")
+            if len(f.paths) > 20:
+                out.append(f"- … and {len(f.paths) - 20} more")
+            out.append("\n</details>")
+    out.append("")
+    out.append("---")
+    out.append("*Generated by [preflight](https://github.com/<you>/preflight) "
+               "— static heuristics, zero LLM calls, runs entirely on your "
+               "machine. A finding is a prompt for human judgment, not a "
+               "verdict.*")
+    return "\n".join(out) + "\n"

preflight_scan-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+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.

preflight_scan-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+preflight/__init__.py,sha256=GGsFsgouFCR9ELj2SRNV0lxAPvyqAUWg7uFYSwj3ey8,539
+preflight/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+preflight/checks.py,sha256=c-BHsUGAbz0cVgWvylKz0IOXCY_6gfOr1Pvv4sEcSkI,32793
+preflight/cli.py,sha256=NAU2t2e7Ah0ueej8KU5JBPv_hJRu7ffFXSXU7igWkNw,3814
+preflight/report.py,sha256=SwKv4-H6R4m8ZRrtUyry9wwERGgA1mixhVeojIhtnnY,3216
+preflight_scan-0.1.0.dist-info/licenses/LICENSE,sha256=O38j1kjHtcE2yoFaMd_m-9FBKJ0u0q6HXeCZ1_YDIMo,1072
+preflight_scan-0.1.0.dist-info/METADATA,sha256=HQlmhL3HI_b9DmJlTvqSN7QjtLZgen3VkrEXHmeQnew,4809
+preflight_scan-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+preflight_scan-0.1.0.dist-info/entry_points.txt,sha256=VcW1tXHanw5ExFiAv-nHrUeDFl0-p85MiGw2YhnnI30,49
+preflight_scan-0.1.0.dist-info/top_level.txt,sha256=ounnrNnQ8yH4uQJrLFyVEB5GGGMW4lQUBqjti6ra2VE,10
+preflight_scan-0.1.0.dist-info/RECORD,,

preflight_scan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

preflight_scan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+preflight = preflight.cli:main

preflight_scan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wellness Agents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

preflight_scan-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+preflight