# 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 ([Records and manifest](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 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 |

## `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](18-records-and-manifest.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 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](01-project-layout-and-modules.md#declining-a-judgement-call)).

`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](19-standard-library.md#a-release-that-adds-a-standard-type)).

- 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](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](sharing-with-jadpo-hq.md)).

Not built yet:

- `jadpo approval --before <ref>`, which writes the review report of what
  changed in behaviour, policy and the API. It comes with
  [Records and manifest](records-and-manifest.md); who signs off is
  under [Review and sign-off](review-and-sign-off.md).
- Jadpo HQ itself: `share` is built against a fake of it.