Skip to content

Relation sides carry state; issue list rows can carry relations; say what --blocked means - #9

Merged
linyiru merged 11 commits into
mainfrom
relation-state
Oct 28, 2026
Merged

linyiru merged 11 commits into
mainfrom
relation-state

Conversation

@linyiru

@linyiru linyiru commented Oct 28, 2026

Copy link
Copy Markdown
Member

Why

A caller that plans from Linear (here bin/mk linear in kaikhq/manekineko) hit three gaps:

  1. issue show named each side of a relation by id, identifier and title only. It could say that ENG-3 blocks this issue, but not whether ENG-3 was still open, so the caller made one more issue list --id … per issue to read its blockers' states.
  2. issue list rows could not carry parent, relations or inverseRelations. A caller listing a whole project could not say which issue blocks which, or group by parent, without one issue show per issue.
  3. --blocked was documented as "only issues blocked by an open issue". What it matches is Linear's to decide (hasBlockedByRelations), and nothing in linearctl said so, tested it, or said what a duplicate-state blocker does.

What

  1. Relation sides carry state (0e25aa0). Each side of a relation (issue, relatedIssue, in relations and inverseRelations) and the parent in issue show are now {id, identifier, title, state {id, name, type}}. Only fields are added; the parent gains id and state.
  2. issue list --fields parent,relations,inverseRelations (afdbe71, 2364621). Same shape as issue show, under Linear's names. They are never in the default row. When --fields names any of them, they are read after the rows by id in a separate query, IssueRelations: up to 250 issues per request, with relations(first: 250) and inverseRelations(first: 250). Only the fields asked for are selected (@include). An issue with more than 250 of either has the rest read by IssueShowMore, as issue show already does, so no list is cut short. This works the same for plain lists, --query and --view.
  3. --blocked / --blocking say what they match (afc01b7). The flag help, issue list's long help, the README and docs/design.md now say these are Linear's hasBlockedByRelations / hasBlockingRelations. Linear decides what matches, and linearctl computes nothing. A blocks relation counts only while both of its issues are open: triage, backlog, unstarted or started. Completed or canceled on either end, it does not count. A duplicate-state issue was not measured. The filters sent are unchanged.
  4. Demo mode (e871fad, 2a2f412) answers both filters by that rule, where it used to list nothing. The seed gains ENG-140 (in review) blocks ENG-158, and ENG-131 (done) blocks ENG-144.
  5. Live test (fbdb923, tests/live.rs). Described below.
  6. docs/performance.md (7eb5a29) records the complexity measurements below.

Complexity: measured, not guessed

These are read-only api query calls against the live API on 2026-10-27, reading X-Complexity. Full table in docs/performance.md.

  • A top-level connection's first does not multiply its cost. issues(first: 1) and issues(first: 250) with the full row both cost 18. A nested connection's first does multiply: the same 250 rows under customViews { issues } (--view) cost 3,751.
  • A relation with both sides and their states costs about 7.6 points.
  • Inlined into the row query under --view, 250 rows with relations(first: 10) cost 42,401 points, and Linear refused them ("Maximum allowed complexity: 10000"). 10 rows with first: 50 cost 7,777.
  • The separate IssueRelations read for 250 ids with all three fields costs 3,805 (parent alone: 5). A field under @include(if: false) costs 0.

So the relation fields are read by id rather than inside the row query. That costs one extra request per 250 rows (plus one per issue with more than 250 relations) and stays under the limit on every path, with no silent cap. Checked live, read-only: issue list --team TEACH --limit 300 --fields identifier,parent,relations,inverseRelations returned 300 rows with 297 relations and 1,677 inverse relations, using two extra requests.

What --blocked means, measured

Read-only, on 2026-10-27, across every issue in a real workspace:

  • Open issues. Of 3,476, 78 were hasBlockedByRelations: true. Each of those has at least one blocker in triage/backlog/unstarted/started. All 47 open issues blocked only by completed issues were excluded, and so was the one blocked by a canceled and a completed issue. This agrees with the downstream check of 2026-09-29.
  • Closed blocked issues. Of 100 completed or canceled issues updated since June that some issue blocks, none was listed, including those with an open blocker.
  • hasBlockingRelations. It follows the same rule from the other end: 74 open issues blocking at least one open issue were listed, and none of the other 144.
  • Duplicate. The workspace had no blocks relation with a duplicate-state end, so the docs say "not measured".

Tests

  • Unit / Rust integration. documents_match_the_schema covers IssueRelations and the changed show/relation documents. tests/issue_list.rs has two new tests:
    • relation_fields_come_by_id_after_the_rows_on_every_path covers list, --query and --view.
    • rows_without_relation_fields_cost_no_request checks that without these fields no extra request is made and no row carries them.
    • A unit test keeps the three names issue show's own and out of the default row.
  • Acceptance (fake Linear validating every request against the schema):
    • TestIssueShowRelationSidesCarryState.
    • TestIssueListRelationFields: the default row makes no extra request. With the fields, the variables are as asked, an issue not found gets null, relations past the first page are read through IssueShowMore (removing that read fails the test), and 251 rows take two reads of 250 + 1.
  • Golden: four new demo cases (--blocked, --blocking, issue show ENG-144 --fields inverseRelations, issue list --project "Checkout v2" --limit 0 --fields identifier,state,parent,relations,inverseRelations). Show and help outputs are re-recorded, and make skill is regenerated.
  • make check: green (fmt, clippy, gofmt, go vet, unit + integration, acceptance, 404/404 golden, 20 skill files current).

Coverage (scripts/cover.sh, all tests merged, lines)

file before after
src/commands/issue.rs 98.61% (16 of 1,155 missed) 98.67% (16 of 1,203 missed)
src/queries.rs 98.48% 98.51%
src/demo.rs 94.29% (50 of 875) 94.31% (51 of 896)
total 94.02% 94.05%

Every added line is covered except one: the fallback arm of a text helper in the demo's blocked rule (_ => String::new()), which only runs for a relation or state without a type.

Live test: not run

blocked_counts_only_an_open_blocker in tests/live.rs does the following:

  1. Creates two issues and makes one block the other.
  2. Waits for the blocked issue to appear in issue list --blocked.
  3. Completes the blocker and checks the blocked issue drops out. Reopens the blocker (back in), then cancels it (out again). Each step waits up to 60 s for Linear's filter to catch up.
  4. At each step, checks that issue list --fields inverseRelations and issue show give the blocker's new state.
  5. If the team has a duplicate-type state, moves the blocker there and prints whether it counts, without asserting.
  6. Archives both issues, also on failure.

It needs a sandbox team to run and has not been run: LINEARCTL_LIVE_TEAM=<sandbox> LINEAR_API_KEY=… make live. Without those variables it returns at once, as the existing watch test does.

Not changed

  • relation create / relation delete print the two issues the caller named (id, identifier), and relation delete's relations[] gives the sides as identifier strings. Adding state there would mean changing a string into an object, which the changelog policy forbids, so they are left as they are.
  • issue show's children[] already had state {name, type}.
  • cycle show / project show / watch rows do not gain the relation fields: none of these takes --fields for rows, and nesting the fields there would multiply their cost.

issue show named each side of a relation by id, identifier and title, so
a caller that saw "ENG-3 blocks this issue" could not tell whether ENG-3
was still open without one more read per relation. Each side, and the
parent, now selects state { id name type }, and the parent its id; the
shape only gains fields.
The demo resolver had no hasBlockedByRelations, so issue list --blocked
listed nothing, and the seed had no blocks relation to show. It now
answers it as Linear did when measured on 2026-10-27 (3,476 open issues of
a real workspace, every one checked): an issue is blocked when an issue
in a triage, backlog, unstarted or started state blocks it; a completed
or canceled blocker does not count. No duplicate-state blocker was there
to measure.

The seed gains two blocks relations, one of each kind: ENG-140 (in
review) blocks ENG-158, which --blocked lists, and ENG-131 (done) blocks
ENG-144, which it does not. Two golden cases show both.
A caller listing a whole project could not say which issue blocks which,
or group by parent, without one issue show per issue: rows carry neither.
issue list's --fields now takes all three, in issue show's shape, each
side of a relation with its state. They are never in the default row.

They are read after the rows, by id: IssueRelations asks for up to 250
issues at a time with relations(first: 250) and inverseRelations(first:
250), and an issue with more has the rest read by IssueShowMore, as issue
show does, so none is cut short. Only the fields asked for are selected
(@include).

Measured against the API on 2026-10-27: Linear does not multiply a
top-level connection's cost by its first (issues(first: 1) and
issues(first: 250) of the same row both cost 18 points), but does
multiply a nested one. So the separate read by id costs 3,805 points for
all three at 250 rows, where the same selection inside the row query
would be multiplied per row under --view (customViews { issues }):
42,401 points for 250 rows at relations(first: 10), over the 10,000 a
query may cost. A separate read keeps every path (list, --query, --view)
the same and under the limit, for one request per 250 rows. Checked live,
read only: 300 rows of a real team, 297 relations and 1,677 inverse
relations, in two extra requests.
Measured against the API on 2026-10-27, read only, on a real workspace:
hasBlockingRelations follows the same rule as hasBlockedByRelations, and
in both the issue itself counts as well as the other end. A blocks
relation counts only while both of its issues are in a triage, backlog,
unstarted or started state.

- --blocked: of the 100 completed or canceled issues updated since June
  that some issue blocks, none was listed, the one blocked by an
  unstarted issue included.
- --blocking: of the issues updated since June that block another, the
  74 open ones blocking at least one open issue were listed, and none of
  the other 144 (an open issue blocking only completed ones, or a
  completed issue blocking open ones).

The demo resolver now applies that rule to both filters, and a golden case
shows --blocking listing ENG-140.
…ts them

--blocked's help said "only issues blocked by an open issue", and
--blocking's "only issues that block another"; nothing said that both are
Linear's hasBlockedByRelations and hasBlockingRelations, that Linear
decides what they match, or what a duplicate-state issue does. A caller
had to find out live.

As measured on 2026-10-27 (see the commit before last), a blocks relation
counts only while both of its issues are open: triage, backlog, unstarted
or started. The flags' help, issue list's long help, the README and
docs/design.md now say so, and that a duplicate-state issue was not there
to measure. The filters sent are unchanged; the skill and golden help are
regenerated.
What --blocked matches is Linear's to decide, so only the real API can
show it changed. The new live test makes one issue block another and
checks issue list --blocked lists the blocked one; completes the blocker
and checks it drops out; reopens it (back in) and cancels it (out again),
waiting up to 60 s each time for Linear's filter to follow. On the way it
checks that issue list --fields inverseRelations and issue show give the
blocker's state as it was just set. Last it moves the blocker to a
duplicate-type state, when the team has one, and prints whether that
counts rather than asserting it: it was never measured. Both issues are
archived at the end, or when the test fails.

Like the watch test, it runs only with LINEARCTL_LIVE_TEAM and
LINEAR_API_KEY (make live) and returns at once without them.
docs/performance.md said per-query complexity needed a real key. Measured
on 2026-10-27 with read-only api query calls: a top-level connection's
first does not multiply its cost (18 points for a page of rows at any
first), a nested one's does (3,751 for 250 rows under customViews), a
relation with both sides and their states is about 7.6 points, and a
field under @include(if: false) costs nothing. The table records the
figures that decided how issue list reads relations.
The example added for --fields parent,relations,inverseRelations was 111
columns wide, past the 100 that every help line keeps to
(TestHelpFits100Columns). It now names a shorter project and drops state.
The acceptance suite checks issue list --fields relations on a plain list.
tests/issue_list.rs now checks it on --query and --view too: each makes
one IssueRelations request after the rows, asks only for what --fields
names, and fills parent and both relation lists with each side's state;
without those fields no request is made and no row carries them. A unit
test keeps the three names issue show's own and out of the default row.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the dependency and blocker-state changes.

No open issues 🎉

What changed in this PR

This PR lets linearctl callers inspect issue dependencies and blocker states without fetching each issue individually. It preserves default list rows and documents Linear’s blocked/blocking filter behavior.

Changes:

  • Adds state to relation sides and parents, plus opt-in list fields fetched in batches with relation pagination.
  • Clarifies blocked/blocking semantics and aligns demo behavior with the measured open-issue rule.
  • Adds integration, acceptance, golden, and opt-in live coverage, alongside query-complexity documentation. The new live test has not been run.
File Description
tests/​live.rs Adds sandbox checks for blocker state transitions.
tests/​issue_list.rs Tests relation retrieval across list, search, and view paths.
tests/​golden/​expected/​0403-issue-list-blocking-fields-identifier-title-json.txt Records demo blocking results.
tests/​golden/​expected/​0402-issue-list-project-Checkout-v2-limit-0-fields-identifier-state-parent-relations-.txt Records project rows with parents and relations.
tests/​golden/​expected/​0401-issue-show-ENG-144-fields-identifier-inverseRelations-json.txt Records a completed blocker’s state.
tests/​golden/​expected/​0400-issue-list-blocked-fields-identifier-title-json.txt Records demo blocked results.
tests/​golden/​expected/​0384-complete-issue-list.txt Updates filter completion descriptions.
tests/​golden/​expected/​0361-issue-show-ENG-142-demo-json.txt Updates demo output with parent and relation states.
tests/​golden/​expected/​0272-issue-show-ENG-142-comments-json.txt Updates show-with-comments output shapes.
tests/​golden/​expected/​0268-issue-show-https-linear-app-northwind-issue-ENG-143-x-json.txt Records enriched parent data for URL-based lookup.
tests/​golden/​expected/​0264-issue-show-ENG-131-fields-inverseRelations-json.txt Records states on inverse relation sides.
tests/​golden/​expected/​0262-issue-view-eng-142-comments-0-json.txt Updates view-alias output without comments.
tests/​golden/​expected/​0260-issue-show-ENG-142-json.txt Updates standard issue-show output.
tests/​golden/​expected/​0095-issue-list-fields-nope-json.txt Adds relation fields to validation errors.
tests/​golden/​expected/​0072-describe.txt Updates formatted command metadata.
tests/​golden/​expected/​0070-describe.txt Updates compact command metadata.
tests/​golden/​expected/​0067-issue-list-help-json.txt Updates help output with JSON enabled.
tests/​golden/​expected/​0048-issue-list-h.txt Updates short-flag help output.
tests/​golden/​expected/​0047-watch-help.txt Updates watch filter descriptions.
tests/​golden/​expected/​0023-issue-list-help.txt Documents relation fields and filter semantics in help.
tests/​golden/​cases.jsonl Registers four new demo scenarios.
src/​queries.rs Adds shared issue-side fields and batched relation queries.
src/​demo.rs Implements open-issue blocked/blocking matching.
src/​commands/​issue.rs Adds opt-in relation enrichment and updates help.
skills/​linearctl/​references/​watch.md Refreshes generated watch documentation.
skills/​linearctl/​references/​issue.md Refreshes generated issue documentation.
README.md Explains relation fields and blocked filtering.
docs/​performance.md Records measured query costs and batching rationale.
docs/​design.md Documents relation shapes and filter behavior.
demo/​workspace.json Seeds open and completed blocker examples.
CHANGELOG.md Summarizes new fields, documentation, and demo fixes.
acceptance/​issue_test.go Tests output shapes, batching, pagination, and missing issues.

Review effort: Balanced

CHANGELOG's Unreleased lists #7's Added entries before this branch's.
The golden cases keep main's 0400-0405 and follow them with this
branch's; expected/ is re-recorded.
issue list's long help keeps both: how --project and --milestone are
looked up, then what --blocked, --blocking and the relation fields do;
the README row names milestone and the relation fields. CHANGELOG's
Unreleased has one Changed and one Fixed section, #8's entries before
this branch's. The golden cases follow main's with this branch's;
expected/ is re-recorded, and issue show's rows carry both the demo's
milestones and the relation sides' states.
@linyiru
linyiru merged commit 9a7dbff into main Oct 28, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants