carrick 0.3.80 → 0.3.82

package/templates/skills/carrick-drift.md

@@ -0,0 +1,101 @@
+---
+name: carrick-drift
+description: Use when the ask is whether a consumer and a producer still agree on a type, before changing a request or response shape, and when a compatibility verdict names a problem you cannot place. Puts the producer's type, each consumer call site's expected type and the stored verdict side by side.
+---
+
+# Where two services disagree about a shape
+
+{{SCOPE_NOTE}}
+
+`get_contract_pair` holds both sides and the verdict. It reports what the scan
+stored and computes no verdict of its own, and neither do you.
+
+## 1. The pairs
+
+```
+get_service_graph({{SCOPE}})
+```
+
+Each edge is a consumer and a producer. An edge carrying `via_sdk` reaches its
+producer through a published package and has no call site of its own. Page with
+`offset: <next_offset>` while the rows keep coming. To start from one service,
+pass `service: "<name>"`.
+
+## 2. Each pair, operation by operation
+
+```
+get_contract_pair({{SCOPE}}, consumer_service: "<consumer>", producer_service: "<producer>")
+```
+
+Per operation the answer carries `producer.request` and `producer.response` as
+type ids, `consumer.call_sites` with each site's `file_location`,
+`expected_request` and `expected_response`, and `verdicts`. The `types` array
+holds each distinct type text once, keyed by the id those rows reference.
+Operations are ranked by call-site count then by untyped sides. Page with
+`offset: <next_offset>`, or narrow with `path` and `method`.
+
+A verdict's `state` is `compatible`, `incompatible` or `unresolved`, and it
+carries `scanner_version` with `mismatch_reason` or `unresolved_reason` where
+the scan wrote one. One verdict covers the whole consumer and producer pair, so
+every call site on that operation shares it. An operation with `verdicts: []`
+was never judged, and `verdict_note` says so.
+
+Honour the wire note. Where `wire_notes` is present, one side declares a field
+as `Date` and the other as `string`. JSON serialises a Date to a string, so
+those two texts can describe the same bytes, and that is not drift.
+
+## 3. Class each operation
+
+- **MATCH**: the stored verdict is `compatible`.
+- **DRIFT**: the stored verdict is `incompatible`. Name the field and the
+  direction, request or response, from `mismatch_reason` and the two type texts.
+- **UNRESOLVED**: the stored verdict is `unresolved`. Report `unresolved_reason`
+  as it is written. Then read the two type texts this answer already returned in
+  `types`, the producer's side against the call site's expected type, and where
+  they differ name the field and say whether it is missing on one side, optional
+  on one side and required on the other, or of a different type. Report that as
+  "type texts differ", never as a verdict.
+- **NOT JUDGED**: `verdicts` is empty. Relay `verdict_note`, then read the same
+  two type texts the same way and report any difference as "type texts differ".
+- **CONSUMER UNTYPED**: a call site's `expected_request` or `expected_response`
+  is null on a side that carries one.
+- **PRODUCER UNTYPED**: `producer.request` is null on a method that carries a
+  body, or `producer.response` is null.
+
+A GET declares no request type by design, and `untyped_sides` already counts it
+that way. The wire note covers both readings above, so a `Date` on one side
+against a `string` on the other is not a difference.
+
+## 4. Report
+
+| operation | class | producer type | consumer type | call site | verdict |
+|---|---|---|---|---|---|
+| GET /api/orders/:id | DRIFT | Order | OrderSummary | web/src/orders.ts:31 | incompatible |
+| POST /api/orders | UNRESOLVED | NewOrder | OrderDraft | web/src/orders.ts:52 | unresolved; type texts differ on `note` |
+
+Class words, and only these: MATCH, DRIFT, UNRESOLVED, NOT JUDGED, CONSUMER
+UNTYPED, PRODUCER UNTYPED. A reading of the two type texts goes in the verdict
+column beside the stored state, in the words "type texts differ", so nothing in
+the table reads as a verdict the index did not give you.
+
+State alongside it: `operations_total` against `operations_shown`,
+`matched_calls` and `unmatched_calls`, `dropped_rows`, and the `non_http_note`
+where the pair also carries GraphQL, socket or pub/sub operations, whose type
+text this surface does not hold.
+
+## 5. Act
+
+Change no type unless you were asked to. Offer one issue per DRIFT, and one per
+UNRESOLVED or NOT JUDGED row whose type texts differ. File the ones accepted:
+
+```
+gh issue create --title "<consumer> and <producer> disagree on <field> of <operation>" --body "<producer type, consumer type, call sites, stored verdict and scanner version>"
+```
+
+An UNRESOLVED or NOT JUDGED row holds no verdict on the difference you read, so
+its title says the two sides may disagree and its body carries the reason the
+tool gave in place of a stored verdict:
+
+```
+gh issue create --title "<consumer> and <producer> may disagree on <field> of <operation>" --body "<producer type, consumer type, call sites, and the unresolved_reason or verdict_note as written>"
+```

package/templates/skills/carrick-impact.md

@@ -0,0 +1,106 @@
+---
+name: carrick-impact
+description: Use before changing or removing a route, a handler, a response shape, an event, or a function other code calls, and whenever the ask is who calls this, who consumes this endpoint, or what breaks if I change it. Names every producer and consumer call site the Carrick index holds, with file and line.
+---
+
+# Who depends on what you are about to change
+
+{{SCOPE_NOTE}}
+
+Carrick finds the call sites. Your work is to open them, decide whether each one
+breaks, and act.
+
+## 1. Name the thing
+
+A route, a GraphQL field, a socket event or a pub/sub topic: its method label
+and its path, as the index spells them. A function: its name, and the file it is
+defined in.
+
+## 2. Producers and consumers
+
+For an operation:
+
+```
+get_operation({{SCOPE}}, method: "<METHOD>", path: "<path>")
+```
+
+Four sections carry the answer.
+
+- `producers`: every service that serves it, with `file_location` and `source`.
+- `consumers`: every call site that reaches it, with `services`,
+  `call_file_location`, `via` (the function the call is written through, where
+  the index names one) and `source`.
+- `unmatched_calls`: recorded calls that resolved to no producer.
+- the near-miss sections: rows the index holds under a neighbouring method or a
+  path one segment away. Read them as candidates to check in source, never as
+  consumers of the operation you asked for.
+
+`source` is `fact: …` where a deterministic pass stated the row and
+`candidate: …` where the model did. Both are claims about the same path, so the
+label belongs in your table.
+
+For a function:
+
+```
+get_callers({{SCOPE}}, function_name: "<name>", file: "<file>", depth: 1)
+```
+
+Each row names the enclosing caller and its line span, not the call-site line.
+Raise `depth` to 2 or 3 for transitive callers. Zero recorded callers is not
+deletion evidence, because a function passed as a value is unmeasured.
+
+## 3. Verdicts, one consumer at a time
+
+For each consumer service the step above listed:
+
+```
+check_compatibility({{SCOPE}}, consumer_service: "<consumer>", producer_service: "<producer>", path: "<path>")
+```
+
+Pass `path`. Without it a large producer returns hundreds of rows. Read
+`type_verdicts` (`compatible`, `incompatible`, `unresolved`, `not_compared`) and
+the `issues` rows for this operation. A `not_compared` pair has no stored
+verdict, which is never agreement.
+
+## 4. A file you have already edited
+
+```
+carrick check <file> --recheck --json
+```
+
+`items[]` holds this file's routes and calls with their `counterparts` and
+`verdict`, judged against the working tree. `recheck.ran` says which answer came
+back: `extraction+types` and `extraction` describe the tree, and `none` means
+the rows are the indexed ones with `recheck.reason` saying why. `boundary_note`
+states what the local run could not classify.
+
+## 5. Report
+
+One table, then the detail.
+
+| consumer service | call site | verdict | source |
+|---|---|---|---|
+| admin-ui | src/api/orders.ts:44 | INCOMPATIBLE | fact |
+
+Verdict words, and only these: COMPATIBLE, INCOMPATIBLE, UNRESOLVED,
+NOT COMPARED. In the same message, state:
+
+- the producers, with file and line;
+- unmatched calls and near misses, listed apart from consumers;
+- the counts the responses carried: `consumer_count`, `consumers_outside_service`
+  where present, and `issues_total` against the rows you read.
+
+Two limits belong in the report wherever they apply. A route added on your
+branch has no consumers on main, so an empty consumer list says nothing about
+it. A call whose URL is built at the call site can be recorded under the wrong
+method, which is what the near-miss rows exist to show.
+
+## 6. Act
+
+Confirm each consumer in source before you call it broken. Change no consumer
+code unless you were asked to. Then offer one issue per finding, and file the
+ones accepted:
+
+```
+gh issue create --title "<consumer> breaks on <METHOD> <path>" --body "<call site, what it expects, what the producer now sends>"
+```

package/templates/skills/carrick-reuse.md

@@ -0,0 +1,89 @@
+---
+name: carrick-reuse
+description: Use at the end of a task that added or changed functions, and whenever the ask is whether something already exists, whether this duplicates code elsewhere, or where this project has built the same thing twice. Compares against the Carrick function index rather than by name.
+---
+
+# What already does this
+
+{{SCOPE_NOTE}}
+
+`find_similar` does the comparison. Your work is to read both spans and class
+each pair.
+
+## Targeted: the functions this task added or changed
+
+One call, up to 20 entries, run once at the end of the task.
+
+```
+find_similar({{SCOPE}}, functions: [
+  { name: "<Class.member or name>", file: "<path suffix>" },
+  { description: "<one plain sentence about a function that is not indexed yet>" }
+])
+```
+
+An entry is either a `name` with a `file` for a function the index holds, or a
+`description` for code you are about to write or have just written. Use one or
+the other in an entry, never both. A `name` that matches more than one
+definition comes back with its candidates on that entry's `error`.
+
+The two kinds are scored on different scales and the response states both
+floors: 0.85 between two indexed functions, 0.45 for a description. A stored
+vector carries the function's name in front of its intent and a bare sentence
+does not, so a description scoring 0.5 is a hit worth reading.
+
+## Audit: the whole project
+
+```
+find_similar({{SCOPE}})
+```
+
+`clusters` groups functions that describe the same behaviour, ordered by size.
+Page with `offset: <next_offset>` while `has_more` is true. A group is
+transitive, so `lowest_similarity` can sit under the floor and a large group can
+hold more than one idea.
+
+Where the project is larger than one pass, the response carries `error` in place
+of clusters and names the two routes under the ceiling: a `service`, or a higher
+`min_lines`. Take the route the response names and run it again. Where
+`truncated` is present the audit is partial, and its `scanned_functions` of `of`
+says by how much.
+
+## Class each pair
+
+Read both spans in source, then class:
+
+- **DUPLICATE**: the same behaviour, and one call site could use the other.
+- **VARIANT**: near neighbours that cannot share an implementation. Say in one
+  line why they cannot.
+- **FALSE POSITIVE**: the index describes them alike and the code does different
+  work.
+
+`matched_on` says which signal joined a row. `similarity` is the intent vectors;
+`intent_text` is two identical intent sentences, which is the signal that still
+finds a copy somebody renamed.
+
+## Report
+
+| class | function | file:line | pair | why |
+|---|---|---|---|---|
+| DUPLICATE | slugify | src/text.ts:12 | src/util/url.ts:4 | same replacement rules |
+
+Then relay the counts the response stated, in its numbers:
+
+- `compared_functions`, and `total_clusters` on an audit;
+- `not_compared`: `without_intent`, `intent_not_embedded`, `awaiting_embedding`,
+  `model_mismatch`;
+- `excluded`: `below_min_lines`, `tests`, `generated`, `callbacks`,
+  `other_service`.
+
+Rows outside the comparison were not looked at, so an empty answer covers what
+was compared and nothing further.
+
+## Act
+
+Merge nothing unless you were asked to. Offer one issue per DUPLICATE, and file
+the ones accepted:
+
+```
+gh issue create --title "Duplicate: <behaviour> in <n> files" --body "<each file:line, and which one should remain>"
+```