Glossary

The words obelize uses, in the sense it uses them. Where a term has a page of its own, the entry links to it.

Migration pack

A data file that describes one migration between two versions of a library: which symbols to find, which rule kind handles each, and what backs it: the official guide for a bundled pack, the public API of the two releases for one that pack synth made. A pack holds no code. obelize parses it with a closed schema and never executes it. The format is in Pack format, and the three that ship are in Packs.

Rule kind

One of the fixed ways obelize rewrites code, such as renaming an import or moving a call to a client object. A pack chooses a rule kind for each change it declares, and the rewrite itself lives in obelize, not in the pack.

Codemod

An automated, mechanical edit of source code. obelize's codemods are written with libcst, so an edit keeps the formatting and comments around it.

Scan

A read-only pass that lists every import, call and dependency line the migration affects, and for each whether obelize can migrate it. obelize scan edits nothing.

Dry run

What obelize fix does until you pass --apply: it prints the plan and the diff and writes only its own record under .obelize/.

Apply

obelize fix --apply. It writes the files on the plan, each through a temporary file and a rename, and records what it did so that obelize undo can put the files back.

Withheld

A place obelize found and did not rewrite. Each withheld place carries a reason, so you can fix it by hand or hand it to an agent. A file is written only when everything in it can be migrated, so one withheld place holds back its whole file.

Reason

The closed-vocabulary code that says why a place was withheld, such as usage_unmapped or file_not_fully_migrated. Scan vocabulary lists every reason and what to do about it.

Baseline

Your verification command run on the code as it was before the change. A run is verified only when the baseline passed.

Verified

A run is verified when the command you gave to --verify passed before the change (the baseline) and still passes after it. Verified describes your tests agreeing with the change. It does not prove the migrated code behaves the same where no test looks.

Run folder

The .obelize/runs/<id>/ directory every fix writes: the plan, the patch, the verification logs and REPORT.md. The run folder lists each file.

Library, SDK and distribution

A library is code you import. An SDK is a library a service publishes to be called from your code, such as google-generativeai. A distribution is the package pip installs, and its name can differ from the name you import: the distribution google-genai provides the module google.genai. obelize reads both, because an import and a dependency line must move together.