Skip to main content
preflight answers the question you should ask before letting anything (an agent, a codemod, or Refactron itself) migrate your code: which changes can be proven safe, and which can’t? It scans a codebase for the SQLAlchemy 1.x Model.query pattern (the 1.x→2.0 select() migration), checks how well your tests cover each site, and returns a per-site verdict: safe to automate, unproven, or needs review. It reports; it does not rewrite.
Preflight is coverage-aware by design. High-stakes migrations fail silently (wrong behavior in production, not a compile error), so “can we even prove this?” is the first question. Preflight is that question, answered before any change is made.

​
Install (from source)

preflight is unreleased; it is not in refactron@0.2.4 on npm. Build from source until the next release, which ships the refactron bin.

​
Run it

target defaults to .. Preflight is auth-gated: run node dist/cli/index.js login, or set REFACTRON_TOKEN in CI. An unauthenticated run exits 7.

​
Flags

​
Exit codes

​
Reading the report

Every detected Model.query site is bucketed by how confidently it could be migrated:
  • Safe to automate: the site is covered by your tests, so a migration here can be verified end to end.
  • Unproven: the pattern is present, but your tests don’t exercise it. A migration would be an UNPROVEN change: possibly fine, but unproven. Add a test first.
  • Needs review: the site has a shape the automated path won’t handle safely; a human should migrate it.
Coverage is measured with coverage.py, so preflight’s coverage signal is Python-only. That matches its scope: SQLAlchemy is a Python library.

​
Why report-only

Refactron ships no SQLAlchemy auto-rewriter. A pre-build safety gate on the migration returned a stop signal on the auto-rewrite premise: on the target corpora, too many Model.query sites lacked the coverage needed to verify a rewrite. Automating a change you can’t prove is exactly the failure this project exists to prevent, so preflight tells the truth about what’s verifiable instead of rewriting on faith. That makes preflight the honest front end of a migration: it draws the line between the sites an agent can safely take and the sites that need a person, before a single line is changed.

​
Next

Verdicts

The SAFE / UNSAFE / UNPROVEN model preflight’s buckets map onto.

Verify a diff

Once a migration is written, prove the diff preserved behavior.