Find what uses a piece of code.

Before you start

• Kin on your PATH. Run kin --version to see the build you are on.
• A repository admitted with kin init. The daemon for that repository starts on the first command, and the first query after a start waits for it to load the graph.
• A shell inside that repository. kin refs resolves references within the current repository only; for a definition in a sibling repository, use kin xref.
• A language Kin has an adapter for. Files in other languages are admitted with their content and history, and produce no entities or relations, so no caller question reaches them.

The steps

1. 01

   Check the graph before you ask it anything

   Readiness is what separates an empty answer where no callers are recorded in the graph from an empty answer meaning the graph is not finished. The report is long; these three lines are the ones that decide whether to trust the next answer.

   kin graph status

   Copy command

   Compare with the saved example output

   Entities: 10 (live query graph, definitions this repository owns)  |  Entity-to-entity relations: 66  |  Files: 4 (files those entities originate in)
   Embeddings: 20/20 indexed (0 pending)
   Contaminated paths: 0

   Embeddings fully indexed, and a relation count above zero. If embeddings still report pending, wait and run it again. Zero relations across several source files means enrichment has not landed yet, not that your code has no connections.

2. 02

   Find the exact entity name

   kin refs takes an entity, not a phrase. If you are not sure of the name, search for it first.

   kin search formatAmount

   Copy command

   Compare with the saved example output

   Found 8 results:
     formatAmount (Function, javascript) - src/money.js
     describeLine (Function, javascript) - src/pricing.js  [text-search fallback, no name match]
     pricing (Module, javascript) - src/pricing.js  [text-search fallback, no name match]
     receipt (Module, javascript) - src/receipt.js  [text-search fallback, no name match]

   The first row is the name match. Rows tagged text-search fallback matched content rather than a name, so they are context rather than answers. If no row is a name match, the entity is not in this graph under that spelling.

3. 03

   Ask for the callers

   One relation kind at a time keeps the answer readable and keeps you honest about which question you asked.

   kin refs formatAmount --kind calls

   Copy command

   Compare with the saved example output

   References to 'formatAmount' -> formatAmount (Function) @ src/money.js
   referenced by 2 entities:
     describeLine @ src/pricing.js:11 [Calls] (type_resolved) sites 12
     renderReceipt @ src/receipt.js:4 [Calls] (type_resolved) sites 6

   Each row names the calling entity, the file and line it is defined at, the relation kind in brackets, how the edge was resolved, and a sites field pointing at where inside that caller the reference was recorded. These are recorded edges, so a name that merely appears in a comment or a string is not here.

4. 04

   Widen to every recorded reference

   Callers are one kind of reference. Drop the filter when you want the whole picture before a rename or a deletion.

   kin refs formatAmount

   Copy command

   Compare with the saved example output

   References to 'formatAmount' -> formatAmount (Function) @ src/money.js
   referenced by 5 entities:
     money @ src/money.js:1 [References] (type_resolved) sites none (no_evidence_span)
     describeLine @ src/pricing.js:11 [Calls, References] (type_resolved) sites 12
     pricing @ src/pricing.js:1 [Imports, References] (type_resolved) sites 1
     receipt @ src/receipt.js:1 [Imports, References] (type_resolved) sites 1
     renderReceipt @ src/receipt.js:4 [Calls, References] (type_resolved) sites 6

   The two callers plus the modules that import it and the module that defines it. A row can carry several kinds at once. Use kin refs X --kind imports when you only want the modules.

5. 05

   Check one caller against the source

   A recorded answer is worth having because you can check it. Do that once on code you know, and you will know how much to trust the next answer on code you do not.

   sed -n '11,13p' src/pricing.js

   Copy command

   Compare with the saved example output

   function describeLine(item) {
     return `${item.quantity} x ${item.name} ${formatAmount(lineTotal(item))}`;
   }

   describeLine is defined at line 11 and reaches formatAmount on line 12, which is what the graph said. If the source disagrees with the graph, the graph may be stale, incomplete, or incorrect: check the revision with kin graph status, and if the mismatch remains after re-admitting the change, report a minimal example.

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: Entity 'applyDiscount' not found in this repo's graph.

  No entity in this repository carries that name. Kin resolves references within the current repository only.

  Run kin search applyDiscount for the real spelling, or kin xref applyDiscount when the definition lives in a sibling repository.

• No incoming Calls relations.

  The current graph contains no incoming Calls edges for this entity. That does not establish that no callers exist in the source.

  Ask the wider question with kin refs X before concluding the code is unused: something may import it or reference it without calling it.

• sites none (no_evidence_span)

  Kin recorded a relationship but has no source span for it.

  Inspect the named file before relying on it.

• all entities are Source, role classification may not be working

  A role heuristic had too little code to calibrate against. On a small repository this is what it says.

  Ignore it for a caller question. It says nothing about the recorded edges the answer above came from.

• The first query hangs for a few seconds.

  The daemon for this repository was not running, so it started and loaded the graph before answering.

  Wait for it. Later queries against the same repository answer from the loaded graph.