How it works

mirago is deliberately small and cautious. Here's exactly what happens when you run a check.

1. It reads your code

mirago parses each file with Python's built-in ast module. That means it understands the structure of your code without ever running it, and extracts every package you import.

2. It checks each package against PyPI

Every imported package name is checked against the official Python Package Index. Lookups are cached on disk for 7 days (via platformdirs), so repeated runs are fast and polite to PyPI.

3. It grades each package: error, warning, or fine

mirago turns existence and metadata into a graded verdict:

• Doesn't exist on PyPI → error. The AI made the name up — a hallucination.
• Exists and is in your lockfile → fine. A package you already declare is trusted; mirago never warns about it.
• Exists, created < 30 days ago, and < 100 downloads/month → warning. A possible copycat ("slopsquat").
• Anything else → fine, and mirago stays quiet.

Both registry signals must fire together. Being merely new, or merely low-download, or merely not-in-your-lockfile is never enough on its own to raise a warning.

Built not to cry wolf — "fail-open"

Every missing or unknown signal is treated as safe. If PyPI can't be reached, or download stats are unavailable, mirago counts that as "fine" rather than manufacturing a warning. A network or stats outage can never turn into a false alarm.

False alarms are what make people uninstall a tool — so this caution is the whole point. (The warning thresholds above are provisional; user-tunable configuration is planned for a later release.)

"Did you mean?" suggestions

When a name doesn't exist, mirago tries to suggest the package you probably meant — matching against a bundled list of popular packages with Python's standard-library difflib. The corpus is deliberately popular-only and offline: suggesting an obscure package could itself nudge you toward a typosquat. Run with --fix to apply a suggestion interactively.

What it doesn't catch yet

• Fake function or method names inside real packages.
• Editor / IDE integrations (mirago is a command-line tool for now).
• Catching mistakes live, as an AI assistant writes them.

See the project roadmap for where this is heading.