Skip to content

Name every get-todos --json field with its type in help and docs - #130

Merged
muellerei merged 1 commit into
mainfrom
fix/get-todos-help-field-types
Oct 15, 2026
Merged

muellerei merged 1 commit into
mainfrom
fix/get-todos-help-field-types

Conversation

@muellerei

Copy link
Copy Markdown
Owner

Summary

 get-todos --help, --json paragraph
-  Each task has marker, content (...), page and uuid; journal_day when ...;
-  scheduled, deadline, next_due (dates as YYYY-MM-DD), repeating,
-  references, references_withheld where they apply.
+  Each task has marker, content, page, uuid and hash, all strings: ...
+  Where they apply: journal_day (...), scheduled, deadline, next_due (all four
+  strings, YYYY-MM-DD), repeating (true), references (a list of page names:
+  journals newest first, then other pages, which a date range withholds) and
+  references_withheld (a number).

The --help epilog and the get-todos row in docs/commands.md name every --json field with its type. The epilog had left out hash. A caller read references as a list of objects and failed; it is a list of page names as strings. docs/design.md said references names days; it names pages.

Closes #129

Evidence

  • Before: tests/test_get_todos_fields_documented.py against the old texts is red: the help misses hash, the reference row misses todos and count.
    After: green. Full suite 4049 passed, 8 skipped; ruff clean.
keys = every key in real get-todos --json output (mocked API)
for text in [--json paragraph of --help, --json paragraph of the docs row]:
  for key in keys:
    assert key is named in text

Removing any of the 15 keys from either text turns the test red (30 of 30).

Merge Danger

Door: two-way

Help text, docs and one test. The --json output does not change.

Blast Radius: none

The --help epilog left out hash, which the command reference listed, and
neither text gave a type: references is a list of page names as strings,
and a caller that read it as objects failed. Both texts now name each
field with its type and say how references is ordered.

A test takes the keys from real get-todos --json output and checks that
the --json paragraph of the help and of the reference row names each one,
so a new field fails until both texts have it.

docs/design.md said references names the days a task was carried into;
it names pages, ordinary pages included.
@muellerei
muellerei merged commit 372f0c7 into main Oct 15, 2026
6 checks passed
@muellerei
muellerei deleted the fix/get-todos-help-field-types branch October 15, 2026 23:41
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.

get-todos --help names every --json field with its type

1 participant