carrick 0.3.81 → 0.3.83

package/templates/skills/carrick-drift.md

@@ -0,0 +1,107 @@
+---
+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. Every operation the answer returned carries one of
+them, the class column is never empty, and the report states operations returned
+against operations classed. Where more than one word fits an operation, the row
+takes the first that applies of DRIFT, PRODUCER UNTYPED, CONSUMER UNTYPED,
+UNRESOLVED, NOT JUDGED, MATCH, because a stored incompatible verdict is the
+finding and a side carrying no type is why nothing past it could be judged.
+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,108 @@
+---
+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. Every consumer call site the answers returned carries one of them
+and the verdict column is never empty, and the report states call sites returned
+against call sites given a verdict. 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,106 @@
+---
+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 the spans it names
+and class every row it returned.
+
+## 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 each result states the floor
+it was ranked against. `vector_basis` says what the cosines are over. On
+`intent` the vector is the intent sentence alone, and a copy somebody renamed
+scores as close as one that kept its name. On `name_anchored` the function's
+name sits in front of the sentence, a renamed copy scores lower, and
+`intent_text` is the signal that still finds it. Read every score against the
+floor and the basis in the answer you got.
+
+## Audit: the whole project
+
+```
+find_similar({{SCOPE}})
+```
+
+`clusters` groups functions that describe the same behaviour, ordered by size.
+Call again with `offset: <next_offset>` for as long as the response carries
+`has_more`, and class what every page returned.
+
+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 every row
+
+Every row the answer returned is classed here. In an audit the first member of a
+cluster is what the rest of that cluster is classed against; in a targeted call
+it is the function you asked about. Read that span at the file and line the
+response gave, read each other row the same way, and take the first of these
+that holds:
+
+- **FALSE POSITIVE**: the two contracts differ. Different inputs, a different
+  result, or a different effect, and the intent sentences alone brought them
+  together.
+- **VARIANT**: one contract, and a behavioural difference you can name in a
+  clause. A different normalisation, a different error path, a different
+  default. Write the clause in the row. Where a comment on the member or at the
+  head of its file names the file it mirrors, the clause is "documented
+  mirror".
+- **DUPLICATE**: one contract, and nothing left to name. Two bodies that run
+  the same once the identifiers are renamed land here.
+
+A cluster is transitive, so `lowest_similarity` can sit under the floor and a
+large group can hold more than one idea. A member that shares no contract with
+the first is FALSE POSITIVE on its own row, and stays in the table.
+
+`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
+
+One row per match, and per cluster member beyond the first. The class column
+carries one of the three words and is never empty.
+
+| class | member | file:line | against | why |
+|---|---|---|---|---|
+| DUPLICATE | slugify | src/util/url.ts:4 | src/text.ts:12 | same replacement rules |
+| VARIANT | slugTag | src/tags.ts:20 | src/text.ts:12 | documented mirror |
+
+State `total_clusters` from the response against the number of clusters carrying
+rows above. Where the two differ, name the clusters left out.
+
+Then relay the counts the response stated, in its numbers: `compared_functions`,
+and every key the answer carries under `not_compared` and under `excluded`.
+
+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>"
+```