mix surfex.migrate (Surfex v0.10.0)

The migration aid (Surfex.Migrate, spec §14.1): moving a section's implements relations to the claims inside it, one section at a time, as work touches it.

mix surfex.migrate spec.md#carts                  # the proposals for one section
mix surfex.migrate spec/08-reclamation.md --within  # every section under a prefix
mix surfex.migrate spec.md#carts --accept          # record the single ones
mix surfex.migrate spec.md#carts --code MyApp.Cart.add/2 --to spec.md#adding
mix surfex.migrate --report                        # every section, worst first
mix surfex.migrate --report spec.md#carts          # what migrating it buys
mix surfex.migrate --report --format json          # the work list, for tools

For each live implements between code and the section (or a table in it), it lists the claims inside the section that could own the code: a row whose key names it (an arity-less key Mod.fun names every arity), a contract unit for it, a claim whose verifying test calls it, or, failing those, one whose test reaches it, through what. Arities of one definition (default arguments) are one proposal. None comes first: code no claim owns is the spec work the migration surfaces, a claim not written yet or code that doesn't belong to the section. Several are listed and never decided: which claim code realises is a judgement. Listing writes nothing.

--accept [--note N] records each single proposal (Surfex.Migrate.accept/4): the code related to its claim, proposed, with migrates naming the section. Such a relation migrates: it doesn't fail the status while the section still holds its relation, so a section can be migrated across several commits. Validate it as any implements, by evidence or a review (mix surfex.validate TEST CLAIM). Once every claim relation of a code item is validated the pair is settled, and the section's relation is retired, noting the claims it moved to: by the next --accept, or by mix surfex.suggest --accept. A section never loses a relation before its claim holds one. --code ID --to CLAIM (--to once per claim) records your choice for a proposal with several candidates, or one with none once its claim is written (Surfex.Migrate.choose/7).

A section relation resting on the baseline (adoption: :trust, mix surfex.baseline) carries it to the claim when the same baselined test, at the version trusted, verifies the claim and exercises the code: the claim relation is recorded with basis baseline, holds at once, and the section's relation retires in the same --accept.

--report is read-only too. Per section: the relations an edit of its text dangles now and after migration, its section-grain implements by outcome, the marking a prose section needs first (the relations one marker line dangles, paid once), and each code item's dangle width now and after, widest after first. With no section, every section holding section-grain implements, worst first, after the population: the sections whose claims are already units (they migrate today) and the prose ones (they need claim forms, spec §11.1).

It is the migration's one work list (spec §14.2): a contained section, one with no verifies of its own while a claim inside it is verified, gets a contained: line naming those claims, and with no section named every contained section is reported, those holding no implements too, with their count in the population. --format json gives the same report as JSON (Surfex.Migrate.json/1).