Skip to content

core: list the subjects in the report - #245

Merged
jbpros merged 2 commits into
mainfrom
core/report-subjects
Oct 17, 2026
Merged

jbpros merged 2 commits into
mainfrom
core/report-subjects

Conversation

@jbpros

@jbpros jbpros commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

First of three PRs for #244 (decision 6 there). A report now says where each subject comes from: a top-level subjects section, and subject on each requirement.

With this input:

{"deployments": [
  {"id": "d-1", "environment": "prod", "approved_by": "alice"},
  {"id": "d-2", "environment": "staging"}
]}

and this policy:

subjects:
  deployment:
    description: Something we ship
    from: deployments
    identified_by: id
  prod deployment:
    from: deployment whose environment is "prod"
  release:
    from: releases
requirements:
  approved:
    subject: prod deployment
    checks:
      approved: approved_by is a non-empty string

the report has "subject": "prod deployment" on the requirement, and (from opa eval):

"subjects": {
  "deployment": {"description": "Something we ship", "from": "deployments", "identified_by": "id", "parts": {}},
  "prod deployment": {"description": "", "from": "deployment whose environment is \"prod\"", "identified_by": "id", "parts": {}}
}
  • Which subjects are listed: the ones a requirement uses, plus any subject they narrow or descend from, all the way back. release isn't listed because no requirement uses it.
  • from and identified_by are printed as sentences. A narrowing subject has the id of the subject it narrows.
  • parts is always {} for now. The third PR fills it.
  • Old syntax: a from written as a list is printed as its path, then whose and its applies_to filters sorted by name. Anything with no sentence form shows in angle brackets, so it's never left out: a filter with a custom operator or a substitute is <condition name>, a naming step with listed keys is <each of "a", "b">, and one with no keys is <each as it>. A naming step whose keys come from a ref prints as named by each of $params.suites.
  • Written wrong: a from or id written wrong shows as <invalid from> or <invalid identified_by>, and the subject is still listed.

Changes the report: every report has subjects, and every requirement entry has subject.

Checks

  • Every check in AGENTS.md passes: 1290 tests, no uncovered lines, 1118 spec cases.
  • The JS Wasm runtime passes within its budgets: 12.4 MB and 10.6 MB.
  • Reports from main and from this branch, on every spec case from main and every corpus line on two inputs (1740 reports), are identical once subjects and subject are removed.
  • pr-reviewer's review-controls report takes 0.33 s against 0.32 s on main.
  • I didn't run the Wasm suite in Docker.

🤖 Generated with Claude Code

The report now has a top-level `subjects` section with one entry for each
subject a requirement uses, including the subjects it narrows or reads from.
Each entry has the subject's `description`, a `from` sentence that says how
it is found, its `identified_by` path (or null), and an empty `parts`. A
subject written wrong still gets an entry, with `<invalid from>` or
`<invalid identified_by>`. Each requirement entry also has `subject`, the
name of the subject it checks, or null when it names none or one that isn't
in the policy.

Subjects written as lists are printed as sentences too. An old-syntax filter
that can't be a sentence is shown as `<condition name>` instead of being
left out.

Changes the report: every report has a new top-level `subjects` key and every
requirement entry has a new `subject` field.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@jbpros jbpros added enhancement New feature or request core Relates to the ergo library or format themselves. impacts-ergo-reports Impacts ergo report schema. Careful design attention needed. labels Oct 17, 2026
A naming step with keys listed, or with no keys, has no from-line form,
so it was left out of the printed from. It's now shown in angle
brackets, like a filter with no sentence form: <each of "a", "b"> and
<each as it>. One whose keys come from a ref prints as named by each of,
whatever its alias.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jbpros
jbpros marked this pull request as ready for review October 17, 2026 21:37
@jbpros
jbpros merged commit 4ee2835 into main Oct 17, 2026
7 checks passed
@jbpros
jbpros deleted the core/report-subjects branch October 17, 2026 21:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

core Relates to the ergo library or format themselves. enhancement New feature or request impacts-ergo-reports Impacts ergo report schema. Careful design attention needed.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant