duckling 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e13fe61846d4bc85faed37d388e0845de0bf0a6742d5b73796524987b0c85681
-  data.tar.gz: b8fec101cf3f92a760ef275261cbbebe3411185cb4ea84bd19756bd25b09bef1
+  metadata.gz: '059bb11a0d905a85d7577db06b62d8971c2896bda2433d0bbeb8fd0a2393c9b2'
+  data.tar.gz: 9101b8b87ada67851e4468270d73131be44dca36ea3c1f72a99bc403f5ef46e7
 SHA512:
-  metadata.gz: 93d4e3ce65576eb6ab27ec20b617b7bc4cdcab1a1be8bf61ccacbf33ede40daf5293e9ec10053a893986d424761012d3d5083ace5bf7681750a6cfb1fa40574e
-  data.tar.gz: 722c57d3d75412edc428b2476a6312ff5b6162a28537e50b523da94d41b0289f7c5b86a46072aa1a37ef72f580753ee9057c2452b0310580aba0843f76ff5a98
+  metadata.gz: fe7ad8e2c972e6070f2a2bea717e30f7d66d021b0ad3bf618466acb29b3d8bbc51efec151424f2ce3d8b08f0c0edbf5a2b78b667b7ffc8f2f81ff380f08ecf96
+  data.tar.gz: 83fa337d4259faa6063c4322fac789c9b98e57bd7f2c8c3dc7e7142515179d2db69bb8700755c11c29078904af9bc7c6a99d01c1ffec2e6610dff5b6b4c2460a

data/CHANGELOG.md

@@ -6,6 +6,97 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-08-10
+
+### Fixed
+
+- The packaged gem no longer includes agent- and development-tooling files.
+  0.3.0 and 0.4.0 shipped `.claude/settings.json`, `AGENTS.md`, and
+  `CLAUDE.md`: the gemspec built its file list from `git ls-files` with a
+  reject-list of paths to exclude, so every newly tracked dotfile or tool
+  directory was packaged by default. The gemspec now allow-lists what ships
+  (`lib/`, `ext/`, `docs/` other than `docs/benchmarks/`, and a named set of
+  root files), so anything new stays out of the gem unless it is added
+  deliberately. Regression coverage checks the gemspec's file list in the
+  main suite and the built artifacts in `test/gem/packaged_gem_test.rb`.
+  None of the previously shipped files contained secrets — they are
+  development configuration and documentation, all public in the repository
+  — so the already-published 0.3.0/0.4.0 gems are unaffected in behavior and
+  have been left in place.
+
+## [0.4.0] - 2026-08-10
+
+### Changed
+
+- **On a stock Debian/Ubuntu host, roughly a hundred IANA zone identifiers
+  stop resolving.** `reference_zone: "US/Eastern"` — and every other
+  backward-compatibility name, such as `"US/Pacific"`, `"Europe/Kiev"`, or
+  `"Japan"` — now raises `ArgumentError` there. Those names live in the
+  `tzdata-legacy` system package, which is not installed by default. Two ways
+  to get them back, either of which restores the previous behavior exactly:
+
+  ```ruby
+  gem "tzinfo-data"   # in your Gemfile
+  ```
+  ```bash
+  apt install tzdata-legacy   # on the host
+  ```
+
+  Canonical identifiers (`"America/New_York"`, `"Europe/Kyiv"`) are
+  unaffected. A host with no zoneinfo files at all — a scratch or distroless
+  container — needs the gem for `reference_zone:` to work at all.
+
+  The error message names the tz database that answered, how many identifiers
+  it has, and both remedies, so this is distinguishable from a typo. The
+  datasource and the count describe whichever database answered on your host,
+  so both differ from the example below:
+
+  ```
+  invalid reference_zone: "US/Eastern" (resolved against system zoneinfo at
+  /usr/share/zoneinfo, which provides 497 identifiers; this database has no
+  backward-compat names (US/Eastern and ~100 others), so if that is what this
+  is, it needs either the tzinfo-data gem or the tzdata-legacy system package)
+  ```
+
+  The remedy is worded as a condition rather than a claim about the name you
+  passed: whether a given identifier is one of the ~100 in IANA's `backward`
+  file isn't knowable without shipping that list, and asserting it would tell
+  every typo on such a host that `tzdata-legacy` will supply it.
+
+  A second, quieter difference comes with the same change: some distributions
+  compile tzdata in *rearguard* format, which strips negative DST, and on such
+  a host `Europe/Dublin` is modelled as an ordinary positive-DST zone rather
+  than a negative-DST one. Which distributions is not guessable — Ubuntu 24.04
+  is rearguard, Debian trixie is vanguard — so if you depend on tzinfo's
+  `dst?` flag, read it from the host rather than assuming. Resolved offsets
+  are the same either way, so no `Duckling.parse` result changes because of
+  it.
+
+- `tzinfo-data` is no longer a runtime dependency. `tzinfo` already prefers
+  that gem when it is installed and falls back to the host's zoneinfo files
+  otherwise, so depending on it forced bundled tz data on every consumer to
+  serve the ones who want it. This is the change that produces the identifier
+  behavior above. Consumers who add `gem "tzinfo-data"` themselves get exactly
+  the previous behavior with no code change, and can still pick up a
+  tz-database revision by bumping that one gem. Dropping it means the bundled
+  tz data is no longer loaded at boot, so the first zone lookup does less
+  work; steady-state parsing is unaffected either way, since `reference_zone:`
+  resolution goes through the same tzinfo call once a database is loaded.
+
+### Added
+
+- `Duckling::TZDataUnavailable`, raised when `reference_zone:` is given on a
+  host with no tz database at all — no zoneinfo files and no `tzinfo-data`
+  gem, as in a scratch or distroless container. Newly reachable because of the
+  dependency change above; previously a database always existed. It names both
+  fixes, where the underlying tzinfo error mentioned neither this gem nor
+  `reference_zone:`. Deliberately not an `ArgumentError`: it reports the
+  deployment's state, not a bad argument, so code rescuing `ArgumentError`
+  around caller-supplied zone names does not swallow it. Every other keyword
+  works without a tz database.
+
+## [0.3.0] - 2026-08-04
+
 ### Changed
 
 - **Breaking:** `reference_time:` now requires a Ruby `Time` object (or

data/README.md

@@ -33,7 +33,7 @@ Duckling.parse("tomorrow", locale: "en")
 `Array` of entity `Hash`es (empty if nothing matched):
 
 ```ruby
-Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false)
+Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_latent: false, reference_zone: nil)
 ```
 
 ### Keyword arguments
@@ -55,9 +55,49 @@ Duckling.parse(text, locale: "en", dims: ["time"], reference_time: nil, with_lat
   raises `TypeError`; wrap it in `Time.at(seconds)` first.
 - `with_latent:` (Boolean, default `false`) — include ambiguous/latent
   matches (e.g. a bare "morning") in the results.
+- `reference_zone:` (String, default `nil`) — an IANA zone name, e.g.
+  `"America/New_York"`. Resolves each wall-clock result's UTC offset against
+  that zone on the result's *own* date, so a result before a DST transition
+  and one after it get different offsets instead of sharing
+  `reference_time:`'s single fixed one. An unknown identifier raises
+  `ArgumentError`; so does a `reference_time:` whose `utc_offset` disagrees
+  with the zone at that instant. It does not anchor the parse — see "Time
+  zone data" below.
 
 There is no `Duckling::Error` class — invalid `locale:`/`dims:` values raise
-plain `ArgumentError`.
+plain `ArgumentError`, as do an unknown `reference_zone:` and a
+`reference_time:` whose offset disagrees with it. The one named error a caller
+is likely to meet is `Duckling::TZDataUnavailable`, for a host with no tz
+database at all — see "Time zone data" below.
+
+### Time zone data
+
+`reference_zone:` resolves against [tzinfo][], which uses the `tzinfo-data`
+gem when it is installed and the host's own zoneinfo files otherwise. This gem
+does not depend on `tzinfo-data`, so by default you get the host's database.
+
+That is usually what you want, and it is the faster of the two to start up.
+Two cases where it is not:
+
+- **Backward-compatibility names.** Debian and Ubuntu ship names like
+  `"US/Eastern"` in a separate `tzdata-legacy` package that is not installed
+  by default, so roughly a hundred valid IANA identifiers raise
+  `ArgumentError` on a stock host. Either `gem "tzinfo-data"` or
+  `apt install tzdata-legacy` restores them. The error message names whichever
+  database answered and how many identifiers it has, so you can tell this
+  apart from a typo.
+- **No zoneinfo files at all**, as in a scratch or distroless container.
+  `reference_zone:` raises `Duckling::TZDataUnavailable` there, naming both
+  fixes. Add `gem "tzinfo-data"` to bundle the data with your app, where you
+  can also patch its vintage by bumping one gem, or install the system
+  `tzdata` package. Every other keyword works without a tz database.
+
+`reference_zone:` reinterprets result offsets; it does not anchor the parse.
+Given without `reference_time:`, a relative expression like `"tomorrow"` still
+anchors on the machine-local clock rather than on "now" in that zone — pass a
+`reference_time:` in the zone to anchor as well.
+
+[tzinfo]: https://github.com/tzinfo/tzinfo
 
 ### Return value
 

data/Rakefile

@@ -60,7 +60,7 @@ end
 # extconf.rb runs in its own subprocess. ENV changes made there do not
 # reach the parent process, and the parent process runs `make`.
 #
-# So this fix changes ENV here, in the Rakefile, not in extconf.rb.
+# So this fix changes ENV here, in the Rakefile.
 # The fix adds a prerequisite task to the local build's Makefile task.
 # This prerequisite task sets the correct host target. It runs before
 # the Makefile task, and before `make` runs later.
@@ -71,7 +71,7 @@ if (ruby_target = ENV["RUBY_TARGET"]) && ruby_target != RUBY_PLATFORM
   # away. Clearing RUST_TARGET alone lets rb_sys fall back to the target
   # baked into the container's $CARGO_HOME/config.toml, which is the
   # cross-compile target again. So a host triple that cannot be read is a
-  # hard error, not something to skip past.
+  # hard error.
   #
   # Both variables belong to the whole rake process, and the cross build
   # reads them too. This is safe only because rake generates the cross
@@ -121,8 +121,8 @@ end
 #
 # So build from a throwaway plain clone instead, whose .git is a real
 # directory under the mount. Two consequences: the gem carries *committed*
-# state, not the working tree, and the clone gets its own Cargo target
-# directory rather than reusing this checkout's.
+# state (uncommitted changes are excluded), and the clone gets its own Cargo
+# target directory separate from this checkout's.
 CLONE_DIR = "tmp/native_gem_clone"
 
 def build_native_gem(platform)
@@ -163,10 +163,10 @@ end
 
 task :benchmark_env do
   # Force a realistic release-profile build regardless of .env.local's
-  # RB_SYS_CARGO_PROFILE=dev (local dev checkouts only, never present in
-  # CI). Must reenable :compile in case it already ran earlier in this same
-  # rake process, so it's guaranteed to recompile under the forced profile
-  # rather than reusing a stale dev-profile build.
+  # RB_SYS_CARGO_PROFILE=dev (local dev checkouts only; CI never has it).
+  # Must reenable :compile in case it already ran earlier in this same
+  # rake process, so it recompiles under the forced profile. A stale
+  # dev-profile build would be reused otherwise.
   ENV.delete("RB_SYS_CARGO_PROFILE")
   Rake::Task[:compile].reenable
 end
@@ -184,8 +184,8 @@ namespace :benchmark do
 
   desc "Run :record on a fresh branch off origin/main, then commit/push and open+auto-merge a PR via gh"
   task record_pr: ["release:guard_clean"] do
-    # Explicit bash, not Rake's default `sh -c` (dash on Debian/Ubuntu
-    # runners): dash's `set` doesn't support the `-o pipefail` flag below.
+    # Explicit bash: Rake's default `sh -c` is dash on Debian/Ubuntu
+    # runners, and dash's `set` doesn't support the `-o pipefail` flag below.
     sh("bash", "-c", <<~SH)
       set -euo pipefail
       original_ref="$(git symbolic-ref -q --short HEAD || git rev-parse HEAD)"
@@ -214,12 +214,14 @@ namespace :benchmark do
 end
 
 # The default suite exercises the extension compiled in this checkout.
-# test/gem/ exercises a *built* or *installed* gem instead — it needs one
-# handed to it, and the installed suite must not see this checkout's lib/ at
-# all — so both run on their own, as plain `ruby test/gem/<file>`. See each
-# file's header.
+# Three test subtrees run outside it:
+# - test/gem/ exercises a *built* or *installed* gem instead — it needs one
+#   handed to it, and the installed suite must not see this checkout's lib/.
+# - test/capabilities/ is loaded by test_helper itself, gated on the tz probes.
+# - test/environments/ holds contracts invoked directly by their CI step.
+# See docs/tz-database-axis.md.
 Minitest::TestTask.create do |t|
-  t.test_globs = FileList["test/**/*_test.rb"].exclude("test/gem/**/*")
+  t.test_globs = FileList["test/**/*_test.rb"].exclude("test/gem/**/*", "test/capabilities/**/*", "test/environments/**/*")
 end
 
 # Minitest::TestTask has no built-in way to declare a task dependency, and
@@ -227,7 +229,7 @@ end
 # `bundle exec rake` itself — `bundle exec rake test` run directly has no
 # guarantee `compile` ran first, which would surface as a confusing
 # LoadError/stale-behavior failure unrelated to the code under test.
-task test: :compile
+task test: %i[compile]
 
 require "standard/rake"