decisive 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b945f08db65a5275cf3630aef57ba562763630b8f7d4da3c3774d84f2c403c52
-  data.tar.gz: a64ba39fba71a016e42506dd03b0db8b3ac7a0e02d93ef44453b072b3175d8d7
+  metadata.gz: d43e1342475b84925559c143552a768a720944559d2b24e8291c0bc6f07cf844
+  data.tar.gz: 50678ed3c307c531395b1b3ffdd6fe7d7adf0dd001ed4bb889f60c4f9e1fc784
 SHA512:
-  metadata.gz: 12271c423c16f11a47fd4fe5475addd94c935350c591d79ebcc9f9314ba0f2855d8018e3b3fb7ee1b376ef22c90da62d3469f96c3b7306bc4576d434ea2cef03
-  data.tar.gz: e3da77344bbd71dc17a12c344065211b9ac212368701ce1e7c45882b84cee6d4f419fdf7c8c34b36e9e2287c9fa813feb5b5c3cdf64fc8cef4c9277e55934f9a
+  metadata.gz: a3b81bd36c87486123533bb0ccb8192d483856509a5806e1112e810076a28748d53590f2932f24f99b58c04b61ed65d5e35958ec14ac133dde005b7c9efd7c83
+  data.tar.gz: b9a75085e0161dfa76dbbfe107ee672b5e0c375ee1d5bb7e62df3276e001a0db12caf4a17c0169d2953ecdca9ee13a898ca73ea53e63d24baabd2451286324f5

data/.github/workflows/ci.yml

@@ -5,14 +5,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        gemfile: [ rails_7.0, rails_7.1, rails_7.2 ]
-        ruby: [ 3.1, 3.2, 3.3 ]
+        gemfile: [ rails_8.0, rails_8.1 ]
+        ruby: [ 3.3, 3.4, '4.0' ]
 
     runs-on: ubuntu-latest
     env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/.ruby-version

@@ -1 +1 @@
-ruby-3.3.4
+ruby-4.0.2

data/Appraisals

@@ -1,12 +1,7 @@
-appraise "rails-7.0" do
-  gem "actionview", "~>7.0.0"
+appraise "rails-8.0" do
+  gem "actionview", "~>8.0.0"
 end
 
-appraise "rails-7.1" do
-  gem "actionview", "~>7.1.0"
+appraise "rails-8.1" do
+  gem "actionview", "~>8.1.0"
 end
-
-appraise "rails-7.2" do
-  gem "actionview", "~>7.2.0"
-end
-

data/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+bundle exec rspec                       # run the suite (also `rake spec`, the default task)
+bundle exec rspec spec/csv_spec.rb:87   # single example by line
+bundle exec rspec --only-failures       # uses .rspec_status
+bin/console                             # IRB with decisive loaded
+```
+
+Rails version matrix via appraisal (CI runs rails 8.0/8.1 × ruby 3.3/3.4/4.0):
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rails-8.1 rake
+BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rspec
+```
+
+## Architecture
+
+Decisive is an ActionView template handler for the `.decisive` extension. `Decisive::Rails` (an
+engine, only defined when Rails is) registers the handler and the `:xls` mime type.
+
+**The compile step is the center of the design.** `TemplateHandler.call` does not render anything —
+it returns a string of Ruby that Rails compiles into the view. That generated code:
+
+1. `extend Decisive::DSL` on the view, then evaluates the *entire template source as one expression*
+   whose value is a **context object**;
+2. sets `Content-Disposition` / `Content-Type` / `Content-Transfer-Encoding` from that context;
+3. either pumps `context.each` into `response.stream`, or returns `context.to_csv` / `context.to_xls`.
+
+So the generated code references `response`, `controller`, and `@stream` as bare names in the view's
+scope. Anything that changes headers or the stream/buffer decision lives in the heredoc in
+`template_handler.rb`, not in the contexts.
+
+`DSL#csv` / `DSL#xls` pick one of three contexts:
+
+| Context | When | Behavior |
+| --- | --- | --- |
+| `StreamCSVContext` | `csv`, default `stream: true` | Columns are collected once at template-eval time, so headers are fixed up front. Raises unless the controller `is_a?(ActionController::Live)`, and unless the block has arity 0. |
+| `RenderCSVContext` | `csv ..., stream: false` | Buffers everything through `Renderer`. The block is re-run per record, so columns may vary per row. |
+| `RenderXLSContext` | `xls` | Worksheets come either from `worksheet` calls inside the block, or from a `{name => records}` hash argument with one shared column block. Renders with RubyXL. |
+
+`Renderer` (used by the two non-streaming contexts) builds a hash per record and takes the **union of
+keys in first-seen order** as the header — that is what makes non-deterministic headers work, and it
+is why the two pending `xit` specs about repeating column names fail: duplicate labels collapse onto
+one key.
+
+**`#column` is implemented twice** — `StreamCSVContext#column` (streaming) and `Renderer::Row#column`
+(non-streaming). They must stay behaviorally identical: value resolution is block > `Symbol`
+accessor > literal value > accessor inferred from the label (`"Full name".parameterize.underscore`),
+and every value is `to_s`'d.
+
+`ViewDelegation` is `method_missing` forwarding to the view, mixed into `Renderer::Row`,
+`StreamCSVContext`, and `RenderXLSContext`. It is why template blocks can call view helpers even
+though they are `instance_exec`'d against decisive's objects. Instance variables deliberately do
+*not* follow — they belong to the view — so blocks see `nil` for `@foo`. It also scrubs its own
+frames from `NameError` backtraces to keep the template's line on top; a spec asserts on that.
+
+XLS specifics in `RenderXLSContext`: sheet names are sanitized (illegal chars → spaces, stripped of
+surrounding quotes, truncated to 31 chars), and cells are always written as **data, never formulas**
+— a leading `=` is intentionally literal (see commit 3bdd657). Do not reintroduce formula detection.
+
+## Testing conventions
+
+Specs never boot Rails. Each example fakes a template with `Struct.new(:source)`, then
+`eval(Decisive::TemplateHandler.call(template))` — meaning the RSpec example itself plays the role of
+the view. Consequences worth knowing before writing a spec:
+
+- `response` and `controller` are `let` doubles; `@records` / `@worksheets` are ivars set in the example.
+- Methods defined on the example group (`shout`, `whisper`) are the "view helpers" that
+  `ViewDelegation` finds — including private ones.
+- Streaming examples assert with `expect(response.stream).to receive(:write).with(...)`, in order.
+- `ActionController::Live` is `stub_const`'d to a bare module, with `controller.is_a?` stubbed.
+- XLS examples write to `tmp/` and read back through `Decisive::XLSHasher`, which is public API for
+  downstream test suites, not just an internal helper.

data/README.md

@@ -70,6 +70,25 @@ Visiting /users.csv will render a file named "users-2010_01_01.csv" with the fol
 | frodo@example.com | Frodo Baggins  | Yes      |       | 2002-06-19 |
 | sam@example.com   | Samwise Gamgee |          | Frodo | 2008-10-13 |
 
+### Helper methods
+
+Decisive evaluates the blocks in your template against its own objects, but they
+still reach the view's helper methods, just like the rest of the template:
+
+```ruby
+# app/views/users/index.csv.decisive
+
+csv @users, filename: "users.csv", stream: false do
+  column "Signed up" do |user|
+    l(user.created_at, format: :short) # a view helper
+  end
+end
+```
+
+The one thing blocks cannot see is the view's instance variables: `@users` above
+is read when the template runs, but inside a block `@users` is nil. Assign it to
+a local first, or reach for a helper method.
+
 ### Debugging
 
 Errors in your decisive template will often be swallowed while streaming is enabled, resulting in only some of the csv being rendered, without any explanation. You can temporarily switch decisive into non-streaming mode to see these errors:

data/gemfiles/{rails_7.0.gemfile → rails_8.0.gemfile}

@@ -3,6 +3,6 @@
 source "https://rubygems.org"
 
 gem "byebug"
-gem "actionview", "~>7.0.0"
+gem "actionview", "~>8.0.0"
 
 gemspec path: "../"

data/gemfiles/{rails_7.1.gemfile → rails_8.1.gemfile}

@@ -3,6 +3,6 @@
 source "https://rubygems.org"
 
 gem "byebug"
-gem "actionview", "~>7.1.0"
+gem "actionview", "~>8.1.0"
 
 gemspec path: "../"

data/lib/decisive/render_csv_context.rb

@@ -3,9 +3,9 @@ require "active_support/core_ext/string/inflections"
 require "decisive/renderer"
 
 module Decisive
-  class RenderCSVContext < Struct.new(:records, :filename, :block)
+  class RenderCSVContext < Struct.new(:records, :filename, :block, :view)
     def to_csv(*args, **kwargs)
-      Renderer.new(records, block).map do |row|
+      Renderer.new(records, block, view).map do |row|
         row.to_csv(*args, **kwargs)
       end.join
     end

data/lib/decisive/render_xls_context.rb

@@ -1,8 +1,11 @@
 require "rubyXL"
 require "decisive/renderer"
+require "decisive/view_delegation"
 
 module Decisive
-  class RenderXLSContext < Struct.new(:worksheets, :filename, :block)
+  class RenderXLSContext < Struct.new(:worksheets, :filename, :block, :view)
+    include ViewDelegation
+
     class Worksheet < Struct.new(:records, :name, :block); end
 
     def initialize *args
@@ -38,7 +41,7 @@ module Decisive
     def render xls
       worksheets.each do |worksheet|
         sheet = xls.add_worksheet(sanitize_name(worksheet.name)).tap do |sheet|
-          Renderer.new(worksheet.records, worksheet.block).each.with_index do |row, row_index|
+          Renderer.new(worksheet.records, worksheet.block, view).each.with_index do |row, row_index|
             row.each.with_index do |cell, cell_index|
               sheet.add_cell row_index, cell_index, cell.to_s
             end

data/lib/decisive/renderer.rb

@@ -1,5 +1,7 @@
+require "decisive/view_delegation"
+
 module Decisive
-  class Renderer < Struct.new(:records, :block)
+  class Renderer < Struct.new(:records, :block, :view)
     include Enumerable
 
     def each &block
@@ -24,11 +26,13 @@ module Decisive
 
     def hashes
       @hashes ||= records.map do |record|
-        Row.new(record, block).to_hash
+        Row.new(record, block, view).to_hash
       end
     end
 
-    class Row < Struct.new(:record, :block)
+    class Row < Struct.new(:record, :block, :view)
+      include ViewDelegation
+
       module Nothing; end
 
       def to_hash

data/lib/decisive/stream_csv_context.rb

@@ -1,8 +1,11 @@
 require "csv"
 require "active_support/core_ext/string/inflections"
+require "decisive/view_delegation"
 
 module Decisive
-  class StreamCSVContext < Struct.new(:records, :filename, :block)
+  class StreamCSVContext < Struct.new(:records, :filename, :block, :view)
+    include ViewDelegation
+
     class Column < Struct.new(:label, :block); end
 
     def initialize *args

data/lib/decisive/template_handler.rb

@@ -59,14 +59,14 @@ module Decisive
       if stream
         raise StreamingNotEnabledByControllerError unless controller.is_a?(ActionController::Live)
         raise StreamIncompatibleBlockArgumentError if block.arity != 0
-        StreamCSVContext.new(records, filename, block)
+        StreamCSVContext.new(records, filename, block, self)
       else
-        RenderCSVContext.new(records, filename, block)
+        RenderCSVContext.new(records, filename, block, self)
       end
     end
 
     def xls worksheets=nil, filename:, &block
-      RenderXLSContext.new(worksheets, filename, block)
+      RenderXLSContext.new(worksheets, filename, block, self)
     end
   end
 end

data/lib/decisive/version.rb

@@ -1,3 +1,3 @@
 module Decisive
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/decisive/view_delegation.rb

@@ -0,0 +1,20 @@
+module Decisive
+  # Blocks in a decisive template are evaluated against decisive's own objects,
+  # so without this they would be cut off from the view's helper methods.
+  module ViewDelegation
+    private
+
+    def method_missing name, *args, **kwargs, &block
+      return super unless view.respond_to?(name, true)
+      view.send(name, *args, **kwargs, &block)
+    rescue NameError => error
+      # Keep the template's own line at the top of the backtrace.
+      error.set_backtrace(error.backtrace.reject { |line| line.include?(__FILE__) })
+      raise
+    end
+
+    def respond_to_missing? name, include_private = false
+      view.respond_to?(name, include_private) || super
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: decisive
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Micah Geisel
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview
@@ -121,6 +120,7 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - Appraisals
+- CLAUDE.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -129,9 +129,8 @@ files:
 - bin/setup
 - decisive.gemspec
 - gemfiles/.bundle/config
-- gemfiles/rails_7.0.gemfile
-- gemfiles/rails_7.1.gemfile
-- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
 - lib/decisive.rb
 - lib/decisive/render_csv_context.rb
 - lib/decisive/render_xls_context.rb
@@ -139,12 +138,12 @@ files:
 - lib/decisive/stream_csv_context.rb
 - lib/decisive/template_handler.rb
 - lib/decisive/version.rb
+- lib/decisive/view_delegation.rb
 - lib/decisive/xls_hasher.rb
 homepage: https://github.com/botandrose/decisive
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -159,8 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: DSL for rendering CSVs
 test_files: []

data/gemfiles/rails_7.2.gemfile

@@ -1,8 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "byebug"
-gem "actionview", "~>7.2.0"
-
-gemspec path: "../"