briefly 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06a4a7f10ae74a9abd66fd882812d0af1a469d09916da7f898375b659bbdbdf
-  data.tar.gz: a72ed9ae644fa4bca67fa2f671486945ddd90872a78171864fa896b33d778443
+  metadata.gz: f6c561612c29ff83aaaccdf483e6e563633e54d3dc81c92856857db2f26978b3
+  data.tar.gz: a257e3be54bb8e1bb076009dc5982a7c15a6add60f16225bb774e9e3100f3db4
 SHA512:
-  metadata.gz: 72e7861ca614204a8536bdd8b0c40c48c480981c9cd494dc5d4de6b14bdbca1e016c0c658e728843b29afcf5b878020ae7e511869ad5ec666d825938afdfc885
-  data.tar.gz: ed27d0120874e0ff825a0ac0859b71c75947bccbe5c9dadf70b20de8d7f7eb46b3212e1f23b52e924e2a8b46b4c31b8950944875fcc94b341039e21b80c816c4
+  metadata.gz: 4496b43e5d42fb6b90d0b8f528092207ff867dfbab5febe1d36b69451c307527bd1a056da118a20a48770b77601c49c8965018fa76c904fc203642a4bd5dc178
+  data.tar.gz: 430188265df3b33c124f90cbf28de0b34f27fa3090174e74d60a94a63d32a97a4bb905bfb46a72e50263977a44c89cecd29a66799f25847e520ee268071ea18e

data/CHANGELOG.md

@@ -6,38 +6,123 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## Unreleased
 
+## v0.2.1 (2026-07-31)
+
+No change to `lib/` or `sig/`: this release carries the documentation the gem ships and the process
+that publishes it. `Briefly::VERSION` is the only Ruby file that differs from v0.2.0.
+
+### Added
+- The README declares the public API that Semantic Versioning covers, and what falls outside it, so
+  a MINOR bump before `1.0.0` now has a stated scope rather than an implied one.
+- CONTRIBUTING.md states the deprecation policy: a public item ships deprecated in one release, with
+  a runtime warning naming its replacement and the earliest removal version, before a later release
+  removes it. v0.2.0's three removals predate the policy and are named there.
+
+### Changed
+- Development now resolves through committed lockfiles. `gemfiles/` holds one file per Rails line,
+  each pinning that line and evaluating the root `Gemfile`, and 7.2, 8.0 and 8.1 commit a lockfile
+  beside theirs; CI installs from them frozen instead of deleting `Gemfile.lock` and re-resolving.
+  Contributors testing another Rails version now pass `BUNDLE_GEMFILE` rather than `RAILS_VERSION`.
+  Nothing an application installs changed.
+- Releases are published by CI from a pushed tag, authenticating to RubyGems through OIDC, gated on
+  a manual approval, and signed with sigstore. No publishing credential exists on any machine.
+  `bundle exec rake release` no longer publishes; it prints the tag steps and exits.
+
+## v0.2.0 (2026-07-14)
+
+### Added
+- `rails g briefly:install`, a Rails generator that writes `config/initializers/briefly.rb`: a
+  working `App` facade plus a commented, concern-grouped map of every shortcut `use "rails"` installs.
+  Pass a name (`rails g briefly:install Facade`) to rename the constant; re-run it after upgrading to
+  refresh the map, as Rails prompts before overwriting. It loads only under `rails generate`, so no
+  Rails runtime dependency is added.
+- `Briefly::Rails::Config` gains `error` (`Rails.error`, the framework's handled-error reporter) and
+  `config_for` (per-environment YAML via `Rails.application.config_for`). Both are live lookups;
+  `config_for` takes an argument, so it never memoizes. Compose one that does by chaining `.memoize`
+  onto a shortcut: `shortcut(:x) { config_for(:x) }.memoize`.
+- `Briefly::Rails::DB` gains `connected_to`, `reading` and `writing` for multi-database routing.
+  `connected_to` forwards the full Rails surface (`role:`, `shard:`, `prevent_writes:`, custom roles);
+  `reading`/`writing` are sugar that pin their role and forward the rest. `base` must be
+  `ActiveRecord::Base` or an abstract connection class; a concrete model raises `NotImplementedError`.
+- `Briefly::Rails::DB` gains `select`, a raw-SQL read through `select_all`, returning an
+  `ActiveRecord::Result` on the query-cache-preserving path, with the same positional and named
+  bind-safety as `query`. `query` keeps running arbitrary SQL (writes and DDL included) via `exec_query`.
+- `Briefly::Rails::Env` gains `dev?` and `prod?`, aliases of `development?` and `production?`.
+- `Briefly::Rails::Instrument`, a new `"rails/instrument"` pack with one `instrument` shortcut over
+  `ActiveSupport::Notifications.instrument(name, payload) { }`. Usable on its own; `use "rails"`
+  includes it, so `App.instrument` comes for free.
+
+### Changed
+- **BREAKING:** Facade management moved behind a single `App.briefly` accessor:
+  `App.briefly.configure`, `App.briefly.shortcuts`, `App.briefly.shortcut?` and
+  `App.briefly.clear_memos!`. This frees `configure`, `shortcuts`, `shortcut?` and `clear_memos!` for
+  use as your own shortcut names; only `briefly`, `inspect` and `to_s` stay reserved on the facade's
+  public surface.
+- **BREAKING:** `Briefly::Rails::DB#connection`/`#conn` is now an auto-releasing block that forwards to
+  `base.with_connection`, yielding the leased connection and releasing it at block exit, the shape of
+  `transaction`. It requires a block; the old bare `base.lease_connection` accessor (held on the thread
+  and never released, a leak outside a request) is gone, with no compatibility shim. Anyone needing a
+  held raw lease calls `lease_connection` on their model directly.
+- The DB pack's tests now run against real Active Record on in-memory SQLite, so its Active Record
+  calls are verified rather than mocked. `activerecord` and `sqlite3` join `activesupport` as dev-only
+  dependencies; the gem still declares no Rails runtime dependency.
+- **BREAKING:** `shortcut` now returns the `Briefly::Shortcut` it declares instead of the canonical
+  name Symbol. Refine it in place (`shortcut(:x) { ... }.memoize`, `.rescue_from(Error) { fallback }`,
+  in any order) so a shortcut's name is never written twice to annotate it. A bodiless `shortcut(:x)`
+  fetches an already-declared shortcut (canonical or alias) to refine, raising
+  `Briefly::UnknownShortcutError` on an unknown name; it never re-declares. A shortcut's memoization
+  and its own error handlers live on the shortcut itself, so refining it after a redeclaration affects
+  the declaration you named, exactly as its body does.
+- **BREAKING:** The top-level `rescue_from(error_class)` verb is now facade-wide only and takes no
+  shortcut names; passing any raises `ArgumentError` pointing at `shortcut(name).rescue_from(...)`.
+  Scope a handler to a shortcut by chaining `.rescue_from` onto it. Global `Briefly.rescue_from` is
+  unchanged.
+- **BREAKING:** the rescue-handler registry is now `Briefly::Rescues` (was
+  `Briefly::ErrorRegistry`), reached through `Briefly.rescues` (was `Briefly.errors`), because it holds
+  `rescue_from` handlers, not errors. `Briefly.rescues.clear` still resets globally registered
+  handlers; the internal `#wide` enumerator is gone, replaced by `#size` for counting registrations.
+
+### Removed
+- **BREAKING:** `App.reset!`. Use `App.briefly.clear_memos!`. It was a pure alias for `clear_memos!`
+  with no internal callers.
+- **BREAKING:** The top-level `memoize` DSL verb. Chain `.memoize` onto the shortcut `shortcut`
+  returns (`shortcut(:x) { ... }.memoize`), or `shortcut(:x).memoize` for one declared elsewhere.
+- **BREAKING:** Scoping `rescue_from` by shortcut name on the top-level verb, both single-name
+  `rescue_from(Error, :x)` and multi-name `rescue_from(Error, :a, :b)`. Scope on the shortcut instead:
+  `shortcut(:x).rescue_from(Error) { ... }`, chaining onto each of several.
+
 ## v0.1.0 (2026-07-10)
 
 ### Added
-- `Briefly.define` builds a facade of real, introspectable, stubbable methods — no `method_missing`.
+- `Briefly.define` builds a facade of real, introspectable, stubbable methods, with no `method_missing`.
 - `shortcut(canonical, *aliases, &body)` with argument, keyword and block forwarding; predicate and
   bang names; last-declaration-wins overrides. Each shortcut compiles to a real method carrying its
-  body's `arity` and parameter kinds, with a `source_location` pointing at the block you declared —
-  keyword names are exact, positionals get generated ones (`__p0`, `__r1`, …). A wrong-arity call, a
+  body's `arity` and parameter kinds, with a `source_location` pointing at the block you declared.
+  Keyword names are exact, positionals get generated ones (`__p0`, `__r1`, …). A wrong-arity call, a
   missing required keyword and an unknown keyword raise `ArgumentError` at the call site, before any
   `rescue_from` handler is consulted.
-- `namespace(name) { ... }` — groups shortcuts behind a child facade, so `App.db.query` works without
+- `namespace(name) { ... }` groups shortcuts behind a child facade, so `App.db.query` works without
   burning root-level names. Takes the whole DSL, including nested namespaces. `clear_memos!` cascades
   into it. `configure` stays atomic across the whole tree: a pass that raises anywhere leaves the root
   and every namespace untouched. A `shortcut` of the same name overrides a namespace and drops the child.
-- `memoize` — permanent per-process caching, correct for `nil`/`false`, never caching a rescued fallback.
-- `rescue_from` — facade-scoped, facade-wide and global (`Briefly.rescue_from`) handlers whose return
+- `memoize`, permanent per-process caching, correct for `nil`/`false`, never caching a rescued fallback.
+- `rescue_from`, with facade-scoped, facade-wide and global (`Briefly.rescue_from`) handlers whose return
   value becomes the shortcut's value.
 - `clear_memos!` / `reset!`, `configure`, `shortcuts`, `shortcut?`, `inspect`.
 - Pack protocol: any object responding to `#install(builder, **opts)`. `use` accepts keywords,
   forwarded to the pack's `install`. `Briefly.register(name, pack)` / `Briefly.pack(name)` provide a
   pack registry, so `use "rails/db"` resolves; values may be a pack or a constant path resolved on
   first use, and an unknown name raises `Briefly::UnknownPackError`.
-- Method fabrication — the arity, `parameters` and `source_location` each shortcut reports — is
+- Method fabrication, meaning the arity, `parameters` and `source_location` each shortcut reports, is
   provided by [candor](https://github.com/svyatov/candor), the sole runtime dependency (candor itself
   has none). Compiled bodies live under `Candor::BODY_PREFIX`; a shortcut may not take a name there.
-- `Briefly::Rails` — `config`/`c`, `config_x`/`x`, `env` and its predicates, `root`, `cache`,
+- `Briefly::Rails`, with `config`/`c`, `config_x`/`x`, `env` and its predicates, `root`, `cache`,
   `logger`/`log`, `credentials`/`cred`, `helpers`/`h`, `routes`/`r`, `renderer`, `render`, plus a `db`
   namespace. Nothing in the pack is memoized. Its `Config`, `Env` and `View` groups are usable alone.
-- `Briefly::Rails::DB` — `connection`/`conn`, `transaction`/`txn`, `query`. `query` takes positional
+- `Briefly::Rails::DB`, with `connection`/`conn`, `transaction`/`txn`, `query`. `query` takes positional
   (`query(sql, 1)`) or named (`query(sql, id: 1)`) binds, and passes a bindless statement through
   unsanitized. Takes `base:` (default `"ApplicationRecord"`), resolved on every call so a reloaded
   class is never captured. Memoizes nothing and wires no lifecycle hook, so it works without a booted
   application.
-- `Briefly::Rails::Reload` — clears memos via `Rails.application.reloader.to_prepare`.
+- `Briefly::Rails::Reload` clears memos via `Rails.application.reloader.to_prepare`.
 - RBS signatures in `sig/`.