# Reviewing a policy change

A one-line change can widen access across many permissions, and its text doesn't show that. `rowstile review`
says what a change does, in plain words, for the pull request:

    rowstile review --base main                          # in a terminal
    rowstile review --base main --markdown --db "$URL"   # the comment CI posts

- **Meaning**: each declaration that changed, before and after, and every permission and rule that changes
  through something it uses.
  When only permissions and rules changed, each is checked against the base in
  many small worlds (made-up users, objects and links, [`core/authzlib/evaluate.py`](https://github.com/rowstile/rowstile/blob/v0.1.0-beta.5/core/authzlib/evaluate.py); among them the ones where
  every condition holds, or where most links do, so a change behind a long `and` shows, and chains of objects
  one link longer than the policies read), and in the worlds of up to three rows of each type, listed with the
  fewest links first, every one with no link or one link among them: each row with every answer its
  conditions can give, so a condition added to a long `and`, or one that must say one thing on a row and another
  on the row it inherits from, shows.
  A number a condition compares a column with in order gets the numbers either side of it and halfway to them
  (`{level > 1}` and `{level >= 2}` differ on 1.5), and an id a condition compares a relation's column with is
  the id of a row there (`{owner_id <> 7}`: a user 7, whose folders it leaves out).
  The listing stops after 3,000 worlds, once those are tried, and after 12,000 whatever: rows whose conditions
  give many answers make many worlds of one link. If they all grant the same, the review says
  "Meaning unchanged", and how far the listing got: "every one of up to 3 rows of each type", with "at most 2
  links" where it stopped there (or "with no link, and some with one", where it stopped before those), and, where
  columns read together take more than 4,096 combinations of values,
  that only the first of them were tried.
  If one world grants otherwise, the review names what differs, for whom and on what, and the comment shows
  that world too.
  It is the first world found, made as small as it still grants otherwise in: each row, link and value it holds
  plays a part.
  Worlds that are bigger, or hold custom roles, are only drawn: for them it is a search, not a proof.
  Formatting and comments are "unchanged" too; text inside quotes is not formatting.
  A
  condition the worlds can't read (a subquery, a function: anything beyond the row's own columns and
  `authz.uid()`; a text compared with a column the policies also compare with a text it may hold as the same
  value, `'a'` beside `'A'` under a case-insensitive collation) is a set of rows of its own there, so when a
  permission or rule changed only in such
  conditions, the review says it can't compare them and names them, instead of guessing.
- **Access**: with `--db`, a database at the base branch's state (its migrations, then the review data,
  prepared by CI; never production), who gains and who loses what if the pull request's policy were in
  force, with examples and how each is granted.
  The database is left as it was.
- **Risk**: what to look at twice: access widened to `anyone`, `link` or `user:*`; a deny removed; a new
  inheritance path or a new way to reach a type; a relation newly shared or shared by another permission; a
  permission or a rule (`select` too) that allows more than before, with an example: because its own line
  changed, because it is new on a table that had rules, through a relation that changed (another column, a
  `where` taken off a link table), or because a type's `where` changed; a mask, a column rule or an invariant
  removed; a `shared if` removed or changed (who a share may name); a caveat changed (what every share made
  with it is held to); a scope changed; a cascade marked as meant (`cascade from`); a sync line added, or
  finding its rows' readers by another permission, or mirrored now (what the sync engine is given).
  A permission's example comes from the small worlds, or with `--db` from Access when the review data shows
  someone gaining it there: a user who had it before isn't named as one who gains it.
  A plain `update after` is compared with the `update` rule that checks in its place: one added that lets more
  rows through after an update, or one removed where `update` lets more through, is flagged.
  A `where` added to a link table, or one that holds for fewer of its rows, allows less, and isn't flagged.
  Each names its policy line; `--annotations` writes them for GitHub, on the file
  the line is in.
  `--out FILE` writes the comment to a file as well, so one review gives both, as the action runs it:
  `rowstile review --annotations --out review.md`.
  "Nothing flagged" means none of these was found in the worlds tried, not a proof.
- **Tests**: checks whose expectation flipped (the author saying "I meant this"), checks removed, new
  permissions no test names.
  A test that only changed its name is said to be renamed, and its checks are
  compared under the new name: a new name alone removes nothing.
  With `--db`, the pull request's tests run
  on the review data after its migrations.
  The checks are listed whatever Meaning says. A test file of the pull request that doesn't parse, or that
  `rowstile test` would refuse with the pull request's policy (a permission it doesn't have, a test another file
  names too), is named, with its mistake: its checks are not compared, nor run, and the review goes on.
- **Deploy**: the migrations the change needs (from the base branch's lock file), their statements, the
  app tables they lock and in which mode, the inheritance tables they rebuild or build beside; with
  `--db`, how long they took on the review data.
  Deploy also names, in words and with the mode it locks them in, the tables a migration finds only as it runs:
  those an inheritance condition reads, and the partitions and child tables made since the last migration, which
  every migration gives rowstile's triggers and, under a table with rules, row-level security.
  A lock file behind the policy is called out. With no lock
  file on either side, the project applies its policy (`rowstile apply`) and keeps no migrations: Deploy says so.

The pull request that adds the policy has none at the base. Each declaration is listed as added, the app role
and the user type too, and the review compares with a policy that allows nothing.
A base whose policy has a mistake is reviewed the same way, so the pull request that fixes it gets a review too:
it says first that the base has a mistake, with its line there and its code, in the text, the comment and the
annotations (`--json`: `base_mistake`, with `line`, `message` and `code`), then reviews the policy as new.

[`review-ci/github/action.yml`](https://github.com/rowstile/rowstile/blob/v0.1.0-beta.5/review-ci/github/action.yml) runs it on each pull request and keeps one comment up to date (and the annotations);
[`review-ci/gitlab/rowstile-review.gitlab-ci.yml`](https://github.com/rowstile/rowstile/blob/v0.1.0-beta.5/review-ci/gitlab/rowstile-review.gitlab-ci.yml) does the same for merge requests.
`rowstile fmt --check` in CI
keeps text diffs to real changes.
On GitHub, the workflow may post the comment once it has
`pull-requests: write`, and checks out the history the base branch's policy is read from:

```yaml
on: pull_request
permissions: {contents: read, pull-requests: write}
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with: {fetch-depth: 0}
      - uses: rowstile/rowstile/review-ci/github@v0.1.0-beta.5   # the release you use
```

A pull request from a fork gets a read-only token, whatever the workflow asks for: the review is then in
the run's summary, a notice says so, and the job passes.
Run it on `pull_request` all the same, not on `pull_request_target` ([the threat model](/threat-model.md)
says why). A review longer than a comment may be is cut, and the comment says the whole review is in the run's
summary; on GitLab, in the job's artifact, `review.md`.
On GitLab the note is written with `ROWSTILE_REVIEW_TOKEN`, set in the project's CI/CD settings. Another release
(`ROWSTILE_VERSION`) or another stage than `test` is set in the job, by its name in the including file: the
template's header shows how.

The review reads the base's policy, the files it includes, its tests and its lock file with git. A file the
base doesn't have is new: a policy, or a test file added since.
But when git can't read one the base has, or
can't list the base's folders (a partial clone that can't fetch them, a repository missing objects), the
review stops, exit 2, and says what git can't read and how to fetch it.
Read as missing, the policy would be
reviewed as new and the base's tests left out. So check out the whole history, with no `filter`, as above.

The review reports; it doesn't gate. It exits 0 whatever it finds: a widened permission, a failing test and a
lock file behind the policy are all in what it prints, for a person to read.
(It exits 1 for a pull request whose policy
doesn't compile, 2 when it can't run: no `--base` where there is no `main` or `master` to compare with, a commit
git doesn't know, a file at the base git can't read, a database it can't reach.)
What
fails a pull request is the other two commands CI runs: `rowstile test`, which exits 1 when a check fails, and
`rowstile migrate --check`, which exits 1 when the policy changed and no migration was written.
