Contract#
This page covers the shapes Rollcall promises to anyone who reads its output. Next: the Proof of a real run.
The contract lives in contract/ as JSON Schema
(draft 2020-12). tests/ContractTest.php runs the real commands on the fixtures, then validates what they print and
store against these files, so the code and the contract cannot drift apart. A dashboard, a Grafana import, ADVISOR
or a script should read Rollcall against these schemas, not against an example it once saw.
| Schema | What it describes | Who produces it |
|---|---|---|
report.schema.json |
rollcall report --format=json and GET /report.json, public and internal views |
Rollcall |
snapshot.schema.json |
One stored scan, <ROLLCALL_STORE_DIR>/<date>.json (internal: it holds app ids) |
Rollcall |
images-export.schema.json |
The image list behind ROLLCALL_IMAGES_FILE |
Any platform, or a hand-kept file |
citadel-export.schema.json |
The Citadel registrations export behind ROLLCALL_CITADEL_EXPORT |
A person or a job, from Citadel |
owners.schema.json |
The owners file behind ROLLCALL_OWNERS_FILE: Rollcall's own owners.json (roles only) or a fleet's own (internal) |
The people who run Rollcall |
digest.schema.json |
rollcall digest --format=json (internal: it names apps) |
Rollcall |
owners-check.schema.json |
rollcall owners --format=json, the latest scan checked against the owners file (internal: it names apps) |
Rollcall |
What the suite checks#
- The public and internal JSON reports, after one scan and after two, match
report.schema.json. GET /report.jsonfrom the raw-PHP endpoint matches the same schema.- Every stored snapshot matches
snapshot.schema.json, and itsschema_versionequals the code's. - The image list, Citadel export and owners fixtures, and Rollcall's own
owners.json, match their input schemas, a report and snapshot built from the Citadel export match theirs,rollcall digest --format=jsonmatchesdigest.schema.json, androllcall owners --format=jsonmatchesowners-check.schema.json. - The drift kinds in the schema are exactly the ones the report builder counts, in the same order.
- The schema has teeth: a public report with a per-app list, an
ownerfield or a made-up drift kind is refused, and so is an internal report without its list. Every other schema refuses a case too: a snapshot of an unknownschema_versionor with anowner, an image entry without its image, a Citadel upgrade whose date is not a date, an owner without a contact or with a project that is not a group/project path, a digest withoutno_owner_on_file, and an owners check with arank. - Every schema in
contract/is validated against real output or a fixture and has a case it must refuse, or the suite fails, so a new schema cannot land unchecked.
It reads fixtures only and never calls GitLab, Citadel or any other host. Run it alone with
vendor/bin/phpunit tests/ContractTest.php; composer ci runs it with everything else.
Rules#
- Closed objects. Rollcall's own output uses
additionalProperties: falsethroughout, so a new field is a contract change made in the same commit as the code. Inputs stay open: a producer may add fields of its own, and Rollcall ignores them. - Public means counts. The public report may never carry
appsorscan_errors, and no field holds an owner, a rank or a score. - Versioning. From 1.0.0 on, Rollcall follows SemVer against this contract: an added field or enum value is a
minor release; a removed or renamed field or a changed type is a major release. A snapshot carries its own
schema_version(1 today), and a reader refuses a version it does not know.