Skip to content

issue list and watch: --project and --milestone by id, never a silent empty or mixed list - #8

Merged
linyiru merged 7 commits into
mainfrom
list-filter-project-id
Oct 28, 2026
Merged

linyiru merged 7 commits into
mainfrom
list-filter-project-id

Conversation

@linyiru

@linyiru linyiru commented Oct 28, 2026

Copy link
Copy Markdown
Member

Why

issue list and watch share list_filter, which sent --project to Linear as {"project": {"name": {"eqIgnoreCase": …}}} and --milestone as {"projectMilestone": {"name": {"eqIgnoreCase": …}}}. A real caller (an issue-tracking wrapper built on linearctl) hit both consequences:

  1. The UUID, slugId or URL that project list and project show hand out matched no project name, so the list was empty with exit 0. Nothing said the reference was wrong.
  2. Project names are not unique in Linear, so a name could list the issues of two projects; the caller had to filter rows by project id afterwards. Milestone names repeat across projects too.

project show already reads a URL, slugId, UUID or name and reports AMBIGUOUS with candidates for a shared name. issue list now does the same.

What

  1. Shared project reference (03ef309): project_filter (URL / slugId / UUID / name → ProjectFilter) and one_project (the NOT_FOUND / AMBIGUOUS decision) in project.rs become public. project show and update behave as before.
  2. Resolve before listing (1894388): list_filter stays pure. It writes --project as project_filter reads it, and --milestone as {id} for a UUID or {name: eqIgnoreCase} otherwise, scoped with project: <the --project filter> when both are given. Then resolve_places sends one request, PlaceResolve (projects and projectMilestones, each behind @include), and replaces both with {id: {eq}}.
    • Nothing found → NOT_FOUND with kind and name (and a hint).
    • More than one → AMBIGUOUS with candidates. A project candidate has id, name and slugId; a milestone candidate has id, name and project.
    • The project is checked first, so its error wins when both flags fail.
    • none still means "in no project / milestone" and sends no request. --milestone NAME with --project none is usage (2).
    • watch calls the same function once, before its snapshot, and filters by id from then on.
    • Flag help, issue list / watch long help, the README, docs/design.md (Inputs), AGENTS.md and the generated skill describe this (a9be209), plus a CHANGELOG [Unreleased] entry.
  3. Demo workspace (99fe759): it gains milestones (Beta and GA in Checkout v2, Beta in Mobile 3.0, four issues in them) and a completed "Platform Reliability" next to the planned "Platform reliability". Without these, demo/golden mode could show only the success path. 38 existing golden outputs change, and only by those additions: milestone fields on issues, the extra project and the milestones.

Interface decisions

  • Always one extra request when --project/--milestone is not none, including for a UUID or slugId. A UUID could filter without a lookup, but then a mistyped or invisible id would again list nothing with exit 0. One request also checks the milestone against the project. With --cursor paging, each page repeats the lookup.
  • --milestone takes a UUID or name, not a URL: milestones have no slugId or URL form in the schema we read.
  • The project is not scoped by --team. A project can span teams, and scoping would make a name's meaning depend on another flag. A shared name is AMBIGUOUS, and the caller passes the slugId or URL from candidates.
  • PlaceResolve asks for first: 50, so candidates lists every match up to 50. project show keeps first: 2.

--json field names are unchanged. issue create / update still resolve --project by name only (untouched).

Tests

  • Unit: places_before_resolving checks list_filter for UUID, slugId, URL, name and none, milestone by id, by name, and by name within a project, plus the usage errors (--project none --milestone X, non-project URL, URL without id, control character). documents_match_the_schema covers PlaceResolve.
  • Acceptance (acceptance/places_test.go, the fake validates every request against the schema):
    • UUID, slugId, URL, unique name; milestone by UUID, by name, and by name within a project; project + milestone none. Each checks the exact PlaceResolve variables, that exactly PlaceResolve,IssueList were sent, and the id filter.
    • none sends no lookup.
    • Unknown name, unknown slugId, ambiguous project, ambiguous milestone, a milestone missing from the project, ambiguous within the project, and project-error precedence. Each checks code/kind/name/candidates and that no IssueList follows.
    • A Linear error on the lookup.
    • Bad references are usage with no request.
    • watch resolves once before WatchIDs and snapshots by id; watch with an unknown project fails NOT_FOUND.
    • TestIssueListFilters and TestMilestoneFilterAndList are updated for the id filter.
  • Golden (420335b, 20 demo cases): slugId, UUID, URL (text), non-project URL, unknown name (JSON and text), ambiguous name (JSON and text), slugId telling the two same-named projects apart, none, milestone by id, milestone by name within a project (JSON and text), ambiguous milestone (JSON and text), a milestone not in the project, --project none --milestone, and watch with an unknown project, an ambiguous project and an unknown milestone.

make check: fmt, clippy, gofmt, go vet, 41 unit + integration, acceptance ok, 420/420 golden, 20 skill files current.

Coverage (scripts/cover.sh, lines)

file before after
commands/issue.rs 98.61% (16 missed / 1155) 98.66% (17 / 1269)
commands/project.rs 100% 100%
demo.rs 94.29% 94.42%
queries.rs 98.48% 98.51%
commands/watch.rs 80.5–82.8% 80.6–81.6%
TOTAL 94.0–94.5% 94.1–94.4%

Of the new lines, only the panic! in the unit test helper is not run. The other missed issue.rs lines predate this change. watch.rs varies between runs on timing-dependent reconnect paths, before and after; its new line is covered.

project_filter reads a URL, slugId, UUID or name into a ProjectFilter, and
the NOT_FOUND / AMBIGUOUS decision over what it found becomes one_project.
Both are public so issue list and watch can read --project the same way;
project show and update behave as before.
--project went to Linear as a project name, so the UUID, slugId or URL
that project list and project show hand out matched nothing and listed no
issues with exit 0, and a name two projects share listed the issues of
both. --milestone had the same two failures, across projects.

Both are now looked up first, together in one request (PlaceResolve), and
the issue filter is by id. --project takes what project show takes: a
linear.app project URL, a slugId, a UUID or a name (ignoring case).
--milestone takes a UUID or a name, looked for in the --project project
when both are given. A reference that finds nothing is NOT_FOUND and a
name that finds several is AMBIGUOUS with candidates, each with kind and
name, as the rest of linearctl reports names. none still means "in no
project/milestone" and costs no request; --milestone NAME with
--project none is a usage error, since a milestone is a project's.

watch shares the filter, so it resolves them once, before its snapshot.
Linear repeats names: milestone names across projects, and project names
too. The demo had neither, so --project and --milestone could show only
their happy path there. Checkout v2 now has Beta and GA, Mobile 3.0 a Beta
of its own, a few issues sit in them, and a completed "Platform
Reliability" shares its name (ignoring case) with the planned one.

The golden outputs that list those issues, projects and milestones are
re-recorded; nothing else changes.
From the demo workspace: a project by slugId, UUID, URL and name; one
that matches nothing, and a name two projects share; none; a milestone by
id, by name within a project, a name two projects' milestones share, and
one the project does not have; --milestone with --project none; and watch
failing the same way before it streams.
The README, docs/design.md and AGENTS.md (and so the skill) said
--project takes a name. They now say which references it takes, that both
flags are resolved to ids in one request before listing, and how a
reference that finds nothing or several things fails. CHANGELOG entry
under Unreleased.
The lookup's own failure (a Linear error) ends issue list with LINEAR_ERROR before IssueList is sent; it was the one new line no test reached.

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 reported for the project and milestone reference-resolution changes.

No open issues 🎉

What changed in this PR

This PR makes project and milestone filtering in linearctl issue list and watch resolve references to unique IDs before reading issues, preventing silent empty results or results mixed across same-named projects.

Changes:

  • Reuses project reference parsing and adds a shared lookup with explicit NOT_FOUND and AMBIGUOUS errors.
  • Adds milestone and duplicate-name demo data, acceptance tests, and golden cases.
  • Updates command help, documentation, and generated skill references.
File Description
tests/​golden/​expected/​0419-watch-project-checkout-v2-milestone-Launch-json.txt Covers missing milestone in watch.
tests/​golden/​expected/​0418-watch-project-platform-reliability-json.txt Covers ambiguous project in watch.
tests/​golden/​expected/​0417-watch-project-Nope-json.txt Covers unknown project in watch.
tests/​golden/​expected/​0416-issue-list-project-none-milestone-Beta-json.txt Covers incompatible project/milestone flags.
tests/​golden/​expected/​0415-issue-list-project-Mobile-3-0-milestone-GA-json.txt Covers milestone outside the selected project.
tests/​golden/​expected/​0414-issue-list-milestone-beta.txt Covers text milestone ambiguity errors.
tests/​golden/​expected/​0413-issue-list-milestone-beta-json.txt Covers structured milestone ambiguity errors.
tests/​golden/​expected/​0412-issue-list-project-checkout-v2-milestone-BETA.txt Covers case-insensitive scoped milestone lookup.
tests/​golden/​expected/​0411-issue-list-project-Mobile-3-0-milestone-beta-fields-identifier-project-projectMi.txt Covers project-scoped milestone results.
tests/​golden/​expected/​0410-issue-list-milestone-ac0845c6-4c40-5517-86b9-d0c03f1e50d0-fields-identifier-proj.txt Covers milestone UUID filtering.
tests/​golden/​expected/​0409-issue-list-project-none-fields-identifier-project-json.txt Covers issues without a project.
tests/​golden/​expected/​0408-issue-list-project-9dd21914662d.txt Covers project disambiguation by slugId.
tests/​golden/​expected/​0407-issue-list-project-platform-reliability.txt Covers text project ambiguity errors.
tests/​golden/​expected/​0406-issue-list-project-platform-reliability-json.txt Covers structured project ambiguity errors.
tests/​golden/​expected/​0405-issue-list-project-Nope.txt Covers text unknown-project errors.
tests/​golden/​expected/​0404-issue-list-project-Nope-json.txt Covers structured unknown-project errors.
tests/​golden/​expected/​0403-issue-list-project-https-linear-app-northwind-issue-ENG-142-json.txt Covers rejection of non-project URLs.
tests/​golden/​expected/​0402-issue-list-project-https-linear-app-northwind-project-checkout-v2-baac88349ee8-o.txt Covers project URL filtering.
tests/​golden/​expected/​0401-issue-list-project-5DC3E15C-4273-5511-8167-BAAC88349EE8-fields-identifier-projec.txt Covers uppercase project UUID input.
tests/​golden/​expected/​0400-issue-list-project-baac88349ee8-fields-identifier-project-projectMilestone-json.txt Covers project slugId filtering.
tests/​golden/​expected/​0398-issue-list-view-checkout-bugs-json.txt Reflects milestones in saved-view results.
tests/​golden/​expected/​0384-complete-issue-list.txt Updates completion descriptions.
tests/​golden/​expected/​0361-issue-show-ENG-142-demo-json.txt Reflects the issue’s demo milestone.
tests/​golden/​expected/​0360-issue-list-demo-json.txt Reflects demo milestone assignments.
tests/​golden/​expected/​0308-project-show-checkout-v2-issues-0-json.txt Includes project milestone metadata.
tests/​golden/​expected/​0306-project-show-Checkout-v2-json.txt Includes milestones in project details and issues.
tests/​golden/​expected/​0299-milestone-list.txt Adds text demo milestone output.
tests/​golden/​expected/​0298-milestone-list-json.txt Adds JSON demo milestone output.
tests/​golden/​expected/​0295-project-list.txt Includes the second similarly named project.
tests/​golden/​expected/​0294-project-list-json.txt Includes the additional project’s metadata.
tests/​golden/​expected/​0272-issue-show-ENG-142-comments-json.txt Reflects milestone data alongside comments.
tests/​golden/​expected/​0268-issue-show-https-linear-app-northwind-issue-ENG-143-x-json.txt Reflects the GA milestone.
tests/​golden/​expected/​0262-issue-view-eng-142-comments-0-json.txt Reflects milestone data without comments.
tests/​golden/​expected/​0260-issue-show-ENG-142-json.txt Reflects the Beta milestone.
tests/​golden/​expected/​0249-issue-list-milestone-none.txt Excludes newly assigned milestone issues.
tests/​golden/​expected/​0240-issue-list-priority-urgent-priority-2-json.txt Reflects milestones in priority-filtered results.
tests/​golden/​expected/​0234-issue-list-id-ENG-142-id-ENG-9999-json.txt Reflects milestone data in partial results.
tests/​golden/​expected/​0232-issue-list-id-eng-142-id-ENG-131-json.txt Reflects milestone data in ID lookups.
tests/​golden/​expected/​0226-issue-list-query-coupon-json.txt Reflects milestones in search results.
tests/​golden/​expected/​0224-issue-list-project-checkout-v2-json.txt Reflects milestones in project-filtered results.
tests/​golden/​expected/​0216-issue-list-state-Todo-json.txt Reflects milestones in state-filtered results.
tests/​golden/​expected/​0212-issue-list-assignee-jonas-northwind-example-json.txt Reflects milestones in assignee-filtered results.
tests/​golden/​expected/​0208-issue-list-assignee-me-json.txt Reflects milestones in current-user results.
tests/​golden/​expected/​0202-issue-list-label-BUG-label-customer-reported-json.txt Reflects milestones in combined-label results.
tests/​golden/​expected/​0200-issue-list-label-bug-limit-0-json.txt Reflects milestones in all matching bugs.
tests/​golden/​expected/​0198-issue-list-limit-5-cursor-c5-json.txt Reflects milestone data on subsequent pages.
tests/​golden/​expected/​0196-issue-list-limit-5-json.txt Reflects milestone data on the first page.
tests/​golden/​expected/​0072-describe.txt Updates machine-readable flag descriptions.
tests/​golden/​expected/​0067-issue-list-help-json.txt Updates issue-list help expectations.
tests/​golden/​expected/​0048-issue-list-h.txt Updates short-help invocation output.
tests/​golden/​expected/​0047-watch-help.txt Documents watch’s startup lookup.
tests/​golden/​expected/​0023-issue-list-help.txt Documents accepted references and lookup errors.
tests/​golden/​cases.jsonl Adds 20 reference-resolution golden cases.
src/​queries.rs Adds and registers the combined PlaceResolve query.
src/​demo.rs Builds milestones and links them to demo issues.
src/​commands/​watch.rs Resolves references once before watching.
src/​commands/​project.rs Exposes shared project parsing and selection helpers.
src/​commands/​issue.rs Resolves filters to IDs and adds validation tests.
skills/​linearctl/​SKILL.md Documents supported project and milestone references.
skills/​linearctl/​references/​watch.md Refreshes generated watch documentation.
skills/​linearctl/​references/​issue.md Refreshes generated issue-list documentation.
README.md Explains reference filtering and error behavior.
docs/​design.md Records lookup semantics and command syntax.
demo/​workspace.json Adds milestones and a similarly named project.
CHANGELOG.md Records filtering fixes and demo changes.
AGENTS.md Updates reference guidance for callers.
acceptance/​places_test.go Tests resolution, errors, request order, and watch integration.
acceptance/​milestone_test.go Updates expectations to resolved milestone IDs.
acceptance/​issue_test.go Removes the superseded project-name filter expectation.

Review effort: Balanced

find_project keeps main's split, two light matches and one detail, and
decides on the matches through one_project, which issue list's --project
lookup shares. CHANGELOG's Unreleased holds #7's Added before this
branch's Changed and Fixed. The golden cases keep main's 0400-0405 and
follow them with this branch's; expected/ is re-recorded.
@linyiru
linyiru merged commit d0ce2ba into main Oct 28, 2026
4 checks passed
linyiru added a commit that referenced this pull request Oct 28, 2026
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.
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