Skip to content

fix(cli): state how complete every list output is - #220

Merged
ysyneu merged 3 commits into
mainfrom
fix/list-completeness-notes
Oct 11, 2026
Merged

ysyneu merged 3 commits into
mainfrom
fix/list-completeness-notes

Conversation

@ysyneu

@ysyneu ysyneu commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

What

Every list output now states how complete it is, using one shared rule (listPage.statement in internal/cli/command.go), so a partial page is not mistaken for the whole set.

Rules, applied in order from what the API returned:

  1. total known: showing N of T, plus a next-page hint while rows remain
  2. else has_next_page / next cursor known: true warns, false is complete
  3. else a full page (N == limit): more may exist
  4. else only the plain count

A count is never printed as a total. Previously the generic renderer and several curated commands printed Total: <row count> when the response had no total.

Table mode prints the statement as a stdout footer. json/toon/jsonl print a note: line on stderr only when rows may be missing; stdout is byte-identical.

Examples (stub server):

$ fduty monit rule-list-basic --folder-id 7 --include-descendants --limit 2 --output-format json
stderr: note: showing 2 results (= limit 2); more may exist; raise --limit

$ fduty member list --output-format json      # total 45, 2 rows
stderr: note: showing 2 of 45 total results (page 1); raise --limit or use --page 2

$ fduty member list                           # table
Showing 2 results (page 1, total 45).

Changes

  • generated commands: printGenericResult takes the request body (cligen emits it, zz_generated_* regenerated) to learn the page and limit the request carried
  • alert events: adds --page / --limit (the SDK request supports them) and shows the real total
  • incident feed, alert timeline: surface has_next_page
  • incident alerts: adds --page; the total shows in every mode
  • incident similar, insight top-alerts: a full top-N list notes that more may exist
  • session list: notes when the fetch was capped by --limit
  • PrintTotal removed; callers use PrintList / PrintPage
  • skill cards regenerated for the new flags

Tests

New list_completeness_test.go: the four rules, a generated bare-array full page (stderr note, stdout unchanged), generic envelopes with has_next_page / next cursor in table mode, alert events, feed commands, incident similar. A few existing assertions on the old Total: N footer were updated.

make test, make build, make lint (0 issues) and make check-cards pass.

List commands printed a row count labelled "Total: N" when the response had
no total, and said nothing at all in structured mode or for bare-array
responses, so a capped page read as the whole set.

One helper (listPage.statement) now decides the statement from what the API
actually returned, in order: a known total ("showing N of T", plus a
next-page hint while rows remain); else has_next_page / a next cursor; else
a full page equal to the limit ("more may exist"); else the plain count. A
count is never printed as a total. Table mode prints the statement as a
stdout footer; json/toon/jsonl print a `note:` line on stderr only when rows
may be missing, so stdout is unchanged for jq/toon pipelines.

- generated commands: printGenericResult takes the request body (cligen now
  passes it) to learn the page and limit the request carried, and applies the
  helper to row arrays and list envelopes
- alert events: gains --page/--limit and shows the real total
- incident feed, alert timeline: surface has_next_page
- incident alerts: gains --page and shows the total in every mode
- incident similar, insight top-alerts: full top-N list notes more may exist
- session list: notes when the fetch was capped by --limit
- PrintTotal is removed; its callers use PrintList / PrintPage
A generated list called without --limit is served the API's default page
size, but the completeness check only knew about a limit the request carried,
so a full default page (e.g. 50 rules) went unannounced.

cligen now reads the structured integer `default` of a request's `limit`
property (never description text) and passes it to printGenericResult, which
uses it as the effective limit when the request set none. Commands whose
schema declares no default pass 0 and behave as before.
…notes

- Page numbering now comes from the request schema's structured default for
  the page property (1 = one-based, 0 = zero-based, none = unknown) through a
  generated Service.Method table (listDefaultsFor), shared by generated and
  curated commands together with the default page size. Zero-based lists no
  longer skip a page in the hint or false-alarm on their last page; when the
  base is unknown the note names no page number and claims a remainder only
  for the first page.
- The "rows remain" judgment from a page offset is made only when the offset
  is knowable (first page, or known page size and base); it no longer
  estimates the page size from the row count.
- alert events sends --limit/--page only when set and is judged against the
  schema default page size.
- Wording: singular "1 result", and one separator scheme across the rules:
  "showing <shown>, <reason>: <how to get more>".
@ysyneu
ysyneu merged commit 9fc6373 into main Oct 11, 2026
12 checks passed
@ysyneu
ysyneu deleted the fix/list-completeness-notes branch October 11, 2026 09:32
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.

1 participant