fix(cli): reject unknown --timezone values by ryoppippi · Pull Request #1735 · ccusage/ccusage

ryoppippi · 2026-09-16T01:11:35Z

Closes #1730.

This carries forward #1732 by @ravsau, preserving the original commit author, and fixes the Linux CI regression found by the full workflow. The documented UTC value was being validated through the host zoneinfo database and could be rejected even though it is always supported by jiff.

The follow-up treats UTC as the built-in UTC timezone and local as the explicit system-timezone fallback, without relying on a zoneinfo lookup.

Validation:

exact failing zcode_cli integration test
cargo test -p ccusage-core -p ccusage (all passed)
just hawk (0 findings)
full pre-push hooks (Clippy, treefmt, gitleaks, Cargo tests)

Summary by cubic

Closes #1730. Unknown --timezone values now fail with a clear error and non-zero exit code instead of silently falling back to the system timezone and grouping usage under the wrong date.

Validation runs once after config and flags merge, so it checks the timezone the command will actually use.
It covers the shared flag, command-level --timezone/-z flags, the statusline flag, and config file timezone.
statusline now inherits the root --timezone value before its own -z flag applies.
UTC is always accepted without a zoneinfo lookup; local remains the documented system-timezone fallback.

^{Written for commit 56124d9. Summary will update on new commits.}

Summary by CodeRabbit

New Features
- Added timezone validation for command-line options and configuration files.
- Accepts valid IANA timezone names, local, UTC, or an unset timezone.
- Applies validation to command-specific timezone settings and flag overrides.
Bug Fixes
- Unknown timezone names now produce a clear error and non-zero exit status instead of silently using the system timezone.
- Shared timezone options now apply to statusline unless overridden.
Documentation
- Documented accepted timezone formats and validation behavior.

parse_tz swallowed the jiff error, so an unknown name such as a typo in America/New_York silently fell back to the system timezone and could group usage under the wrong date, with no error and no warning. The check runs once in the binary after config and flags are merged, next to the existing --last resolver, because the parser crate deliberately has no timezone dependency. It covers the shared flag, the statusline flag, and a config timezone, and only inspects the value the command will actually use. `local` stays accepted as the documented name for the system timezone.

Co-authored-by: Saurav Sharma <[email protected]>

cloudflare-workers-and-pages · 2026-09-16T01:11:46Z

Deploying with Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	ccusage-guide	`56124d9`	Commit Preview URL Branch Preview URL	Sep 16 2026, 01:27 AM

coderabbitai · 2026-09-16T01:11:49Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: f8bc0159-cbcf-4066-b5ac-a0afa34f20da

📥 Commits

Reviewing files that changed from the base of the PR and between a16c963 and 56124d9.

📒 Files selected for processing (2)

rust/crates/ccusage-cli-parser/src/parser.rs
rust/crates/ccusage/src/cli/timezone.rs

Included review availability: Your plan provides up to 10 included reviews per hour; 6 remain after this review.

📝 Walkthrough

Walkthrough

The change validates effective timezone values from CLI arguments and configuration files. It preserves local and UTC handling, rejects unknown names before report processing, propagates shared statusline values, adds tests, and documents the behavior.

Changes

Timezone validation

Layer / File(s)	Summary
Timezone parsing and validation `rust/crates/ccusage-core/src/date_utils.rs`	Adds `is_valid_timezone`. `parse_tz` handles `local` and `UTC` explicitly and resolves other names through `JiffTimeZone::get`. Tests cover aliases and an invalid name.
Effective CLI timezone validation `rust/crates/ccusage-cli-parser/src/parser.rs`, `rust/crates/ccusage/src/cli/timezone.rs`	Propagates shared timezone values to `statusline`, resolves the effective timezone for each command, and rejects invalid values. Tests cover command-specific values, precedence, and configuration defaults.
CLI wiring and documentation `rust/crates/ccusage/src/cli.rs`, `docs/guide/cli-options.md`	Runs timezone validation after CLI parsing and documents accepted timezone values and rejection behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant CliParser
  participant TimezoneValidator
  participant DateUtils
  participant UsageExit
  CliParser->>TimezoneValidator: Validate effective timezone
  TimezoneValidator->>DateUtils: Call is_valid_timezone
  DateUtils-->>TimezoneValidator: Return validation result
  TimezoneValidator->>UsageExit: Return usage error when invalid

Merge Risk: ⚪ Minimal · up to 56124

Timezone validation and statusline timezone propagation retain the configured value and root-flag override behavior, with no actionable current-head merge risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 52.94% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 17 functions across 4 files.	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 and concisely describes the main change: rejecting unknown --timezone values in the CLI.
Linked Issues check	✅ Passed	Issue `#1730` requires rejection of unknown timezone values from flags and configuration, exit code 2, support for `UTC` and `local`, validation after merged values are selected, and prevention of silen…
Out of Scope Changes check	✅ Passed	The timezone validator, `is_valid_timezone`, `parse_tz` alias handling, `statusline` inheritance fix, documentation, and automated tests directly support issue `#1730`. The reviewed changes contain no d…

Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/fix-invalid-timezone

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.98.0)

Clippy execution failed

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

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

pullfrog

ℹ️ Minor suggestions only — validation logic looks correct.

Reviewed changes

Reviewed fix(cli): reject unknown --timezone values for silent system-timezone fallback on typos.

Core validation helper — new is_valid_timezone accepts local and UTC without a zoneinfo lookup and checks everything else via JiffTimeZone::get.

Fallback-free parsing — parse_tz now maps local to system and UTC to TimeZone::UTC directly instead of a fallible lookup.

Single CLI checkpoint — new cli/timezone module validates the effective timezone once after config and flag merge, covering root flags, per-command flags, and config file values.

Docs — documents rejection of unknown names with a non-zero exit.

ℹ️ Nitpicks

The docs paragraph says the value must be an IANA name or local, while the code special-cases UTC as always accepted without a zoneinfo lookup. Naming UTC alongside local in that sentence would match the error message and the implementation.

^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Muse Spark Contributor (free via Pullfrog for OSS) ｜ 𝕏}

cubic-dev-ai

All reported issues were addressed across 4 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

pkg-pr-new · 2026-09-16T01:18:59Z

Open in StackBlitz

ccusage

npx https://pkg.pr.new/ccusage@1735

@ccusage/ccusage-darwin-arm64

npx https://pkg.pr.new/@ccusage/ccusage-darwin-arm64@1735

@ccusage/ccusage-darwin-x64

npx https://pkg.pr.new/@ccusage/ccusage-darwin-x64@1735

@ccusage/ccusage-linux-arm64

npx https://pkg.pr.new/@ccusage/ccusage-linux-arm64@1735

@ccusage/ccusage-linux-x64

npx https://pkg.pr.new/@ccusage/ccusage-linux-x64@1735

@ccusage/ccusage-win32-x64

npx https://pkg.pr.new/@ccusage/ccusage-win32-x64@1735

commit: 56124d9

github-actions · 2026-09-16T01:24:48Z

ccusage performance comparison

PR SHA: 5adeab30811f
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

github-actions · 2026-09-16T01:24:49Z

ccusage performance comparison

PR SHA: 5adeab30811f
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

github-actions · 2026-09-16T01:27:51Z

ccusage performance comparison

PR SHA: a16c9631810c
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

github-actions · 2026-09-16T01:28:10Z

ccusage performance comparison

PR SHA: a16c9631810c
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

pullfrog

✅ No new issues found.

Reviewed changes

Reviewed the delta since the prior pullfrog review (a16c963 → 56124d9).

Preserved root timezone for statusline — the statusline parser branch now clones the root shared.timezone into StatuslineArgs after config application, so ccusage --timezone <value> statusline is honored and validated like every other subcommand.
Extended timezone validation tests — rejection and acceptance cases now cover the root flag placed before statusline in both directions.

^{｜ Fix it ➔ ｜ View workflow run ｜ Using Muse Spark Contributor (free via Pullfrog for OSS) ｜ 𝕏}

github-actions · 2026-09-16T01:39:18Z

ccusage performance comparison

PR SHA: 56124d9e25ad
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

github-actions · 2026-09-16T01:39:19Z

ccusage performance comparison

PR SHA: 56124d9e25ad
Base SHA: ef300c97bc53

Performance comparison skipped.

Base package URL was not ready before 300.000s. Fixture performance comparison requires a base package when --base-dir is not provided.

Base package: ef300c97bc53

ravsau and others added 3 commits September 15, 2026 19:47

fix(cli): mention local in the --timezone error

ebc680f

fix(core): handle UTC without zoneinfo lookup

5adeab3

Co-authored-by: Saurav Sharma <[email protected]>

ryoppippi mentioned this pull request Sep 16, 2026

fix(cli): reject unknown --timezone values #1732

Closed

pullfrog Bot reviewed Sep 16, 2026

View reviewed changes

Comment thread docs/guide/cli-options.md Resolved

docs(cli): name UTC as an accepted timezone

a16c963

cubic-dev-ai Bot reviewed Sep 16, 2026

View reviewed changes

Comment thread rust/crates/ccusage/src/cli/timezone.rs Resolved

Comment thread docs/guide/cli-options.md Resolved

fix(cli): preserve root timezone for statusline

56124d9

pullfrog Bot reviewed Sep 16, 2026

View reviewed changes

ryoppippi merged commit a87f0d2 into main Sep 16, 2026
40 checks passed

ryoppippi deleted the codex/fix-invalid-timezone branch September 16, 2026 01:41

github-actions Bot mentioned this pull request Sep 16, 2026

chore: release v20.0.21 #1606

Merged

BrewTestBot mentioned this pull request Sep 17, 2026

ccusage 20.0.21 Homebrew/homebrew-core#311747

Merged

Conversation

ryoppippi commented Sep 16, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Summary by CodeRabbit

Uh oh!

cloudflare-workers-and-pages Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying with Cloudflare Workers

Uh oh!

coderabbitai Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

ℹ️ Nitpicks

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new Bot commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

github-actions Bot commented Sep 16, 2026

ccusage performance comparison

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ryoppippi commented Sep 16, 2026 •

edited by cubic-dev-ai Bot

Loading

cloudflare-workers-and-pages Bot commented Sep 16, 2026 •

edited

Loading

coderabbitai Bot commented Sep 16, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

pkg-pr-new Bot commented Sep 16, 2026 •

edited

Loading