Skip to content
ROLLCALL

Register 1.2.0 part of the Wayne State app stack

Menu

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.json from the raw-PHP endpoint matches the same schema.
  • Every stored snapshot matches snapshot.schema.json, and its schema_version equals 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=json matches digest.schema.json, and rollcall owners --format=json matches owners-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 owner field 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 unknown schema_version or with an owner, 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 without no_owner_on_file, and an owners check with a rank.
  • 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: false throughout, 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 apps or scan_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.