Skip to main content

Work with code

Check a change before accepting it.

Use Kin to find code connections worth inspecting during a review. Its report is advice, not a correctness guarantee, and the decision to accept the change stays with you.

How this works in Kin

Kin reads a change as entities and relations rather than lines, so a review can start from the signature that changed and the consumers it reaches. The report-only gate never blocks and never changes graph state, and the merge decision stays with the team.

Start with a disposable copy of your code. Examples below were checked on a specific build; language and workflow support are limited.

Check the example version and setup

Supported build

Every command below was run on Kin v0.7.6, macOS on Apple silicon, on 2026-09-09, against a four-file JavaScript repository created from scratch. The output shown is what that run printed. Current release: v0.7.19.

Before you start

  • Kin on your PATH, and a repository admitted with kin init.
  • A recorded change to review. kin review defaults to the latest change, and the report-only gate takes a base and a head.
  • An author identity, if you are going to record the change yourself. Kin refuses to record a change it cannot attribute.
  • A decision that stays with you. Review evidence is advisory and does not block merges by default, and the report-only gate never blocks and never changes graph state.

The steps

  1. 01

    Read what the change did to the graph

    With no arguments, review reports the latest change: which entities were added or modified, and which relations moved.

    kin review
    Compare with the saved example output
    Reviewing semantic change: 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855
  Message: Accept a currency argument when formatting an amount
  Author: Docs Example <docs@example.com>

=== Semantic Review ===
Base: 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865
Head: 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855

--- Entity Changes ---

Modified (2):
  ~ money (Module)
  ~ formatAmount (Function)
    signature: function formatAmount(cents) -> function formatAmount(cents, currency = 'USD')

    A base, a head, and the entities between them. The signature line is recorded rather than reconstructed from a text diff, so a reviewer reads what the contract became instead of guessing from the surrounding lines.

  2. 02

    Run the report-only gate over the range

    The shadow gate evaluates a change the shape a pull request has: a base and a head. It reports and stops there.

    kin review shadow <base>..<head>
    Compare with the saved example output
    Shadow Merge Gate Report (report-only; never blocks)
  Range: 61ad778d54790180e31c78b2f1b6f8912d61fa0eb22eb049f70af07a46d8d865 .. 5c15d027b9849974ea2b4d8e31ce8ce11ca3428d9bce65bac7d2d3a96fffd855

Verdict: WOULD BLOCK (risk: high) - 1 blocking finding(s), 4 attention signal(s); would block in enforcing mode

Changed entities (2):
  ~ formatAmount (Function) [src/money.js:0]
  ~ money (Module) [src/money.js:0]

    A verdict phrased as what an enforcing mode would do, not what this run did. The command never blocks and never changes graph state, so the verdict is information for a person, and the range accepts branch names, semantic change ids and imported Git commit shas.

  3. 03

    Read the blast radius before the findings

    The findings are about one entity. The blast radius is who has to care, which is usually the part that changes a review.

    kin review shadow <base>..<head>
    Compare with the saved example output
    Blast radius (6 affected; this repository):
  callers (2):
    describeLine [src/pricing.js]
    renderReceipt [src/receipt.js]
  dependents (6):
    cli [src/cli.js]
    main [src/cli.js]
    describeLine [src/pricing.js]
    pricing [src/pricing.js]
    receipt [src/receipt.js]
    renderReceipt [src/receipt.js]
  cross-repo: not_evaluated - cross-repo federation is not evaluated by shadow report v2; blast radius covers this repository only

    Callers and the wider dependent set, each with the file it lives in. The cross-repo line is a stated boundary rather than an empty result: a dependent in another repository was not looked for, so its absence proves nothing.

  4. 04

    Read the findings and what they are missing

    A finding names the fact it is built on. A missing-coverage finding names an absence, which is the one a review usually acts on first.

    kin review shadow <base>..<head>
    Compare with the saved example output
    Findings (5):
  [warning] Behavior of `money` changed with 2 distinct non-test consumer(s) across 2 file(s) [src/money.js:0]
  [warning] Modified entity `money` has no test coverage [src/money.js:0]
  [warning] Signature changed: `function formatAmount(cents)` → `function formatAmount(cents, currency = 'USD')` [src/money.js:0]
  [error] [blocking] Breaking change: signature modification affects 4 downstream entity(ies) [src/money.js:0]
  [warning] Modified entity `formatAmount` has no test coverage [src/money.js:0]

    No test coverage means no graph-known test covers the entity. That is a statement about what the graph holds, so treat it as a gap to close or a gap to explain, not as proof the code is untested.

  5. 05

    Take the repair context to the change, and decide

    The report ends with what to do about each finding and which consumers to look at. Then a person decides.

    kin review shadow <base>..<head>
    Compare with the saved example output
    Repair context:
  - Signature changed: `function formatAmount(cents)` → `function formatAmount(cents, currency = 'USD')`
    Verify every listed caller against the new signature before merging.
    consumers: describeLine (src/pricing.js), renderReceipt (src/receipt.js)
  - Modified entity `formatAmount` has no test coverage
    No graph-known test covers this entity; add or link a test so the gate has proof.
    consumers: describeLine (src/pricing.js), renderReceipt (src/receipt.js)

    Two named consumers to open and read. Nothing in this flow merges anything or records a decision; kin review decide is the separate command for recording one.

When the answer looks wrong

An empty or partial answer can reflect coverage, repository state, or an error. Each row below says what the state means and what to do next.

  • error: the following required arguments were not provided: <RANGE>

    kin review shadow needs a base and a head. The bare command reviews the latest change; the gate reviews a range.

    Pass base..head, or use --base and --head. Refs accept branch names, semantic change ids and imported Git commit shas.

  • Verdict: WOULD BLOCK

    What an enforcing mode would have done. This run did not block anything and did not change graph state.

    Read the blocking finding, open the consumers it names, and decide. Nothing is waiting on the verdict.

  • Modified entity X has no test coverage

    No test the graph knows about covers that entity. A test that exists but is not linked in the graph reads the same way.

    Add a test, or link the one that already covers it, so the next report has the evidence.

  • kin review reports a change you did not expect.

    With no argument it reviews the latest recorded change, which is the last one kin commit created rather than whatever is in your working tree.

    Pass the change id you meant, or record your working change first and review again.

  • Error: config error: kin has no author identity to record for this change.

    This came from kin commit, not from review. Kin will not record a change it cannot attribute.

    Set git config user.name and user.email, or default_author in .kin/config.toml, then record the change and review it.

Next action

Run the report on a change of your own.

Pick a change you already reviewed by hand, run the report-only gate over its range, and compare what it found with what you found. That comparison is worth more than any claim on this page.

Inspect potential change impact

Related