How a release's facts, change record and fingerprints are worked out

This is the detail behind What a release shows, The changelog, Search and The verifier: what jadpo package check prints above its bar, and what jadpo package verify --json writes.

The facts cover what the code can do. An operation of a resource the package keeps to itself reaches the host and can change something there as much as a public one does, so hosts and changing_calls list every operation, and a hostile release can't hide a call behind a public action. hosts are the provider's hosts: and each asks host, or "the service Jadpo runs" and "the address its connection gives" where it names none. Each marked field is listed for each host it reaches, with its operation and categories, and decided_only when the value only decides what is sent. storable_types are every public type of a library package, and of a provider's only the plain values, never an object or an enum. standard_candidates are package.standard_candidate's findings on the package's types, which a package that compiles has declined. last_contract_run and the Jadpo releases it works with are the registry's to add, so verify writes null for the first and leaves out the second.

The change record. It compares the surface with the last release's: a new entry is added, one gone removed, a new fails line new_failure, a new host new_host on provider, and any other change to an entry's facts one retyped, whose detail says what it says now and what it said (max_length: 30, was max_length: 20). Descriptions, files, sources and recordings alone aren't changes. Comparing the two releases' facts gives personal_data_sent, once per field and host. A last release this Jadpo can't compile has no facts, so everything now sent counts as new. jadpo package check writes CHANGELOG.md's list from these entries, a line each, and a first release's list is "first release".

The previous release's examples and tests run in a scratch app of their own: the new package's files without its own tests, and the last release's .test.jadpo files and description examples placed beside them. A release at a tag is read from git; verify is given its folder. Each one that fails is a behaviour_changed entry, whose detail is its name and whose declaration is the public call it makes, on the line that failed if it can tell. One that no longer compiles has failed too, so a release can't hide a change by removing a helper an old test leans on. Recordings aren't run again: the new package's own are, by the bar.

A fix is a line beneath the new version's list in CHANGELOG.md, Fix `uk.parse`: why it had to change, naming the entry's declaration. It says why as well, so it needs no other text, and its reason is the entry's why. A mark with no reason is no mark. Without one, the bar's behaviour row fails with publish.behaviour_changed. While the version row itself is refused the behaviour row waits, since a breaking change usually fails those examples too.

A new major version is compared with the newest release of any label of the package's name in code, so Postcodes.v3's first release shows what changed since Postcodes.v2's last. Its version is still the one its label names, nothing in the change record refuses it, and its behaviour row says "a new major".

jadpo package verify <folder> [--previous <folder>] is this bar on a commit as it stands: it writes nothing, and reads no git tags. A surface row checks the committed surface.jadpo_record against the code, and the changelog row checks the list under the version's heading against the change record, each publish.stale_files when it differs. The previous folder's version is the one its committed surface says, and it has to be a release of the same name in code. With no --previous it is a first release. Its JSON holds package, version, passed, bar, surface (the record's text), facts, change_record, fingerprints, previous (since, ran, each failed) and jadpo, the release it was checked with. Its screen is check's, without the Wrote line or the hint, and its footer counts the fingerprints.

Fingerprints. Each public declaration has source, the SHA-256 of its tokens as the formatter writes them, leaving out its description, comments, visibility, decline lines and its own name. A function's or action's parameters and variables are named by their position, as the similar-helper check names them, so a renamed and reformatted copy has the same source. A type's fields keep their names, since they are what it is. Each operation, action and function also has shape: inputs and output reduced to standard types and their constraints (Text { max_length: 20, min_length: 5 }, { note: Text?, outward: Text }, Enum { england, wales }, with … where a type comes round to itself), failures reduced to their kinds, effects (calls, changes), and a digest of those for an exact match. A recipe has none: it isn't part of the compiled package.

What check prints, for a provider package with a release behind it:

text

$ jadpo package checkFacts  kind      provider  hosts     https://api.acme-pay.example            https://sandbox.acme-pay.example  changes   customers.create  erasure   not declared  storable  CustomerId  failures  none  contract  1 of 2 operations confirmedPersonal data sent  to https://api.acme-pay.example  to https://sandbox.acme-pay.example  customers.create  CustomerRequest.notes  health, sensitiveChanges since 1.0.0  + new host       provider          https://sandbox.acme-pay.example  + personal data  customers.create    CustomerRequest.notes to https://sandbox.acme-pay.examplePublishing bar...

A row is left out only where the package's kind can't have it, so a library's block is its kind, what an app may store and what can fail, and standard shows only when there is one. jadpo package show prints the same block, and --json holds every fact whole, with each host's operations.