# Commands for records, findings and review

Some files in your project are records: files Jadpo writes for you to
commit, such as the record of your public API, which a reviewer reads in a
pull request ([Review and records](/docs/records-and-manifest.md)). These
commands keep them current, and deal with the findings `jadpo check`
leaves for a person or an agent to settle.

| Command | Does |
|---|---|
| `jadpo api update` | Rewrites the committed record of each public API |
| `jadpo records` | Lists every committed record and flags any out of date |
| `jadpo acceptance new` | Drafts a person's acceptance of the changes that need one |
| `jadpo approval` | Writes the report a reviewer reads: what a change does, decisions first |
| `jadpo declines list` / `clear` | Lists or removes your declines |
| `jadpo fix` | Applies the fix you pick for a finding |
| `jadpo suggest` | Hints where code could use a standard type or operation |

| Command | What it does |
|---|---|
| [`jadpo api`](/docs/jadpo-api.md) | Rewrite the API records. |
| [`jadpo records`](/docs/jadpo-records.md) | List and update the records. |
| [`jadpo acceptance`](/docs/jadpo-acceptance.md) | Draft a person's acceptance. |
| [`jadpo approval`](/docs/jadpo-approval.md) | Explain a change, decisions first. |
| [`jadpo declines`](/docs/jadpo-declines.md) | List or clear declines. |
| [`jadpo fix`](/docs/jadpo-fix.md) | Fix a standard type's finding. |
| [`jadpo suggest`](/docs/jadpo-suggest.md) | Hint where a standard type or operation fits. |

## `jadpo api update`

Rewrites the committed record of the public API, `api/main.jadpo_record`,
from the source. It writes one record per API with routes, as
`api/<api>.jadpo_record` in [the record
format](/docs/what-is-committed-and-why.md#the-record-format), and removes the
record of an API that has no routes. A record has no `version:`: the
OpenAPI version is a hash of it.

`jadpo check` fails while a record disagrees with the source
(`record.out_of_date`) or was edited by hand (`record.edited`). A record
under its old name, `api/<api>.api`, is removed.

## `jadpo records`

Lists every committed record (the `.jadpo_record` files and `jadpo.lock`)
grouped by the command that writes it, each with its state. It fails while
one needs its command. `jadpo records update` brings every record up to
date at once and moves records from their old names.

## `jadpo acceptance new`

`jadpo acceptance new <purpose>` writes
`acceptances/<stamp>_<purpose>.jadpo`, listing every change since the
default branch at its merge base that needs a person and that no
acceptance this change adds lists yet, with no reason
([Acceptances](/docs/acceptances.md)). The stamp is the
minute in UTC, as a migration's is. An agent runs it, then stops: a
person writes the reason on a `///` line above `acceptance`, and `jadpo
check` fails until they do.

```text
$ jadpo acceptance new open_the_catalogue
✓ Wrote acceptances/20261030T1400_open_the_catalogue.jadpo
    "main GET /books"    PolicyChange.route_public
    lending.Book.read    PolicyChange.widened

◆ decision  2 changes wait for a person's reason
  at        acceptances/20261030T1400_open_the_catalogue.jadpo:1
  next      Stop and hand over: a person reads the changes and writes why
            they are accepted on a `///` line above `acceptance`. (human)
```

With `--json`, `data` holds the `file`, each change's `subject` and
`change`, and `reason: false`. A purpose that isn't lower_snake_case,
nothing waiting for an acceptance, or nothing to compare with (outside
git, before the first commit) is `cli.acceptance_arguments`; a base the
clone doesn't hold is `acceptance.base_missing`. `--before <branch or
commit>` compares with another base, as `jadpo check`'s does.

## `jadpo approval`

`jadpo approval` writes `build/review/approval.md` and `.json`, the
difference between this change and its before side: the default branch at
its merge base, or the branch or commit `--before <ref>` names, as `jadpo
check`'s does. It builds the before side with this compiler, once per
commit, keeping its manifest in `build/before/<commit>/`
([Comparing two builds](/docs/comparing-two-builds.md)).
[Reviewing a change](/docs/reviewing-a-change.md) gives
what it says, in that order, and what it prints. It fails only when it
can't write the report: a source with errors (`approval not written`, each
error shown), `cli.approval_arguments` for an argument, a `--before` git
doesn't know or nothing to compare with, and `acceptance.base_missing` for
a base the clone doesn't hold. With no before side, what
[a first record holds](/docs/comparing-two-builds.md#what-a-first-record-holds)
is still written, as all the report holds.

## `jadpo declines list` and `clear`

A decline is a line in your code that answers a judgement-call finding
with a reason, `decline <rule>: "<reason>"` ([Declining a judgement
call](/docs/declining-a-judgement-call.md)).

`list` shows every decline with its rule, place and reason, as one list in
file order. A reason too long for its row goes on the lines under it.
`clear` removes the matching decline lines, so each finding comes back. It
stops on syntax errors and points at `jadpo check` afterwards. Both take
`--rule <id>`, a path and `--json`. An unknown action or rule, or a path
outside the project, is `cli.declines_arguments`.

## `jadpo fix`

Applies the fix you pick for a finding, through the same code as the
editor's quick fix. Its first use is a release of Jadpo that adds a
standard type your app already names ([A release that adds a standard
type](/docs/standard-type-clashes.md)).

- Alone, it lists each `type.standard_clash` and `type.standard_exists`
  finding with the fixes it takes.
- `jadpo fix <name> swap` and `jadpo fix <name> rename <NewName>` list
  what changed, file by file.

A fix whose result would add an error changes nothing and shows the
error. A name with nothing to fix, a fix it doesn't take, or a name already
taken is `cli.fix_arguments`. It takes `--json`. Its rename isn't
`jadpo rename`: it writes no identity line.

## `jadpo suggest`

Hints where code could use a standard type or operation, and never edits
([Suggestions](/docs/suggestions.md)). It takes `--json`.

| Form | Does |
|---|---|
| `jadpo suggest` | Formats, then reports numbered findings and ends with the agent's instruction |
| `--catalogue` | Lists every signal |
| `ignore <number> "<why>"` | Keeps a suggestion quiet, in `ignored_suggestions.jadpo_record` |
| `found <file>:<line> <Type or operation> "<why>"` | Teaches a miss, in `taught_suggestions.jadpo_record` |
| `share`, `share --approve`, `--decline`, `--new-token` | Sends what was learned to Jadpo HQ |

The findings come from the signals on the standard types' entries and the
loop table. `ignore` and `found` also add to `.jadpo/suggest_pending`. A
wrong number, place, type or operation is `cli.suggest_arguments`.

`share` sends the pending hashes and shows the snippets HQ asks for, with
the exact payload. It sends those only with `--approve`. It stops at once
when sharing is turned off, and an HQ that can't be reached or refuses is
`suggest.share_failed` ([Sharing with Jadpo HQ](/docs/sharing-with-jadpo-hq.md)).

Not built yet: Jadpo HQ itself: `share` is built against a fake of it.