Repository navigation
Relation sides carry state; issue list rows can carry relations; say what --blocked means - #9
Merged
Merged
Conversation
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.
There was a problem hiding this comment.
🟢 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A caller that plans from Linear (here
bin/mk linearin kaikhq/manekineko) hit three gaps:issue shownamed 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 moreissue list --id …per issue to read its blockers' states.issue listrows could not carryparent,relationsorinverseRelations. A caller listing a whole project could not say which issue blocks which, or group by parent, without oneissue showper issue.--blockedwas 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
issue,relatedIssue, inrelationsandinverseRelations) and theparentinissue showare now{id, identifier, title, state {id, name, type}}. Only fields are added; the parent gainsidandstate.issue list --fields parent,relations,inverseRelations(afdbe71, 2364621). Same shape asissue show, under Linear's names. They are never in the default row. When--fieldsnames any of them, they are read after the rows by id in a separate query,IssueRelations: up to 250 issues per request, withrelations(first: 250)andinverseRelations(first: 250). Only the fields asked for are selected (@include). An issue with more than 250 of either has the rest read byIssueShowMore, asissue showalready does, so no list is cut short. This works the same for plain lists,--queryand--view.--blocked/--blockingsay what they match (afc01b7). The flag help,issue list's long help, the README and docs/design.md now say these are Linear'shasBlockedByRelations/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.tests/live.rs). Described below.Complexity: measured, not guessed
These are read-only
api querycalls against the live API on 2026-10-27, readingX-Complexity. Full table in docs/performance.md.firstdoes not multiply its cost.issues(first: 1)andissues(first: 250)with the full row both cost 18. A nested connection'sfirstdoes multiply: the same 250 rows undercustomViews { issues }(--view) cost 3,751.--view, 250 rows withrelations(first: 10)cost 42,401 points, and Linear refused them ("Maximum allowed complexity: 10000"). 10 rows withfirst: 50cost 7,777.IssueRelationsread for 250 ids with all three fields costs 3,805 (parentalone: 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,inverseRelationsreturned 300 rows with 297 relations and 1,677 inverse relations, using two extra requests.What
--blockedmeans, measuredRead-only, on 2026-10-27, across every issue in a real workspace:
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.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.Tests
documents_match_the_schemacoversIssueRelationsand the changed show/relation documents.tests/issue_list.rshas two new tests:relation_fields_come_by_id_after_the_rows_on_every_pathcovers list,--queryand--view.rows_without_relation_fields_cost_no_requestchecks that without these fields no extra request is made and no row carries them.issue show's own and out of the default row.TestIssueShowRelationSidesCarryState.TestIssueListRelationFields: the default row makes no extra request. With the fields, the variables are as asked, an issue not found getsnull, relations past the first page are read throughIssueShowMore(removing that read fails the test), and 251 rows take two reads of 250 + 1.--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, andmake skillis 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)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_blockerintests/live.rsdoes the following:issue list --blocked.issue list --fields inverseRelationsandissue showgive the blocker's new state.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 deleteprint the two issues the caller named (id,identifier), andrelation delete'srelations[]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'schildren[]already hadstate {name, type}.cycle show/project show/watchrows do not gain the relation fields: none of these takes--fieldsfor rows, and nesting the fields there would multiply their cost.