fix: normalize mail triage filters

[yangr-happy]

Summary

• Normalize mail +triage filter parsing for JSON, key=value, alias tokens, and split flags.
• Support is_read/is_unread compatibility while emitting canonical is_unread filters.
• Add focused mail shortcut tests for the supported filter forms and conflicts.

Tests

• go test ./shortcuts/mail -count=1

Summary by CodeRabbit

• New Features
  • Extended mail +triage --filter parsing to handle whitespace/empty input, JSON, standalone is_unread/is_read tokens, and key=value forms.
  • “Next page” stderr hints now build pagination flags from the effective triage settings (e.g., folder/unread), not the raw --filter text.
• Bug Fixes
  • Normalized/validated read/unread semantics: is_read=false → unread; is_unread=false ignored; is_read=true rejected with clearer schema guidance and suggestions.
• Documentation
  • Updated --print-filter-schema examples to match supported inputs, normalization, and alias behavior.
• Tests
  • Added coverage for parsing compatibility, merging/conflict detection, dry-run error consistency, and next-page hint preservation.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Changes

Mail triage now accepts JSON, token, and key=value filter forms, normalizes read-status inputs, merges standalone flags, rejects conflicts, and preserves runtime filter flags in next-page hints.

Mail triage filter flow

Layer / File(s)	Summary
Filter normalization and compatibility shortcuts/mail/mail_triage.go	Adds JSON, token, and key-value parsing; read-status normalization; conflict validation; updated schema examples; and field hints.
Filter construction and pagination integration shortcuts/mail/mail_triage.go	Uses buildTriageFilter for dry-run and execution, and appends changed runtime filter flags to pagination hints.
Filter parsing and triage regression coverage shortcuts/mail/mail_triage_test.go	Tests normalization, compatibility, conflict rejection, flag merging, dry-run errors, search parameters, and pagination hints.

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

Sequence Diagram(s)

sequenceDiagram
  participant Runtime
  participant MailTriage
  participant FilterBuilder
  participant PaginationHint
  Runtime->>MailTriage: provide filter and runtime flags
  MailTriage->>FilterBuilder: buildTriageFilter(runtime)
  FilterBuilder-->>MailTriage: return effective filter
  MailTriage->>PaginationHint: appendTriagePaginationFilterFlags(runtime)
  PaginationHint-->>Runtime: return next-page hint

Loading

Possibly related PRs

• larksuite/cli#301: Modifies triage pagination hint and page-token wiring.
• larksuite/cli#2025: Extends triage filter parsing, read-status handling, and runtime flag merging.

Suggested reviewers: chanthuang

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers summary and tests, but it omits the required Changes and Related Issues sections.	Add a Changes section with the main edits and a Related Issues section (or None) to match the template.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main change: normalizing mail triage filters.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

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

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (2)

shortcuts/mail/mail_triage.go (2)

534-549: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Case handling is inconsistent between bare tokens and key=value.

Bare tokens are lowercased (strings.ToLower(raw)), but the kv key is matched case-sensitively, so IS_UNREAD works while IS_UNREAD=true is rejected as an unknown key. Lowercase key for symmetry.

♻️ Proposed tweak

 	key, value, _ := strings.Cut(raw, "=")
-	key = strings.TrimSpace(key)
+	key = strings.ToLower(strings.TrimSpace(key))
 	value = strings.TrimSpace(value)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@shortcuts/mail/mail_triage.go` around lines 534 - 549, Normalize the key
extracted in the key=value path to lowercase before the switch in the triage
filter parser, matching the existing strings.ToLower handling for bare tokens.
Update the key normalization near strings.Cut so case variants such as
IS_UNREAD=true resolve through the same cases as lowercase keys.

---

447-457: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

dec.Decode(&extra) conflates malformed trailing data with "multiple JSON values".

Any non-EOF error (including a syntax error after the object) is reported as multiple JSON values. Minor, but distinguishing io.EOF from a decode error yields a truer message.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@shortcuts/mail/mail_triage.go` around lines 447 - 457, Update
parseTriageFilterJSON’s second dec.Decode(&extra) check to distinguish io.EOF
from other decode errors: keep EOF as the valid end-of-input case, but report
non-EOF decode errors as invalid JSON trailing data rather than multiple JSON
values; reserve the multiple-values message for successfully decoded additional
JSON.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/mail/mail_triage_test.go`:
- Around line 281-303: Update TestParseTriageFilterRejectsInvalidShorthands to
assert each error’s typed validation metadata via errs.ProblemOf
category/subtype, and use errors.As to verify *errs.ValidationError has Param
set to "--filter". Add a malformed-JSON case and assert its underlying decode
error remains unwrap-able, while retaining the existing message checks.

In `@shortcuts/mail/mail_triage.go`:
- Line 154: Update the pagination hint construction in the mail triage flow to
re-emit all filter flags merged by buildTriageFilter, including --folder,
--folder-id, --is-unread, and --is-read, in addition to --filter. Ensure the
suggested next-page command preserves the active query filters and page-token
semantics.
- Around line 503-518: Make read-status conflict validation deterministic by
processing is_unread before is_read outside the nondeterministic fields map
iteration in the triage filter parsing flow. Reuse the existing bool
unmarshalling and mergeTriageReadStatus logic, and ensure conflicting input
consistently reports is_unread as the offending source.
- Around line 545-583: Update the key=value parsing branch around the triage
filter parser so embedded key=value pairs such as “folder=INBOX,is_unread=true”
are detected and rejected with the existing typed --filter validation error
instead of being stored as part of a scalar value. Preserve valid scalar and
boolean parsing, and ensure unsupported input shapes cannot be silently coerced
or ignored.

---

Nitpick comments:
In `@shortcuts/mail/mail_triage.go`:
- Around line 534-549: Normalize the key extracted in the key=value path to
lowercase before the switch in the triage filter parser, matching the existing
strings.ToLower handling for bare tokens. Update the key normalization near
strings.Cut so case variants such as IS_UNREAD=true resolve through the same
cases as lowercase keys.
- Around line 447-457: Update parseTriageFilterJSON’s second dec.Decode(&extra)
check to distinguish io.EOF from other decode errors: keep EOF as the valid
end-of-input case, but report non-EOF decode errors as invalid JSON trailing
data rather than multiple JSON values; reserve the multiple-values message for
successfully decoded additional JSON.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 15f942cc-5539-442c-bf8a-ba8e131f76a3

📥 Commits

Reviewing files that changed from the base of the PR and between 3d2c10c and c12eb08.

📒 Files selected for processing (2)

• shortcuts/mail/mail_triage.go
• shortcuts/mail/mail_triage_test.go

[yangr-happy]

🤖 AI Review | CR 汇总 | 可合入前建议修复（1 个 P2）

增量审查：已读取现有评论并跳过 CodeRabbit 已提出且后续确认解决的问题。本次新增 1 个 P2 正确性问题：time_range 内部未知字段会在新解析器中被静默忽略，可能导致用户以为按时间过滤，实际请求未携带 create_time 条件。

本地仓库 clone 因 GitHub 443 连接超时未能完成，审查基于 gh pr diff、PR head 文件内容和已有检查状态；当前 GitHub checks 显示 CodeRabbit、CLA、sync-pr-labels 通过。

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@db9dcba732e0f14a6d1eeaa0f0bde9022ed610f1

🧩 Skill update

npx skills add yangr-happy/cli#feat/12cf2e5 -y -g