Close 1.0 readiness gaps: download path test, MF2 gap docs, Format.Options public, locale-id path guard

Author: kipcole9

.github/workflows/upload-locales.yml

@@ -8,6 +8,10 @@ on:
 
 env:
   MIX_ENV: dev
+  # Toolchain pins — also part of the dependency cache key, since
+  # cached BEAMs are only valid for the OTP/Elixir that built them.
+  ELIXIR_VERSION: "1.19"
+  OTP_VERSION: "28"
   R2_BUCKET: content
   # Prefix within the bucket where locale ETF files are stored.
   R2_PREFIX: locales
@@ -97,8 +101,8 @@ jobs:
         if: steps.check_existing.outputs.skip != 'true'
         uses: erlef/setup-beam@v1
         with:
-          elixir-version: "1.19"
-          otp-version: "28"
+          elixir-version: ${{ env.ELIXIR_VERSION }}
+          otp-version: ${{ env.OTP_VERSION }}
 
       - name: Restore dependency cache
         if: steps.check_existing.outputs.skip != 'true'
@@ -107,9 +111,9 @@ jobs:
           path: |
             deps
             _build
-          key: mix-locales-${{ hashFiles('mix.lock') }}
+          key: mix-locales-otp${{ env.OTP_VERSION }}-elixir${{ env.ELIXIR_VERSION }}-${{ hashFiles('mix.lock') }}
           restore-keys: |
-            mix-locales-
+            mix-locales-otp${{ env.OTP_VERSION }}-elixir${{ env.ELIXIR_VERSION }}-
 
       - name: Install dependencies
         if: steps.check_existing.outputs.skip != 'true'

CHANGELOG.md

@@ -6,10 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Added
+
+* The locale download base URL can be overridden with `config :localize, locale_base_url: "..."` for deployments mirroring the locale files; downloads are verified against the bundled hash manifest regardless of source.
+
+### Changed
+
+* `Localize.Number.Format.Options` is documented again: `validate_options/2` is the supported way to pre-resolve formatting options for hot loops (as the Performance guide describes), so the module is part of the public API.
+
+* The TR35 conformance guide documents the MessageFormat 2 working-group suite exclusions precisely: unknown-function fallback, duplicate declaration/option validation, select and digit-size option validation, `u:dir`/`u:id` expression options, and the `:isolate` bidi strategy deviation.
+
 ### Fixed
 
 * Calendar- and provider-module probes in date/datetime formatting (era year, day of era, ISO week and day of year, day of week, CLDR calendar type) and `Localize.Locale.Provider.allow_download?/1` ensure the module is loaded before `function_exported?/3`, so a cold module no longer silently takes the gregorian or default fallback branch.
 
+### Security
+
+* `Localize.Locale.Provider.locale_file_name/1` rejects locale identifiers that do not have the shape of a CLDR locale id, as defense in depth for the cache-path and download-URL interpolations.
+
 ## [0.49.0] — July 12th, 2026
 
 ### Fixed

guides/conformance.md

@@ -481,15 +481,27 @@ Two areas are explicitly out of scope:
 | Feature | Status | Notes |
 |---------|--------|-------|
 | Syntax errors | Implemented | Parser returns `{:error, reason}`. |
-| Resolution errors (unknown function, unresolved variable) | Partial | Unknown functions fall back to string conversion rather than error. |
-| Data model errors | Partial | Duplicate declarations and options not explicitly validated. |
+| Resolution errors (unknown function, unresolved variable) | Partial | Unresolved variables error per spec; unknown functions fall back to formatting the operand rather than producing an unknown-function error. |
+| Data model errors | Partial | Duplicate declarations and duplicate option names are not validated. A declaration option referencing a not-yet-declared variable errors per spec. |
 
 ### MF2 Data Model
 
 | Feature | Status | Notes |
 |---------|--------|-------|
 | JSON interchange format | Implemented | `Localize.Message.JSON.to_json/2` and `from_json/1` for round-trip serialization to the TR35 §8 data model. |
-| Bidirectional text handling | Implemented | `:bidi` option (`:none`, `:isolate`, `:auto`) wraps placeholder output in Unicode isolate characters (FSI/PDI). Supports `u:dir` attribute for per-expression overrides. |
+| Bidirectional text handling | Partial | `:bidi` option (`:none`, `:isolate`, `:auto`) wraps placeholder output in Unicode isolate characters (FSI/PDI), and the `@u:dir` expression *attribute* overrides direction per expression. The `u:dir` / `u:id` expression *options* are not implemented, and the `:isolate` strategy isolates every placeholder where the WG default strategy leaves known-LTR placeholders unisolated. |
+
+### MF2 known conformance gaps
+
+The MessageFormat working group conformance suite runs against both the parser and the formatter (`test/localize/message/formatter_conformance_test.exs`); the cases the implementation cannot yet satisfy are excluded there, each with a documented reason. Beyond the Partial rows above, the excluded cases are:
+
+* Unknown functions fall back to formatting the operand instead of producing an unknown-function error, and the WG `:test:select` / `:test:format` registry functions used by some suite cases are not implemented.
+
+* Declarations bind the formatted string, so re-annotating an already-annotated variable in a later declaration fails.
+
+* Select option validation (literal-only restrictions and operand restrictions on `:integer` / `:number` selection) is not implemented, number-literal operand validation (leading zero or plus sign) is not enforced, and invalid digit size option values are ignored instead of producing a bad-option error.
+
+* `:currency` is not rejected as a selector (no bad-selector error), the `:offset` function's `signDisplay` option is not implemented, and variant keys are not NFC-normalized so duplicate variants differing only in normalization are not detected.
 
 ---
 

lib/localize/collation.ex

@@ -71,6 +71,10 @@ defmodule Localize.Collation do
 
   * `backend` - `:nif` or `:elixir`. The default is `:elixir`.
 
+  ## Return value convention
+
+  Unlike the rest of Localize, the functions in this module return bare values rather than `{:ok, result}` tuples: `compare/3` returns `:lt`, `:eq` or `:gt` (the shape `Enum.sort/2` and friends expect for a comparator), `sort/2` returns the sorted list, and `sort_key/2` returns a binary. This deviation is deliberate — collation functions are designed to be passed directly to `Enum` and used in hot paths, where a wrapping tuple would defeat their purpose. Consistent with that design, unrecognised option values fall back to their defaults rather than producing an error.
+
   """
 
   alias Localize.Collation.{

lib/localize/locale/provider.ex

@@ -37,6 +37,8 @@ defmodule Localize.Locale.Provider do
   @locale_hashes_key {:localize, :locale_hashes}
   @locale_hashes_warned_key {:localize, :locale_hashes_warned}
 
+  @default_locale_base_url "https://elixir-localize.com/locales"
+
   # ── Behaviour callbacks ────────────────────────────────────────
 
   @doc """
@@ -543,6 +545,10 @@ defmodule Localize.Locale.Provider do
   @doc """
   Returns the base URL from which locale data files are downloaded.
 
+  The default is the Localize CDN. It can be overridden with the `:locale_base_url` application configuration key, for deployments that mirror the locale files on their own infrastructure (downloads are still verified against the bundled SHA-256 hash manifest regardless of the source):
+
+      config :localize, locale_base_url: "https://mirror.example.com/locales"
+
   ### Returns
 
   * A string URL.
@@ -555,7 +561,7 @@ defmodule Localize.Locale.Provider do
   """
   @spec base_url() :: String.t()
   def base_url do
-    "https://elixir-localize.com/locales"
+    Application.get_env(:localize, :locale_base_url, @default_locale_base_url)
   end
 
   @doc """
@@ -569,6 +575,8 @@ defmodule Localize.Locale.Provider do
 
   * A string file name of the form `"{locale_id}.etf"`.
 
+  Raises `ArgumentError` if the locale identifier does not have the shape of a CLDR locale id (letters, digits, `-` and `_` only). Locale ids reaching this function have already been validated, so this is a defense-in-depth guard: the file name is interpolated into cache paths and download URLs, and a tampered identifier must not be able to traverse outside them.
+
   ### Examples
 
       iex> Localize.Locale.Provider.locale_file_name(:en)
@@ -577,7 +585,14 @@ defmodule Localize.Locale.Provider do
   """
   @spec locale_file_name(locale_id()) :: String.t()
   def locale_file_name(locale_id) when is_atom(locale_id) do
-    "#{locale_id}.etf"
+    name = Atom.to_string(locale_id)
+
+    if String.match?(name, ~r/^[A-Za-z0-9_-]+$/) do
+      name <> ".etf"
+    else
+      raise ArgumentError,
+            "locale identifier #{inspect(locale_id)} is not a valid locale file name component"
+    end
   end
 
   @doc """

lib/localize/number/format/options.ex

@@ -1,10 +1,10 @@
 defmodule Localize.Number.Format.Options do
-  @moduledoc false
+  @moduledoc """
+  Validation and resolution of number formatting options.
 
-  # Options validation and transformation for number formatting.
-  # This is an internal module that validates user-supplied
-  # options and produces a normalized options struct for the
-  # formatter pipeline.
+  `validate_options/2` resolves a keyword list of the options accepted by `Localize.Number.to_string/2` into a `t:Localize.Number.Format.Options.t/0` struct — locale validation, number system resolution, format pattern lookup, currency data loading and symbol resolution all happen once. Passing the resulting struct to `Localize.Number.to_string/2` bypasses that resolution on every call, which is significantly faster when formatting many numbers with the same locale and format. See the [Performance and optimization](number_formatting.html#performance-and-optimization) section of the Number Formatting guide for benchmarks.
+
+  """
 
   alias Localize.Number.{Format, Symbol, System}
 

plans/RELEASE_1.0_READINESS_2026-07-15.md

@@ -0,0 +1,94 @@
+# Localize 1.0 Readiness — Fresh Assessment
+
+Date: July 15, 2026. Baseline: v0.49.0 + unreleased (commit 8c4235d7), Elixir 1.20.1-otp-29 / Erlang 29.0.1. Method: full quality-gate run, `mix hex.build` package inspection, and four verification passes (API freeze, API hygiene/security, documentation, test wiring) re-checking every item in the July 4 plan (`RELEASE_1.0_READINESS.md`) against current source.
+
+## Executive summary
+
+The July 4 plan is almost entirely executed. Milestones 1–3 are done and verified: all six TR35 nonconformances (C1–C6) fixed, all consumer-breaking packaging bugs (B1/B2) fixed and verified in the built hex tarball, security items S1–S6 resolved, the API-freeze renames (B3/B4) shipped in 0.43.0 with deprecated delegates, and the hiding pass (B5) applied. All five quality gates pass clean and coverage is 91.23% (gated at Mix's default 90% threshold on the CI lint row). What remains before an RC is one API decision, four visibility-deviation confirmations, one genuine test gap (the download happy path), a handful of doc nits, and the `localize_mcp` release plumbing.
+
+## Quality gates (July 15, Elixir 1.20.1-otp-29)
+
+| Gate | Result |
+|---|---|
+| `mix format --check-formatted` | ✅ clean |
+| `mix compile --warnings-as-errors` | ✅ clean |
+| `mix test --cover` | ✅ 29,069 passed (945 doctests, 17 properties), 0 failures, 2 excluded; coverage 91.23% |
+| `mix dialyzer` | ✅ Total errors: 0 |
+| `MIX_ENV=release mix docs` | ✅ no localize-owned doc warnings (deps emit their own; see nits) |
+
+`mix hex.build`: 264 files; `c_src/Makefile`, `c_src/env.mk`, `c_src/localize_nif.cpp` present (B1 verified at the artifact level), no stray `.o` files, `priv/localize/locale_hashes.etf` integrity manifest bundled (S1 verified), Elixir floor `~> 1.17` retained.
+
+## Verified done since the July 4 baseline
+
+* **C1–C6 conformance fixes** — shipped across 0.42.0–0.44.0 (compact plurals + operands, BCE era years, significant digits, day periods, locale week configuration, Annex C alias disambiguation).
+
+* **B1 NIF packaging** — fixed and verified in the tarball. **B2 json_polyfill** — resolved by policy: `only: [:dev, :test]` stays until the announced OTP 26 drop on December 31, 2026.
+
+* **B3 option unification** — `Unit.to_string` and `Duration.to_string` both take `:format`; `:style` is a documented deprecated alias on Duration ("removed by Localize 1.0"). `Unit.display_name` and `Localize.quote/2` settled on the naming-vs-formatting split (0.43.0).
+
+* **B4 known_/available_ semantics** — implemented in 0.43.0: `known_*` = locale-independent universe, `supported_*` = configuration, `*_for` = localized inventories. Deprecated delegates in place for every renamed function (removal window "no later than December 2026"). `Territory.known_styles/0` and public `Territory.known_territories/0` exist.
+
+* **B5 hiding pass** — all `Localize.Utils.*`, `DataLoader`, `Substitution`, `FormatCache`, `Locale.Loader`, `LanguageTag.Parser`, `Message.Interpreter`, `LocaleDefaults`, `SupplementalData`, `Validity` are `@moduledoc false`; the keep-public list is public; `guides/conformance.md` no longer references hidden modules; the ex_doc group map covers everything except the bare `Localize` module (conventional).
+
+* **Error-shape policy** — Language/Script `display_name` return `{:error, %InvalidValueError{}}` on bad options; `Localize.quote/2` errors on unknown format; all 5 missing bang variants exist; `Localize.validate_currency/1` delegate exists (all 0.43.0).
+
+* **Security** — S1 hash manifest (0.44.0, fail-closed with `LocaleIntegrityError`); S2 corrupt cache decode → miss/stale at both sites; S3 atomic write-temp-then-rename; S4 `autoredirect: false`; S5 `existing_atom` for `:usage`; S6 resolved via Utils modules going internal. NIF-backend locale validation closed (0.43.0).
+
+* **Docs** — all four planned guides exist (plural_rules, list_formatting, locale_validation, display_names); README feature list complete, install snippet hex-correct, all guide links hexdocs; CHANGELOG fully Keep-a-Changelog; `to_range_string/3` and `!/3` documented; doctests wired for 5 of the 6 flagged modules; conformance.md day-period rows accurate; collation known-failures comment refreshed to zero-threshold reality; `usage-rules.md` spot-checked accurate.
+
+* **Test wiring** — RBNF reference data exercised for en/de/es/fr; MF2 working-group suite runs against the formatter (with documented exclusion groups); likely-subtags FAIL rows asserted with zero skips; every exception module's `message/1` exercised, multi-reason exceptions enumerated per reason atom (gettext msgid-drift guard); coverage ignore-list guarded against orphaned entries; OTP 26 CI rows present pending the December drop.
+
+* **Credo strict** — zero findings, enforced in CI (0.45.0).
+
+## Remaining before RC
+
+### A. API decisions (freeze at 1.0)
+
+1. **`Currency.currencies_for_locale/3` and `!/3` still take positional `only \\ :all, except \\ nil` filter args** (`lib/localize/currency.ex:639`, `:989`). The plan called for an options keyword list. This is the last remaining breaking-shaped API decision; decide (convert with deprecated positional heads, or explicitly accept the positional form) before RC.
+
+2. **Four deviations from the frozen B5 visibility list** — RESOLVED July 15. Three confirmed correct: `List.Pattern` public (its struct is documented API in `Localize.List`), `Number.Format.Meta` public (its type appears in the public `Format.Compiler` specs), `Utils.Code` hidden (nothing public references it). One was wrong: `Number.Format.Options` was hidden while `validate_options/2` is a documented performance idiom in the Performance guide, the number cheatsheet and usage-rules.md — its moduledoc is restored and its doctest wired.
+
+3. **Deprecated-delegate removal timing** — Duration `:style` says "removed by Localize 1.0"; the B4 delegates say "no later than December 2026". If 1.0 ships before December, decide whether 1.0 removes all of them in one breaking sweep (cleanest) or carries them to a 1.1.
+
+### B. Test gaps
+
+4. **`Provider.download_locale/1` happy path has no end-to-end test.** — DONE July 15: `test/localize/locale/download_test.exs` drives HTTP 200 → integrity verify → cache write → read-back against a local `:httpd` server, plus 404, tampered-content and missing-manifest-entry failure paths. Required a `:locale_base_url` config seam in `Provider.base_url/0` (also useful for self-hosted mirrors).
+
+5. **MF2 formatter conformance exclusion groups** — DOCUMENTED July 15: `guides/conformance.md` Part 9 now lists every exclusion group precisely (Error Handling and Data Model rows corrected, new "MF2 known conformance gaps" section; bidi row downgraded to Partial since `u:dir`/`u:id` expression *options* are unimplemented — only the `@u:dir` attribute form works). Closing the gaps themselves remains an explicit 1.0 scope decision.
+
+6. **Favor-region column parsed but never asserted** in `likely_subtags_test.exs` (`_remove_region` in every comprehension); the feature is unimplemented. Either implement + assert, or drop the parse and note it as out of scope.
+
+### C. Documentation nits
+
+7. **`Message.JSON.from_json/1` docstring example is wrong** — DONE July 15. The example had in fact already been corrected; only the doctest was still unwired and the test comment stale. `doctest Localize.Message.JSON` is now enabled and passing.
+
+8. **Collation's bare-return deviation** — DONE July 15: the `Localize.Collation` moduledoc now has a "Return value convention" section explaining the bare returns and that unrecognised option values fall back to defaults (verified: they do not raise).
+
+9. **README has no MCP section.** The skill is documented; `localize_mcp` (complete, 52 tests passing, 11 tools) is unpublished and unmentioned. Once it's on hex, add a section beside the skill one.
+
+### D. Mechanical nits
+
+10. ~~`mix.exs` deprecated `xref: [exclude: ...]` shape~~ — WITHDRAWN July 15: the warning in the gates log came from compiling the `earmark_parser` dep in the docs stage; localize's own mix.exs has no `xref` key and a fresh release-env compile is clean.
+
+11. Two always-true type warnings in `test/localize/unit/data_test.exs` — DONE July 15 (`refute Enum.empty?(...)`).
+
+12. `.github/workflows/upload-locales.yml` cache key — DONE July 15: OTP/Elixir pins moved to workflow `env` and included in the cache key and restore-keys.
+
+13. S7 locale-id shape validation — DONE July 15: `Provider.locale_file_name/1` (the single choke point for both cache paths and download URLs) raises `ArgumentError` unless the id matches `^[A-Za-z0-9_-]+$`, with tests for traversal-shaped atoms.
+
+## Companion deliverables
+
+* **Claude Code skill** — shipped in 0.47.0, committed, README-documented, marketplace manifest in place. Done.
+
+* **`localize_mcp`** — implemented (11 tools, 52 tests passing on 1.20.1-otp-29, version 0.1.0) but a single local "Initial commit": no GitHub remote, not published to hex. Remaining: create repo + push, release review per house checklist, publish, cross-link from README (item 9).
+
+## Suggested order
+
+Updated July 15: items 2, 4, 5 (documentation half), 7, 8, and 10–13 are done as annotated above. Remaining:
+
+1. Item 1 (Currency positional args) and item 3 (delegate removal timing) — the two decisions that freeze.
+2. Scope decisions: close or accept the MF2 conformance gaps now documented in the guide (item 5), and implement-or-drop favor-region (item 6).
+3. Item 9 — `localize_mcp` release (repo, review, hex publish); README MCP section.
+4. Full house release review; 1.0.0-rc.1; soak; 1.0.0.
+
+Nothing found in this pass contradicts the stability-period intent: items 1–3 are decisions plus small diffs, and everything else is additive tests/docs.