tztr 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e92587c8ab85fb2d8d30742355d39affa2732dfca85f3e2593f0b24747db174e
-  data.tar.gz: 9bcb138c9a6d4344251307e0d302e9ecd33d2b36a2ed00d28e6dfc3f15ed943a
+  metadata.gz: 6d285193d8b72f78de45ce70067ab31b21b41dd51845ee7cf3a875a2d7b896f0
+  data.tar.gz: 4c2780b1e58dc0d565aef9921d7a34159de1ecb84264f757baa8c01e51635496
 SHA512:
-  metadata.gz: 6a4438297ef18d9e41e8b2b9cf2a69c3c0edbadc6f22e5ef55ada8614f13bc4c838c125e5438e446ca7b34c9e0aac8123425f46656302ba019c4206764430397
-  data.tar.gz: 70432ef4777d42567ff4f84e34460e503a6d46de6216f1079621d4c6cc15c032c65684fce712b6c2c78350e7695aa4fa35662adcad4144ae92500baf64e544d2
+  metadata.gz: 6b275cd983a772305f7982de46e6877f39375c1793f905ed0f36315cc41f9bc288bb09c0f98c37176076a13453792402753acd677959cc92d0d7085c3575a985
+  data.tar.gz: c6e2c34828da29253654d7f550b6c024a43be89eb3e437ae35765e55f2d89841f82ac985bad1a623a88414cdad65b069e2878101052537bb9093ac5037b0da0b

data/CHANGELOG.md

@@ -1,2 +1,65 @@
+###  0.2.1  (2026-09-26)
+
+#### Breaking
+
+- A timestamp with no zone, with no `-f` and `$TZ` unset (the macOS default), is read in the system zone (`/etc/localtime`) and converted. It used to be taken to be in the output zone already and only relabelled: `12:00 | tztr -t utc` printed `12:00 UTC` on a Mac set to Pacific time; it now prints `19:00 UTC`. Set `-f` to choose another source zone.
+
+#### Fixed
+
+- The Ruby gem is about 4x faster than 0.2.0 on a mixed log, and on par with or faster than 0.1.0: lines without a timestamp are skipped before the scan, zone lookups are cached, and a time without a zone no longer switches `$TZ` and back to convert.
+
+###  0.2.0  (2026-09-26)
+
+0.1.0 reached users twice: the gem in April, then the Rust crate and Homebrew
+formula in June, which already had `-j`, `-J`, `--detect`, `-d` and `-v`/`-V`.
+Entries marked *(gem)* are new only to gem users.
+
+#### Breaking
+
+Before upgrading, check any script that passes `-t gmt`, a numeric offset,
+`-F`, `-d` or `-v`, or that relies on an unknown timezone falling back to UTC.
+Also check logs with zone abbreviations tztr used to ignore (`CET`, `BST`,
+`JST`), and runs where `TZ` is set to a zone outside the US.
+
+- `-t gmt` now means UTC. It used to follow British Summer Time; use `-t london` for civil UK time.
+- A timezone that can't be resolved is an error (exit 1) instead of silently becoming UTC. That includes `TZ` itself: the POSIX spelling `TZ=:America/New_York` used to make every conversion come out in UTC.
+- Numeric offsets are whole hours in `-12..14`. Sub-hour offsets (`-t +5:30`) are refused rather than silently mis-signed; reach a half-hour zone by name (`-t ist`, `-t Asia/Kolkata`).
+- Zone abbreviations inside text convert as the fixed offset they name. `JST`, `CET`, `BST`, `IST`, `AEST` and the rest used to be ignored, so the time was read as if it were in the source zone. Only the generic `ET`, `CT`, `MT` and `PT` follow DST, so `CEST` is +02:00 even in January. `CET` is +01:00 even in summer, which means a log that writes `CET` year-round for Berlin time converts an hour off from Berlin's clock in summer.
+- An abbreviation your source zone (`-f`, else `$TZ`) uses itself is read in that zone's sense. With `TZ=Asia/Shanghai`, `CST` is China Standard Time (+08:00), not US Central. `PST` in Manila and `IST` in Dublin or Jerusalem change the same way. With `TZ` unset, UTC or anywhere in the US, nothing changes.
+- `-F short` always labels the zone. It used to drop the label whenever the output zone matched `$TZ`, which is every run without `-t`. *(gem)* `-F short` and `-F iso` used to carry no zone or offset at all; they now end in `PDT` and `-07:00`.
+- `-d` accepts only `2026-01-15`, `2026/01/15`, `20260115`, `January 15, 2026`, `Jan 15 2026` and `15 January 2026`, with two-digit months and days and real calendar dates. Anything else is an error. The gem used to take whatever Ruby's `Date.parse` would (`Sept 15`, `2026-1-5`, a date with no year).
+- *(gem)* `-v` is `--verbose`; the version is `-V/--version`.
+- Library: `resolve_tz` raises `Tztr::Error` (Ruby) / returns `Result<String, TzError>` (Rust), and `translate`/`matches` no longer take a `local` parameter.
+
+#### Added
+
+- `tztr now` prints the current time, as ISO 8601 in `-t`, else `$TZ`, else UTC. Every flag except `-i` works with it.
+- `-v` says what it assumed: the source zone it borrowed from `$TZ`, the date it assumed for DST when there's no `-d`, and any zone abbreviation it passed over for its case (`Pst`) or didn't know (`EEST`).
+- `-j`/`-J` add `group: {type, members}` to a timestamp in a range or list. *(gem)* `-j/--json`, `-J/--ndjson`, `--detect` and `-d/--date` are new.
+- Ranges and lists share the zone and AM/PM written at their end, and a date written at their start: `from 3:30 to 4:45 PM PST` and `3:00, 4:00 or 5:00 PM PST` convert every member. A range is joined by `-`, `–`, `—`, `to`, `until`, `till`, `through` or `thru`; a list by commas, `or` and `and`.
+- More formats, each converted date and all: nginx/Apache access logs (`[15/Jan/2015:12:31:01 -0700]`), slashed dates (`2026/09/25 23:14:42`, Go's log package and nginx's error log), `ls -lT` (`Sep 25 23:40:39 2026`), and glibc's locale form of `date` (`Fri 25 Sep 2026 10:14:42 PM PDT`).
+- A dated clock with seconds takes a numeric offset, glued or spaced: `2026-09-25 22:14:42-07:00` (Python, `date --rfc-3339`), `2026-04-03 09:00:00-07` (Postgres). ISO 8601's comma fraction (`…T22:14:42,123456789-07:00`) is read too.
+- 12-hour forms: `3:45 p.m.`, `11:30 A.M.`, hours alone (`9am`, `9 PM PST`), and a no-break space before AM/PM, as Chrome and macOS write it.
+- Lowercase zone abbreviations (`15:30 pst`), except `est`, `cet`, `et`, `ist`, `ut` and `z`, which are ordinary words that can follow a time.
+- A time followed by a unit of time is left alone as a duration: RSpec's `Finished in 1:05 minutes`.
+
+#### Fixed
+
+- A dated timestamp without seconds keeps its date. `2026-01-15 23:30` used to be read as a time alone, resolved against today, an hour off in winter; `2026-12-31T23:30+05:30` came out garbled and `2026-12-31T23:30Z` was ignored.
+- `date` output and RFC 2822 dates convert as one timestamp. `date | tztr -t est` used to convert only the clock, so `Fri Sep 25 22:14:42 PDT 2026` came out as `Fri Sep 25 01:14:42 EDT 2026`, a day early; it is now `Sat Sep 26 01:14:42 EDT 2026`. A `date` line with a zone tztr can't resolve (`WIB`) is left as written.
+- A 12-hour time is read in its source zone. AM/PM used to be taken for a zone name, so `11:30 PM` was assumed to be in the output zone already and the `PST` of `3:45 PM PST` was ignored.
+- Every timestamp on a line converts, whatever its format. Only the first format found used to convert, so in `{"ts":"2026-04-03T12:00:00Z","msg":"at 15:30 UTC"}` the `15:30 UTC` was left alone with no warning. A bare time with no date, zone or AM/PM is still left alone when another timestamp on its line has one, as the `0:05` of `2026-04-03T12:00:00Z took 0:05` is most likely a duration.
+- In a range or list with no date, a member earlier on the clock than the one before it is on the next day: `11:30 PM to 12:30 AM` ends tomorrow.
+- A numeric offset glued to a time must follow seconds (`12:34:56-05:00`), and every offset must be within -12..+14. `15:30-16:45 PST` used to be read as 15:30 at an offset of −16:45.
+- Log levels stay in the line: `15:30 INFO server started` keeps its `INFO`.
+- Fractional seconds keep every digit (Docker's nanoseconds were cut to milliseconds), and Python logging's `12:00:00,123` keeps its comma milliseconds.
+- IPv6 addresses (`fe80::1:23:45`) and SMPTE timecodes (`01:02:03:04`) are left alone instead of having a "time" inside them converted.
+- An ambiguous wall clock in a repeated fall-back hour resolves to the earlier (daylight) occurrence, matching `date(1)`, Temporal, RFC 5545 and ICU.
+- `24:00` and a leap-second `23:59:60` normalize; impossible calendar dates (`2026-02-30`) are left exactly as found instead of being rewritten to a different day.
+- A file that can't be read no longer stops a multi-file run. It is reported, every other file is still processed, and the exit status is 1, as with `cat` and `sed -i`. With `-i` it used to leave the job half-done: files before the bad one rewritten, files after it untouched.
+- Errors are one line, with no backtrace, and an error about a file names it.
+- Lines that aren't valid UTF-8 keep their bytes, in every output mode including `-i`.
+- Rust build: the POSIX `--` terminator works, and `tztr -h` and `tztr -l` match the gem byte for byte.
+
 ###  0.1.0  (2026-04-19)
 

data/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`tztr` is a small CLI + library that translates timestamps between timezones. It auto-detects timestamp formats in arbitrary text, converts them, and preserves the surrounding text and original format by default.
+
+- Library entry point: `lib/tztr.rb` (single file, `Tztr` module)
+- Executable: `bin/tztr` (uses OptionParser, streams stdin/files line-by-line)
+- Required Ruby: `>= 3.2`. CI runs against 3.3, 3.4, and 4.0.
+
+## Dual implementation — Ruby (reference) + Rust (port)
+
+This repo ships **two implementations kept functionally identical**: the Ruby
+gem at the root (`lib/`, `bin/`) and a Rust crate under `rust/` (`cargo install
+tztr`; Homebrew installs the Rust binary). Ruby is the **reference**; Rust
+mirrors it.
+
+**Parity is the contract.** Any behavior change must land in *both* and keep the
+CLI outputs identical:
+1. Change Ruby (`lib/tztr.rb` / `bin/tztr`), add/adjust specs, `bundle exec rspec`.
+2. Port the change to Rust under `rust/tztr/`, add/adjust tests, `make check`
+   (`cargo fmt --check` + clippy `-D warnings` + `cargo test`).
+3. `make parity` (or `ruby script/parity.rb`) — the Ruby ↔ Rust CLI parity
+   harness diffs both binaries across a matrix of inputs/args/`TZ`; JSON modes
+   compared semantically, everything else byte-for-byte. Must be 100%.
+
+CI (`.github/workflows/rust.yml`) runs the Rust gate + parity; `make hooks`
+installs a pre-push hook that runs rspec + `make check` + `make parity`.
+Timezone math in Rust uses `jiff` (system tzdb, same source as Ruby's `Time`),
+so DST matches. Watch the replicated `Time.parse` quirks documented in
+`rust/REPORT.md` (unrecognized abbreviations ignored; `from` bypassed when an
+embedded zone is present).
+
+## Commands
+
+```bash
+bundle install                 # install deps
+bundle exec rspec              # run all tests
+bundle exec rspec spec/tztr_spec.rb:42   # run a single test by line number
+bin/tztr ...                   # run the CLI from a working copy (no install needed)
+gem build tztr.gemspec         # build the gem
+```
+
+There is no Rubocop / linter configured — only RSpec + SimpleCov. `--require spec_helper` is set in `.rspec`, so specs don't need to require it explicitly.
+
+## Architecture notes
+
+A few things that aren't obvious from a quick read:
+
+**`Tztr.translate` mutates `ENV['TZ']`.** Both `translate` and `parse` set `ENV['TZ']` as a side effect to coerce Ruby's `Time` parsing into the right zone. The spec helper resets `ENV['TZ'] = 'UTC'` in a `before(:each)` to keep tests isolated — anything new that exercises parsing should rely on that, or save/restore `TZ` itself.
+
+**Pattern order is priority, not exclusivity.** `PATTERNS` in `lib/tztr.rb` is joined into one alternation (`TIMESTAMP`, and `timestamp()` in Rust) and scanned in a single pass, so every timestamp on a line converts whatever its format. At each position the alternatives are tried top-to-bottom, so more specific patterns (ISO with timezone) must come before less specific ones (bare time) or a shorter format will match inside a longer one. A bare time (`BARE_TIME`) beside a timestamp that names its date or zone is left alone as a probable duration (`Tztr.timestamps`); only a line of nothing more specific converts its bare times. Before that, each member of a range or list (`3:30 to 4:45 PM PST`, `3:00, 4:00 or 5:00 PM`; `RANGE_JOIN` / `LIST_JOIN`) takes the zone and meridiem after it, and `-j` reports the members as `group`. A bare hour counts only as the start of a range (`RANGE_HOUR`, the 9 of `9-9:15am`). A numeric offset glued to a time needs seconds, so `15:30-16:45` is a range. When adding a new format, place it carefully and add tests covering lines that mix formats.
+
+**A match's text and its reading differ.** Each match is a `Stamp` with the `text` it replaces and the `effective` reading it is parsed as (`Tztr.reading`): a named-month date (date(1), RFC 2822, CLF) normalized to `YYYY-MM-DD`, `9am` to `9:00am`, a slashed date dashed, a comma fraction dotted, plus whatever zone, meridiem or date it shares with its range. Parse the reading; format from the text, so the output keeps the input's shape.
+
+**Zones inside text are fixed offsets; zones given to `-f`/`-t` are IANA.** `CEST` in a line is always +02:00 (`ZONE_OFFSETS`), but `-t est` is New York with DST. Only the generic `ET`/`CT`/`MT`/`PT` follow DST inside text. An abbreviation the source zone itself uses this year wins over the table (`local_abbreviations`): `CST` under `TZ=Asia/Shanghai` is +08:00; under any zone that doesn't use it, the US-centric table stands. A dateless timestamp's date is today *where it was written* (`today_where` in Ruby, `anchor` in Rust), never Time.parse's own guess.
+
+**Timezone resolution has three layers** (`Tztr.resolve_tz`):
+1. Numeric offset string (e.g. `"-7"`) → `Etc/GMT±N` — note the POSIX sign inversion (`-7` becomes `Etc/GMT+7`).
+2. Lowercased + underscored lookup in `TIMEZONE_ALIASES` (covers tz abbreviations like `pst`, plus city nicknames like `sf`, `nyc`).
+3. Validated against the system tzdb as an IANA name like `America/Los_Angeles` — an unknown name raises `Tztr::Error` rather than passing through.
+
+**Output format preservation** (`format_time`) inspects the *original* matched substring and rebuilds the output to mirror it (ISO `T`, space-separated, time-only, with/without fractional seconds). Explicit `--format iso|short|time` short-circuits this.
+
+**CLI streaming.** `bin/tztr` sets `$stdout.sync = true` and processes input line-by-line so it works with `tail -f`. `-i/--in-place` reads, translates, and writes back only if content changed.
+
+**Structured output is agent-facing.** `-j/--json` (array) and `-J/--ndjson` (one object per line, streaming-friendly) emit `{original, detected_format, detected_tz, translated}` per match, backed by `Tztr.matches`. `--detect` reports format/zone only (omits `translated`). **Directive: every new CLI option must work in `-j`/`-J` modes** — when adding a flag, make sure it composes with structured output (e.g. `-F` shapes the `translated` field) and add a spec covering it. `-i` is the one exception: it's mutually exclusive with `-j`/`-J`/`--detect` and aborts.
+
+## Testing beyond the suites
+
+The parity harness only proves the two builds agree; several rounds of bugs were ones both builds shared. `script/parity.rb` has a `golden` group of absolute expectations for exactly those. Add to it whenever a bug is found in both builds at once.
+
+User-testing rounds (logs and reports archived locally under `research/`, which is gitignored) found the most with these kinds of input. Reuse them for any matching change:
+
+- **Real machine logs, read-only**: macOS `/var/log/*.log`, `log show --style syslog|default`, `ls -lT`, `git log` (`--format=fuller`, `--date=iso|rfc`), real `date`, `date -u`, `date -R` and `TZ=<far zone> date` output, and Rails `log/*.log` and nginx access/error logs found in local checkouts.
+- **Formats from memory, where no real sample exists**: Lograge, ActiveJob, Sidekiq JSON/text, RSpec output (`Finished in 1:05 minutes`), crontab lines and cron syslog, RFC 5424/journald, Postgres, Docker/k8s RFC3339Nano, GitHub Actions, Go's `log` package, Python `logging` (comma milliseconds), log4j, multi-field JSON/NDJSON.
+- **Prose**: meeting invites, standup notes and on-call handoffs with ranges and lists written every way people write them (`9-9:15am`, `3:00, 4:00 or 5:00 PM`, `11:30 PM to 12:30 AM`), deadlines next to dates (`Apr 3 - 5pm`), and French and German text (`à 15:30 est annulée`).
+- **Things that aren't timestamps**: durations, line numbers (`foo.rb:42:10`), `ip:port`, versions, ratios, scores, cron fields, ticket numbers (`#12 - 9:30am`).
+- **Adversarial input**: Latin-1 and invalid UTF-8 bytes beside a match, fullwidth and Arabic-Indic digits, glued offsets (`15:30-1645`), impossible clocks (`99:14`), and 100k+ character lines, timed to catch quadratic paths.
+- **Date boundaries**: midnight, month, leap-day and year ends toward far zones (`Pacific/Kiritimati` +14, `Pacific/Pago_Pago` −11, `Asia/Kathmandu` +5:45), DST transition days in the US, UK and Australia, and anything that depends on today's date (run with `-t 14` and `-t -12`).
+
+## Release / distribution
+
+Distributed via RubyGems (`gem install tztr`) and Homebrew (`brew install dpep/tools/tztr`). Version lives in `lib/tztr/version.rb`. Dependabot auto-approves and auto-merges minor/patch dependency PRs (see `.github/workflows/dependabot.yml`).

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    tztr (0.1.0)
+    tztr (0.2.1)
+      optparse (>= 0.5)
 
 GEM
   remote: https://rubygems.org/
@@ -12,13 +13,15 @@ GEM
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
     docile (1.4.1)
-    erb (6.0.2)
+    erb (6.0.4)
+    ice_age (0.2.0)
     io-console (0.8.2)
     irb (1.17.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
+    optparse (0.8.1)
     pp (0.6.3)
       prettyprint
     prettyprint (0.2.0)
@@ -62,6 +65,7 @@ PLATFORMS
 
 DEPENDENCIES
   debug (>= 1)
+  ice_age (>= 0.2)
   rspec (>= 3.10)
   rspec-debugging
   simplecov (>= 0.22)
@@ -72,9 +76,11 @@ CHECKSUMS
   debug (1.11.1) sha256=2e0b0ac6119f2207a6f8ac7d4a73ca8eb4e440f64da0a3136c30343146e952b6
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   docile (1.4.1) sha256=96159be799bfa73cdb721b840e9802126e4e03dfc26863db73647204c727f21e
-  erb (6.0.2) sha256=9fe6264d44f79422c87490a1558479bd0e7dad4dd0e317656e67ea3077b5242b
+  erb (6.0.4) sha256=38e3803694be357fe2bfe312487c74beaf9fb4e5beb3e22498952fe1645b95d9
+  ice_age (0.2.0) sha256=2cfd333ac6791d2e8abaf3060afd0c88c57868beca40d0d9579b7c5534bbbb73
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   irb (1.17.0) sha256=168c4ddb93d8a361a045c41d92b2952c7a118fa73f23fe14e55609eb7a863aae
+  optparse (0.8.1) sha256=42bea10d53907ccff4f080a69991441d611fbf8733b60ed1ce9ee365ce03bd1a
   pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
   prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
   prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
@@ -92,7 +98,7 @@ CHECKSUMS
   simplecov_json_formatter (0.1.4) sha256=529418fbe8de1713ac2b2d612aa3daa56d316975d307244399fa4838c601b428
   stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
   tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
-  tztr (0.1.0)
+  tztr (0.2.1)
 
 BUNDLED WITH
   4.0.9

data/Makefile

@@ -0,0 +1,65 @@
+# tztr — dual implementation (Ruby reference + Rust port).
+#
+#   make build       - release build of the Rust CLI into rust/target/release
+#   make install     - cargo install the Rust CLI into ~/.cargo/bin
+#   make test        - run both test suites (rspec + cargo test)
+#   make check       - Rust gate: cargo fmt --check + clippy + test
+#   make fmt         - cargo fmt the Rust crate
+#   make parity      - Ruby <-> Rust CLI parity harness (builds Rust first)
+#   make hooks       - enable the committed git hooks (pre-push runs parity+check)
+#
+# Ruby is the reference implementation; Rust mirrors it. See CLAUDE.md for the
+# parity contract.
+
+CARGO    ?= cargo
+RUST_DIR := rust
+
+.DEFAULT_GOAL := help
+.PHONY: help build install test check fmt parity hooks
+
+help:
+	@echo "tztr targets:"
+	@echo "  make build       release build of the Rust CLI"
+	@echo "  make install     cargo install the Rust CLI"
+	@echo "  make test        rspec + cargo test"
+	@echo "  make check       Rust gate: fmt --check + clippy + test"
+	@echo "  make fmt         cargo fmt the Rust crate"
+	@echo "  make parity      Ruby <-> Rust CLI parity harness"
+	@echo "  make hooks       enable committed git hooks (.githooks)"
+
+build:
+	$(CARGO) build --release --manifest-path $(RUST_DIR)/Cargo.toml
+
+install:
+	$(CARGO) install --path $(RUST_DIR)/tztr
+
+test:
+	bundle exec rspec
+	$(CARGO) test --manifest-path $(RUST_DIR)/Cargo.toml
+
+# The Rust gate — mirrors CI. Run before merging/pushing.
+check:
+	cd $(RUST_DIR) && $(CARGO) fmt --check
+	cd $(RUST_DIR) && $(CARGO) clippy --workspace --all-targets -- -D warnings
+	cd $(RUST_DIR) && $(CARGO) test --workspace
+
+fmt:
+	cd $(RUST_DIR) && $(CARGO) fmt
+
+# A bare `ruby` here is macOS system Ruby 2.6 whenever rbenv's shims are off
+# PATH and `rbenv global` is unset, and the harness then reports every case as
+# failing for reasons unrelated to parity. Pick the first interpreter that
+# satisfies the gemspec instead; override with `make parity RUBY=/path/to/ruby`.
+RUBY_CANDIDATES := ruby $(shell rbenv root 2>/dev/null)/versions/*/bin/ruby /opt/homebrew/opt/ruby/bin/ruby
+RUBY ?= $(shell for r in $(RUBY_CANDIDATES); do \
+	  "$$r" -e 'exit Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.2")' 2>/dev/null \
+	    && echo "$$r" && break; \
+	done)
+
+parity: build
+	@test -n "$(RUBY)" || { echo "make parity: no Ruby >= 3.2 found (tried: $(RUBY_CANDIDATES))"; exit 1; }
+	$(RUBY) script/parity.rb
+
+hooks:
+	git config core.hooksPath .githooks
+	@echo "git hooks enabled (.githooks) — pre-push now runs parity + check"

data/README.md

@@ -3,17 +3,24 @@ tztr
 ![Gem](https://img.shields.io/gem/dt/tztr?style=plastic)
 [![codecov](https://codecov.io/gh/dpep/tztr/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/tztr)
 
-Timezone Translator - convert timestamps to local time.
+Timezone Translator: find the timestamps in any text and convert them to
+another timezone, leaving everything else alone.
 
-Reads from stdin or file, auto-detects timestamp formats, and preserves the original format by default.
+Reads from stdin, files, or the clock (`tztr now`), auto-detects timestamp
+formats, and preserves each one's original format by default.
 
 
 ## Install
 
 ```bash
-gem install tztr
+brew install dpep/tools/tztr   # the Rust binary
+gem install tztr               # Ruby
+cargo install tztr             # Rust, from source
 ```
 
+The gem and the crate are two implementations of the same tool, kept
+functionally identical. Same CLI, same output.
+
 
 ## Usage
 
@@ -22,24 +29,60 @@ echo '2026-04-03T12:00:00Z' | tztr -t America/Los_Angeles
 # 2026-04-03T05:00:00-07:00
 
 echo '15:30 UTC' | tztr -t America/New_York
-# 11:30 EDT
+# 11:30 EDT   (a time with no date resolves against today; in January, 10:30 EST)
 
 tail -f app.log | tztr
+
+tztr now -t tokyo
+# 2026-09-27T07:28:30+09:00   (whatever the time is)
 ```
 
+`tztr now` reads the current time as though it were piped in, so every flag
+works with it (`-F short`, `-j`, `--detect`) except `-i`. It prints ISO 8601 in
+`-t`, else `$TZ`, else UTC. To read a file named `now`, write `./now`.
+
+Several files are processed in order. A file that can't be read is reported
+and skipped, the rest still run (and with `-i`, are still rewritten), and the
+exit status is 1, as with `cat` and `sed -i`.
+
 ### Options
 
 ```
--f, --from TZ       Input timezone (default: auto-detect)
--t, --to TZ         Output timezone (default: UTC)
+-f, --from TZ       Input timezone for timestamps that name none (default: $TZ, else the system zone)
+-t, --to TZ         Output timezone (default: $TZ, else UTC)
+-l, --list          List timezone aliases
+-i, --in-place      Edit files in place
 -F, --format FMT    Output format: iso, short, time (default: preserve input)
--v, --version       Show version
+-d, --date DATE     Reference date for time-only inputs (resolves DST)
+-j, --json          Emit a JSON array of matches
+-J, --ndjson        Emit newline-delimited JSON (one object per match)
+    --detect        Report detected format/zone without converting
+-v, --verbose       Print diagnostics to stderr
+-V, --version       Show version
 -h, --help          Show this help
 ```
 
-### Environment
+`-F` replaces the preserved format with one of:
+
+| `-F`    | Output                      |
+|---------|-----------------------------|
+| `iso`   | `2026-04-03 08:30:00-07:00` |
+| `short` | `2026-04-03 08:30 PDT`      |
+| `time`  | `08:30:00`                  |
+
 
-Set `TZ` to change the default output timezone (overridden by `-t`):
+## Timezones
+
+`-f` and `-t` take an IANA name (`America/Los_Angeles`), an alias or
+abbreviation (`pst`, `nyc`, `jst`; `tztr -l` lists them all), or a whole-hour
+numeric offset from `-12` to `14` (`-8` → `Etc/GMT+8`). Sub-hour offsets
+aren't accepted; reach a half-hour zone by name: `-t ist`, `-t Asia/Kolkata`.
+
+Names given to `-f` and `-t` are real zones that follow DST: `-t est` is New
+York time, EDT in summer. `gmt` means UTC; for civil UK time, which follows
+British Summer Time, use `-t london`.
+
+`TZ` sets the default for both sides, and `-f`/`-t` override it:
 
 ```bash
 export TZ=America/Los_Angeles
@@ -47,16 +90,251 @@ echo '2026-04-03T12:00:00Z' | tztr
 # 2026-04-03T05:00:00-07:00
 ```
 
-### Supported Formats
+A timestamp that names its own zone is read in that zone, whatever `-f` says.
+One that doesn't is read in `-f`, else `$TZ`, else the machine's own zone (the
+one `/etc/localtime` points to, as on macOS, where `TZ` is usually unset):
+
+```bash
+echo '12:00' | env -u TZ tztr -t utc -d 2026-04-03
+# 19:00 UTC   (on a Mac set to Pacific time)
+```
+
+Only if no system zone can be found either is it taken to be in the output
+zone already, and labelled rather than converted.
+
+A zone that can't be resolved is an error: exit 1, nothing on stdout.
+
+```bash
+echo '15:30 UTC' | tztr -t Mars/Phobos
+# tztr: unknown timezone: Mars/Phobos
+```
+
+
+## Supported formats
+
+Every timestamp on a line converts, whatever its format, and everything around
+it (quotes, JSON, log levels) passes through untouched.
+
+### What converts
 
 - ISO 8601: `2026-04-03T12:00:00Z`, `2026-04-03T12:00:00+05:30`
-- Date + time: `2026-04-03 12:00:00 UTC`
-- Time only: `15:30 UTC`, `08:30:45 PDT`
-- Fractional seconds: `2026-04-03T12:00:00.123Z`
+- Date + time: `2026-04-03 12:00:00 UTC`, and slashed as Go's log package and
+  nginx's error log write it, `2026/04/03 12:00:00`
+- A numeric offset after the seconds, glued or spaced, as Python,
+  `date --rfc-3339` and Postgres write it: `2026-09-25 22:14:42-07:00`,
+  `2026-04-03 09:00:00-07`
+- `date` output: `Fri Sep 25 22:14:42 PDT 2026`, with or without the weekday
+  (`ls -lT`) or zone (ctime), a numeric zone (`+03`), and glibc's locale form,
+  `Fri 25 Sep 2026 10:14:42 PM PDT`
+- Email and HTTP dates (RFC 2822): `Fri, 25 Sep 2026 22:14:42 -0700`
+- nginx/Apache access logs: `[15/Jan/2015:12:31:01 -0700]`
+- Time only: `15:30 UTC`, `08:30:45 PDT`, `12:00 +0530`, `12:34:56-05:00`
+- 12-hour: `11:30 PM`, `3:45 p.m.`, `11:30 A.M.`, `3:45 PM PST`, and an hour
+  with AM/PM: `9am`, `9 PM PST`
+- Fractional seconds, kept to the nanosecond: `…T12:00:00.123456789Z`, the ISO
+  comma (`…T12:00:00,123456789Z`), and Python logging's comma milliseconds,
+  `2026-04-03 12:00:00,123`
+
+Dated timestamps convert date and all, so `Fri Sep 25 22:14:42 PDT 2026` in
+New York is `Sat Sep 26 01:14:42 EDT 2026`. The output keeps the input's shape,
+seconds and fraction, except that a 12-hour time comes out on the 24-hour
+clock (`11:30 PM` → `23:30 UTC`); only `date`'s locale form and RFC 2822 keep
+their AM/PM.
+
+**Seconds** are optional (`2026-04-03 15:30`, `2026-04-03T15:30Z`) except in
+three places: `date` output, access logs, and a numeric offset glued to the
+clock. That last one is what keeps `15:30-16:45` a range rather than 15:30 at
+an offset of −16:45. With a space, an offset needs no seconds
+(`12:00 +0530`). An offset outside -12..+14 isn't an offset.
+
+A date, time and zone are read together only when they're written together, in
+one of the formats above. A date in another column
+(`2026-12-31 | 23:30:00 | UTC`), a syslog date with no year
+(`Sep 25 22:14:42`), or a word like `tomorrow` isn't attached to the time
+beside it, which converts as a time alone.
+
+### Ranges and lists
+
+A range is joined by `-`, `–`, `—`, `to`, `until`, `till`, `through` or `thru`;
+a list by commas, `or` and `and`. Its members share what's written around them:
+
+- **The zone and AM/PM at the end apply to every member before it.**
+  `from 3:30 to 4:45 PM PST` reads both ends as PST afternoon times, and
+  `3:00, 4:00 or 5:00 PM PST` converts all three. AM/PM flips if it would run
+  the range backwards: `11:30 to 1:00 PM` starts in the morning.
+- **A date at the start applies to every member after it.**
+  `2026-04-03 9:00 AM - 10:00 AM PST` puts both ends on April 3.
+- **Nothing else crosses.** A zone on the start stays there: in
+  `3:30 PST to 4:45 PM`, the end is in your source zone.
+- **A member earlier on the clock than the one before it is on the next day.**
+  The preserved format shows only the clock; `-F iso` shows the dates:
+
+```bash
+echo '11:30 PM to 12:30 AM PST' | tztr -t utc -d 2026-04-03 -F iso
+# 2026-04-04 07:30:00Z to 2026-04-04 08:30:00Z
+```
+
+A bare hour is just a number, except as the start of a range whose end has
+AM/PM: `9-9:15am` and `9 to 10am` convert, but `Room 7 - 3pm` and
+`Apr 3 - 5pm` convert only the `3pm` and `5pm`.
+
+Any other word between two times keeps them apart, as in `15:30, then 16:45 PST`.
+Here the rule below applies, and the `15:30` is left alone.
+
+### What's left alone
+
+- **A bare time beside a richer one.** A time with no date, zone or AM/PM, like
+  the `0:05` in `2026-04-03T12:00:00Z took 0:05`, is probably a duration. It's
+  left alone whenever another timestamp on its line has a date, zone or AM/PM.
+  Alone on its line (`request took 0:05`), it can't be told from a time, and
+  converts as one.
+- **A time followed by a unit of time.** `Finished in 1:05 minutes`,
+  `took 2:30 hrs` (`sec`, `min`, `hr`, `hour`, spelled out or plural). So
+  `at 15:30 hrs` is left alone too.
+- **A zone tztr doesn't know.** `Fri Sep 25 22:14:42 EEST 2026` stays as
+  written, rather than half-converted, unless your source zone uses `EEST`
+  (see below). `-v` names the zone.
+- **Colon runs that aren't times.** IPv6 addresses (`fe80::1:23:45`) and SMPTE
+  timecodes (`01:02:03:04`).
+- **Impossible dates.** `2026-02-30` stays exactly as found rather than rolling
+  to another day.
+
+### Zone abbreviations
+
+- **Standard and daylight names are fixed offsets**, whatever the date: `PST`
+  is -08:00 even in July, `CEST` is +02:00 even in January. Only the generic
+  `ET`, `CT`, `MT` and `PT` follow DST.
+- **Ambiguous names are read the US way** (`CST` is US Central) and `IST` as
+  India, **unless your source zone (`-f`, else `$TZ`) uses the name itself**.
+  Then it means what it means there: with `TZ=Asia/Shanghai`, `CST` is China
+  Standard Time, and with `TZ=Europe/Helsinki`, `date`'s `EEST` converts. With
+  `$TZ` unset, UTC or anywhere in the US, the US reading stands.
+- **Uppercase or lowercase, never mixed.** `PST` and `pst` both work; `Pst`
+  doesn't. Six are uppercase only, because their lowercase spellings are words
+  that can follow a time: `est`, `cet`, `et`, `ist`, `ut` and `z`. In
+  `à 15:30 est annulée`, `est` is French for "is", not Eastern time.
+
+
+## JSON output (for agents and scripts)
+
+`-j/--json` emits a JSON array; `-J/--ndjson` emits one object per line, which
+streams (works with `tail -f`). Each match is an object:
+
+```bash
+echo 'meeting at 15:30 UTC' | tztr -t pst -j
+# [
+#   {
+#     "original": "15:30 UTC",
+#     "detected_format": "time",
+#     "detected_tz": "UTC",
+#     "translated": "08:30 PDT"
+#   }
+# ]
+```
+
+(`08:30 PDT` in summer; `07:30 PST` in winter, as the time has no date.)
+
+A timestamp in a range or list also carries `group`, which lists every member
+in order, so the two ends of a range can be read together (abridged):
+
+```bash
+echo 'standup 9:00 to 9:15 AM PST' | tztr -t utc -j
+# [
+#   { "original": "9:00", "detected_tz": "PST", "translated": "17:00 UTC",
+#     "group": { "type": "range", "members": ["9:00", "9:15 AM PST"] }, ... },
+#   { "original": "9:15 AM PST", "detected_tz": "PST", "translated": "17:15 UTC",
+#     "group": { "type": "range", "members": ["9:00", "9:15 AM PST"] }, ... }
+# ]
+```
+
+`--detect` reports what was found without translating (omits `translated`),
+and composes with `-j`/`-J`:
+
+```bash
+echo '2026-04-03T12:00:00Z' | tztr --detect -j
+# [ { "original": "2026-04-03T12:00:00Z", "detected_format": "iso", "detected_tz": "Z" } ]
+```
+
+Combine `-h` with `-j`/`-J` to get the help itself as JSON: the full option
+schema (flags, args, descriptions, examples), so an agent can read it instead
+of scraping the text.
+
+```bash
+tztr -h -j
+# { "name": "tztr", "version": "...", "options": [ { "short": "-f", "long": "--from", ... } ], ... }
+```
+
+
+## Diagnostics (`-v`)
+
+`-v` explains itself on stderr, leaving stdout untouched. Each note is printed
+once, the first time it applies:
+
+- the source and output zones, when `-f` is given
+- the source zone it borrowed from `$TZ` or the system, when a timestamp needed one
+- the date it assumed for DST, when a timestamp had none and there's no `-d`
+- a zone it passed over for its case (`Pst`), or didn't know (`EEST`)
+
+```bash
+echo '15:30' | tztr -f pacific -t utc -v
+# tztr: from=America/Los_Angeles to=UTC
+# tztr: no -d given, assuming 2026-09-26 for DST resolution   (whatever today is)
+# 22:30 UTC
+```
+
+
+## DST caveats
+
+### Time-only inputs
+
+A time with no date can't say whether it was standard or daylight time.
+`tztr` resolves it against **today's** date where the time was written (in the
+zone it names, else the source zone). That can be off by an hour for a
+timestamp from the other side of a DST boundary:
+
+```bash
+echo '15:30' | tztr -f pacific -t utc
+# 22:30 UTC   (run in summer: pacific -> PDT, UTC-7. In January: 23:30 UTC)
+```
+
+Two ways to remove the guess:
+
+```bash
+# Supply the date the time belongs to:
+echo '15:30' | tztr -f pacific -t utc -d 2026-01-15
+# 23:30 UTC   (January -> PST, UTC-8)
+echo '15:30' | tztr -f pacific -t utc -d 'January 15, 2026'
+
+# Or sidestep DST entirely with a fixed numeric offset instead of a named zone:
+echo '15:30' | tztr -f -8 -t utc
+# 23:30 UTC   (-8 -> Etc/GMT+8, never observes daylight time)
+```
+
+`-d` takes one of `2026-01-15`, `2026/01/15`, `20260115`, `January 15, 2026`,
+`Jan 15 2026` or `15 January 2026`. Month names are full or exactly three
+letters (`Sep`, not `Sept`); the numeric forms need two digits for month and
+day. Anything else, including a date that isn't on the calendar, is
+`tztr: invalid date: ...` and exit 1.
+
+Inputs that carry a date (`2026-04-03 15:30`) or a fixed offset are
+unaffected.
+
+### The repeated hour
+
+A fall-back repeats an hour, so the same wall clock happens twice, dated or
+not. `tztr` takes the **earlier** (daylight) occurrence, matching macOS
+`date(1)`, Temporal, RFC 5545 and ICU:
+
+```bash
+echo '2026-11-01 01:30:00' | tztr -f pacific -t utc
+# 2026-11-01 08:30:00 UTC   (01:30 PDT; the later 01:30 PST would be 09:30)
+```
 
 
 ## Library
 
+From Ruby:
+
 ```ruby
 require "tztr"
 
@@ -64,15 +342,11 @@ Tztr.translate("log 2026-04-03T12:00:00Z event", to: "America/Los_Angeles")
 # => "log 2026-04-03T05:00:00-07:00 event"
 ```
 
+`Tztr.matches` returns the `-j` objects for a line, and `Tztr.resolve_tz`
+raises `Tztr::Error` for a zone it can't resolve. Both `translate` and
+`matches` set `ENV['TZ']` as a side effect; save and restore it if the rest of
+your process cares.
 
-----
-## Contributing
-
-Yes please  :)
-
-1. Fork it
-1. Create your feature branch (`git checkout -b my-feature`)
-1. Ensure the tests pass (`bundle exec rspec`)
-1. Commit your changes (`git commit -am 'awesome new feature'`)
-1. Push your branch (`git push origin my-feature`)
-1. Create a Pull Request
+The Rust crate exposes the same functions; see
+[`rust/tztr`](rust/tztr). The Ruby gem is the reference implementation, and
+[`rust/REPORT.md`](rust/REPORT.md) has the port notes and a perf comparison.