Ledger filtering: --where queries and a viewer bottom pane

[NovusEdge]

Summary

docket list and docket graph take --where QUERY, a small query language parsed in one place, docket/where.py. The graph viewer uses the same language through its / prompt, and gains a bottom pane for filter, status, and key hints.

• Terms: kind:, state:, scope:PATH and scope:DIR/, is:pinned|corrected|retired|blocked, author:, branch:, after:, before:, and bare or quoted text. Repeated positive terms on one field are ORed, is: terms are ANDed, - negates a term, and different fields are ANDed.
• is:blocked keeps the viewer's meaning: an adopted, current decision that is not applicable. scope: asks which records govern a path, and it also matches top-level files.
• list includes retired records when the query asks for is:retired. graph --format and the no-viewer fallback honour --where. An invalid query exits 1 before the viewer starts.
• The viewer previews text terms live in Go, with the same fields, AND, negation, and quoting rules as Python; one JSON fixture keeps both tokenizers in agreement. On Enter, field terms go to a hidden docket _filter-ids through a JSON argv in DOCKET_GRAPH_FILTER_CMD. The CLI uses an environment variable because an older viewer binary exits on an unknown flag.
• The callback runs asynchronously with a 10 s timeout, empty stdin, and captured output. Stale results are dropped, and a failure restores the last applied filter.
• Layout: the title and search lines are gone. A three-line bottom pane appears at height 8 and above, a one-line pane at heights 4–7, and ? opens a full help overlay.

Test plan

• just test: 902 Python tests OK (6 skipped), plus the graph and installer Go suites
• just lint: ruff format and check, pyrefly, golangci-lint (graph, installer)
• cd graph && go test -race ./...
• CLI exercised against a scratch ledger: --where=-kind:question, _filter-ids -- -kind:question, is:retired with --format, invalid query before launch

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added --where filtering to docket list and docket graph, with support for text searches and terms for kind, state, scope, status, author, branch, and dates. Negation and quoted values are supported.
  • The graph viewer now previews text filters as you type, applies field filters on submission, shows match counts, and includes a ? help overlay. Filters can be cleared to show all records.
  • Graph exports now include only entries matching the filter.
• Changed
  • / in the graph viewer now opens query filtering instead of the previous single-substring search.
• Documentation
  • Added query syntax and viewer-filter guidance to the command and key-reference documentation.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: b7bb06bf-3a42-4737-ad79-ae258423e3f0

📥 Commits

Reviewing files that changed from the base of the PR and between ce04e82 and 329c7b2.

📒 Files selected for processing (19)

• .docket/ledger.jsonl
• CHANGELOG.md
• docket/cli/__init__.py
• docket/cli/completion.py
• docket/cli/graph.py
• docket/cli/query.py
• docket/where.py
• docs/commands.md
• docs/installer-reference.md
• graph/filter.go
• graph/filtercmd.go
• graph/main.go
• graph/main_test.go
• graph/model.go
• graph/pane.go
• graph/testdata/tokenizer_cases.json
• skills/docket/SKILL.md
• tests/test_docket.py
• tests/test_where.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

Walkthrough

The change adds query filtering to docket list and docket graph. Graph exports use matching entries, and the interactive viewer previews text terms and requests field-term matches through a CLI callback. The viewer also adds filter status, controls, and a help overlay.

Changes

Ledger query filtering

Layer / File(s)	Summary
Query language and list filtering docket/where.py, docket/cli/..., tests/test_where.py, docs/commands.md, CHANGELOG.md	Adds query parsing and matching for text and field terms, including negation, grouping, scope, and dates. docket list --where applies the query with existing filters. Tests and command documentation cover the language and its errors.
Graph command filtering and callback docket/cli/..., tests/test_docket.py, skills/docket/SKILL.md, .docket/ledger.jsonl	Applies queries to graph output and exports. The viewer receives initial matching IDs and a callback command for field queries. Tests cover exports, fallback rendering, callback setup, and _filter-ids.
Interactive viewer filtering graph/..., tests/test_where.py, docs/installer-reference.md, CHANGELOG.md	Adds live text preview, field-query callback handling, result and error status, and filter controls. The viewer also adds a bottom pane and help overlay. Tests cover filtering, command outcomes, and terminal layouts.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  actor User
  participant GraphViewer
  participant FilterModel
  participant DocketCLI
  User->>GraphViewer: Enter a field query
  GraphViewer->>FilterModel: Submit query
  FilterModel->>DocketCLI: Run _filter-ids with query
  DocketCLI-->>FilterModel: Return matching record IDs
  FilterModel-->>GraphViewer: Update visible rows and status

Loading

Merge Risk: ⚪ Minimal · up to 329c7

The new --where filtering for docket list and docket graph and the viewer's filter pane show no outstanding defects. Retired records and text fields reach the viewer consistently with the CLI filter, so the change looks ready to merge.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 134 functions across 13 files. (6 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: ledger --where filtering and the graph viewer bottom pane.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 10.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 134 functions across 13 files. (6 skipped: 6 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

Warning

Some tools did not complete. Review the errors below.

🔧 SkillSpector (2.11.0)

SkillSpector batch scan produced no output

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit taps a query key,
Text terms hop across the tree.
Field terms visit the CLI,
IDs return and rows comply.
A help pane shows the way,
Then carrots mark the filter day.}

_{Comment @coderabbitai help to get the list of available commands.}