csb 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cad937e169f1330223f51cefcd7c636c8132eee9223ea86c99e465bde7140e14
-  data.tar.gz: 529f7c0fdbd85a7ed4332587ae09cc1ef45730f5a6819f6b389da048219fc446
+  metadata.gz: f05cd902f17175e076c30da2f46b027e9306a8027c535a592bb6b177e6075247
+  data.tar.gz: 863d4f9abbdf7489a78494065c6b6f50f3cef74865e692002d8f0214f5a2b3d4
 SHA512:
-  metadata.gz: 765f40840055d26afbca395312836480017ad08679d96fe295f6cf088a62ab1e09d019fbff41e2200cc9d6364beaef59ba26688f5290249787b83e9311f1e6bd
-  data.tar.gz: 07535155a1c0788a148b5fc8faadd7b03e76a661b134c5c47ecc5b2283e980ffc50ff0d4e5dbcf4fc19ae25bb5abcefbbd217484ff1da26d7f760e416ea6482e
+  metadata.gz: 2733b58f2e976bc92affbc510392949f12795d7d78f417fcee413255724f3d313088731869f0ed3179cc5ba6674cfb96133ae21fd44870d283004f26e6262d39
+  data.tar.gz: 1c7231a8a755593232e033d503d16951b2d39c998ce010c2063317460582cc9ae08a4a665594c2ddd2f38f514a293567ca968dbcd8cfdf0b373cce0a0c8aa5ee

data/.github/workflows/rspec.yml

@@ -16,15 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ["3.1", "3.2", "3.3", "3.4", "4.0"]
-        gemfile: ["rails71", "rails72", "rails80", "rails81"]
-        exclude:
-          # rails 8.0: support ruby 3.2+
-          - ruby: "3.1"
-            gemfile: "rails80"
-          # rails 8.1: support ruby 3.2+
-          - ruby: "3.1"
-            gemfile: "rails81"
+        ruby: ["3.3", "3.4", "4.0"]
+        gemfile: ["rails72", "rails80", "rails81"]
     steps:
       - uses: actions/checkout@v6
 

data/.gitignore

@@ -12,3 +12,6 @@
 Gemfile.lock
 /vendor/bundle
 .vscode/settings.json
+
+# Local-only Japanese skill drafts (not distributed)
+skills/**/*-ja.md

data/README.md

@@ -3,20 +3,39 @@
 
 # Csb
 
-A simple and streaming support CSV template engine for Ruby on Rails.
+A simple, streaming CSV template engine for Ruby on Rails. (The name is short for **CSV builder**.)
 
-## Features
+## Why csb?
 
-- Support for streaming downloads
-- Output in UTF-8 with BOM
-- Readable code
-- High testability
+Writing CSV downloads in Rails by hand looks easy, but the naive approach has recurring problems:
+
+```ruby
+# app/views/posts/index.csv.erb (the typical hand-written version)
+CSV.generate do |csv|
+  csv << %w[Date Category Title Content]
+  @posts.each do |post|
+    csv << [l(post.created_at.to_date), post.category.name, post.title, post.content]
+  end
+end
+```
+
+- **Garbled in Excel** — UTF-8 without a BOM shows up as mojibake.
+- **Memory / timeout errors** — loading and building the whole CSV in memory breaks on large datasets.
+- **Hard to maintain** — headers and values are defined far apart, so adding columns hurts readability.
+- **Hard to test** — the export logic is buried in a view, leaving you stuck with slow system tests.
+
+csb solves each of these:
+
+- **Excel-friendly** — output UTF-8 with a BOM so Excel opens it without garbling.
+- **Streaming download** — stream row by row to handle hundreds of thousands of records without memory or timeout errors.
+- **Readable** — define each column's header and value together on one line.
+- **Testable** — extract column definitions into a model and unit-test them directly.
 
 ## Usage
 
 ### Template handler
 
-In app/controllers/reports_controller.rb:
+In `app/controllers/reports_controller.rb`:
 
 ```ruby
 def index
@@ -24,61 +43,66 @@ def index
 end
 ```
 
-In app/views/reports/index.csv.csb:
+In `app/views/reports/index.csv.csb`:
 
 ```ruby
 csv.items = @reports
 
-# When there are many records
+# For large datasets, pass an Enumerator so streaming starts immediately
+# instead of waiting for every record to load:
 # csv.items = @reports.find_each
 
-# When there are many records with decorator
+# Combine with a decorator (e.g. Draper) while keeping it lazy:
 # csv.items = @reports.find_each.lazy.map(&:decorate)
 
+# Optional per-view overrides:
 # csv.filename = "reports_#{Time.current.to_i}.csv"
 # csv.streaming = false
 # csv.csv_options = { col_sep: "\t" }
 
-csv.cols.add('Update date') { |r| l(r.updated_at.to_date) }
+csv.cols.add('Update date') { |r| l(r.updated_at.to_date) } # block receives the record
 csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
-csv.cols.add('Content', :content)
-csv.cols.add('Empty')
-csv.cols.add('Static', 'dummy')
+csv.cols.add('Content', :content) # a Symbol calls the method on the record
+csv.cols.add('Static', 'dummy')   # a String is output verbatim
+csv.cols.add('Empty')             # no value -> empty column
+csv.cols.add('Dup', :col1)        # the same header may be added more than once
+csv.cols.add('Dup', :col2)        # (columns are output in definition order)
 ```
 
 Output:
 
 ```csv
-Update date,Categories,Content,Empty,Static
-2019/06/01,category1 category2,content1,,dummy
-2019/06/02,category3,content2,,dummy
+Update date,Categories,Content,Static,Empty,Dup,Dup
+2019/06/01,category1 category2,content1,dummy,,a,b
+2019/06/02,category3,content2,dummy,,c,d
 ```
 
+A link such as `link_to 'Download CSV', reports_path(format: :csv)` triggers the streaming download automatically.
+
 ### Directly
 
+When you want to generate the CSV outside of a request (e.g. in a background job), use `Csb::Builder`:
+
 ```ruby
 csv = Csb::Builder.new(items: items)
 csv.cols.add('Update date') { |r| l(r.updated_at.to_date) }
 csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
 csv.cols.add('Content', :content)
-csv.cols.add('Empty')
-csv.cols.add('Static', 'dummy')
-csv.build
-
-# =>
-# Update date,Categories,Content,Empty,Static
-# 2019/06/01,category1 category2,content1,,dummy
-# 2019/06/02,category3,content2,,dummy
+csv.build # => returns the CSV string
+
+# File.write('reports.csv', csv.build)
 ```
 
 ### Testing
 
+Move the column definitions out of the view so you can unit-test them:
+
 ```ruby
-# Your view
+# app/views/articles/index.csv.csb
 csv.items = @articles
 csv.cols = Article.csb_cols
 
-# Your Model
+# app/models/article.rb
 def self.csb_cols
   Csb::Cols.new do |cols|
     cols.add('Update date') { |r| I18n.l(r.updated_at.to_date) }
@@ -86,16 +110,20 @@ def self.csb_cols
     cols.add('Title', :title)
   end
 end
+```
 
-# Your test
-require 'csb/testing'
+```ruby
+# spec/models/article_spec.rb
+require 'csb/testing' # adds col_pairs and as_table
 
+# Assert a single record, row by row:
 expect(Article.csb_cols.col_pairs(article)).to eq [
   ['Update date', '2020-01-01'],
   ['Categories', 'test rspec'],
   ['Title', 'Testing'],
 ]
 
+# Assert the whole table (header row + value rows):
 expect(Article.csb_cols.as_table(articles)).to eq [
   ['Update date', 'Categories', 'Title'],
   ['2020-01-01', 'test rspec', 'Testing'],
@@ -132,13 +160,32 @@ Csb.configure do |config|
   config.utf8_bom = true # default: false
   config.streaming = false # default: true
   config.csv_options = { col_sep: "\t" } # default: {}
+
+  # Called when an error is raised during streaming. Without this, errors that
+  # happen mid-stream are not reported even if you use a tool like Bugsnag.
   config.after_streaming_error = ->(error) do # default: nil
     Rails.logger.error(error)
     Bugsnag.notify(error)
   end
+
+  # Error classes to ignore (not re-raise) during streaming, e.g. when the
+  # client disconnects before the download finishes.
+  config.ignore_class_names = %w[Puma::ConnectionError] # default: %w[Puma::ConnectionError]
 end
 ```
 
+## Agent skill
+
+This gem ships an [agent skill](skills/csb/) (`SKILL.md`) so AI coding agents (e.g. Claude Code) understand how to use csb. Install it into your project with [apm (Agent Package Manager)](https://github.com/microsoft/apm):
+
+```sh
+apm install aki77/csb/skills/csb
+```
+
+apm deploys the skill to each agent's directory (e.g. `.claude/skills/`) and locks the version in its lockfile.
+
+Alternatively, if your project already pulls csb in via Bundler, the [bundler-skills](https://github.com/aki77/bundler-skills) plugin auto-syncs this skill on `bundle install` — keeping the skill version locked to the gem version.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/aki77/csb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/csb.gemspec

@@ -20,15 +20,17 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|\.claude)/}) || f.match(%r{^skills/.*-ja\.md$})
+    end
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = '>= 3.1.0'
+  spec.required_ruby_version = '>= 3.3.0'
 
-  spec.add_dependency "rails", ">= 7.1.4"
+  spec.add_dependency "rails", ">= 7.2.0"
   spec.add_dependency "csv"
 
   spec.add_development_dependency "rake"

data/gemfiles/rails72.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 7.2.0'
 

data/gemfiles/rails80.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 8.0.0'
 

data/gemfiles/rails81.gemfile

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gem 'rails', '~> 8.1.0'
 

data/lib/csb/version.rb

@@ -1,3 +1,3 @@
 module Csb
-  VERSION = '0.15.0'
+  VERSION = '0.17.0'
 end

data/skills/csb/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: csb
+description: "Generate streaming, Excel-friendly CSV downloads in Rails with the csb gem. Use when implementing a CSV export/download, writing a `.csv.csb` template, building CSV via Csb::Builder, or testing column definitions. Not for parsing CSV."
+---
+
+# csb
+
+A simple, streaming CSV template engine for Ruby on Rails (the name is short for **CSV builder**). Use it to generate Excel-friendly, memory-safe CSV downloads with column definitions that are easy to read and unit-test.
+
+## When to use csb
+
+Reach for csb when building a CSV **download/export** in Rails. It replaces the naive hand-written `CSV.generate` in a view, which has recurring problems csb solves:
+
+| Problem with hand-written CSV | csb solution |
+| --- | --- |
+| Garbled in Excel (UTF-8 without BOM) | Optional UTF-8 BOM output |
+| Memory / timeout on large datasets | Row-by-row streaming download |
+| Headers and values defined far apart | Each column's header + value on one line |
+| Export logic buried in a view, hard to test | Extract column defs to a model and unit-test |
+
+Out of scope: **parsing** CSV (use the `csv` stdlib directly).
+
+## Approach 1: Template handler (the common case)
+
+Controller — just assign the records (an `ActiveRecord::Relation` is fine, no `.to_a` needed):
+
+```ruby
+# app/controllers/reports_controller.rb
+def index
+  @reports = Report.preload(:categories)
+end
+```
+
+View — `app/views/reports/index.csv.csb` (note the `.csv.csb` extension):
+
+```ruby
+csv.items = @reports
+
+# Each column: header + value defined together.
+csv.cols.add('Update date') { |r| l(r.updated_at.to_date) } # block receives the record
+csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
+csv.cols.add('Content', :content) # Symbol -> calls the method on the record
+csv.cols.add('Static', 'dummy')   # String  -> output verbatim
+csv.cols.add('Empty')             # no value -> empty column
+csv.cols.add('Dup', :col1)        # the same header may be added more than once;
+csv.cols.add('Dup', :col2)        # columns are output in definition order
+```
+
+A link like `link_to 'Download CSV', reports_path(format: :csv)` triggers the streaming download automatically.
+
+### Large datasets
+
+Pass an Enumerator so streaming starts immediately instead of loading every record first:
+
+```ruby
+csv.items = @reports.find_each
+# With a decorator (e.g. Draper), kept lazy:
+csv.items = @reports.find_each.lazy.map(&:decorate)
+```
+
+### Per-view overrides
+
+```ruby
+csv.filename = "reports_#{Time.current.to_i}.csv"
+csv.streaming = false
+csv.csv_options = { col_sep: "\t" }
+```
+
+## Approach 2: Direct generation (outside a request)
+
+For background jobs or anywhere outside a controller, use `Csb::Builder`:
+
+```ruby
+csv = Csb::Builder.new(items: items)
+csv.cols.add('Update date') { |r| l(r.updated_at.to_date) }
+csv.cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
+csv.cols.add('Content', :content)
+csv.build # => returns the CSV string
+
+# File.write('reports.csv', csv.build)
+```
+
+## Testing column definitions
+
+Extract the column definitions into a model method so they can be unit-tested apart from the view:
+
+```ruby
+# app/views/articles/index.csv.csb
+csv.items = @articles
+csv.cols = Article.csb_cols
+
+# app/models/article.rb
+def self.csb_cols
+  Csb::Cols.new do |cols|
+    cols.add('Update date') { |r| I18n.l(r.updated_at.to_date) }
+    cols.add('Categories') { |r| r.categories.pluck(:name).join(' ') }
+    cols.add('Title', :title)
+  end
+end
+```
+
+```ruby
+# spec/models/article_spec.rb
+require 'csb/testing' # adds col_pairs and as_table
+
+# One record, header/value pairs:
+expect(Article.csb_cols.col_pairs(article)).to eq [
+  ['Update date', '2020-01-01'],
+  ['Categories', 'test rspec'],
+  ['Title', 'Testing'],
+]
+
+# Whole table (header row + value rows):
+expect(Article.csb_cols.as_table(articles)).to eq [
+  ['Update date', 'Categories', 'Title'],
+  ['2020-01-01', 'test rspec', 'Testing'],
+  ['2020-02-01', 'rails gem', 'Rails 6.2'],
+]
+```
+
+## Configuration
+
+`config/initializers/csb.rb`:
+
+```ruby
+Csb.configure do |config|
+  config.utf8_bom = true              # default: false. Set true so Excel opens without mojibake.
+  config.streaming = false            # default: true
+  config.csv_options = { col_sep: "\t" } # default: {}
+
+  # Called when an error is raised during streaming. WITHOUT this, mid-stream
+  # errors are silently swallowed and won't reach tools like Bugsnag.
+  config.after_streaming_error = ->(error) do # default: nil
+    Rails.logger.error(error)
+    Bugsnag.notify(error)
+  end
+
+  # Error classes to ignore (not re-raise) during streaming, e.g. when the
+  # client disconnects before the download finishes.
+  config.ignore_class_names = %w[Puma::ConnectionError] # default: %w[Puma::ConnectionError]
+end
+```
+
+## Pitfalls
+
+- The view must use the `.csv.csb` extension.
+- Trigger the download with `format: :csv` (e.g. `link_to 'Download', reports_path(format: :csv)`).
+- The `cols.add` value rules: block → receives the record; `Symbol` → calls that method; `String` → literal; omitted → empty cell.
+- Streaming errors are swallowed unless you set `config.after_streaming_error` — set it if you rely on error reporting.
+- For big tables, pass `find_each` (an Enumerator), not a fully-loaded array, to keep streaming memory-safe.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: csb
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0
 platform: ruby
 authors:
 - aki77
 bindir: exe
 cert_chain: []
-date: 2026-01-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.4
+        version: 7.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.1.4
+        version: 7.2.0
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -98,7 +98,6 @@ files:
 - bin/console
 - bin/setup
 - csb.gemspec
-- gemfiles/rails71.gemfile
 - gemfiles/rails72.gemfile
 - gemfiles/rails80.gemfile
 - gemfiles/rails81.gemfile
@@ -112,6 +111,7 @@ files:
 - lib/csb/template.rb
 - lib/csb/testing.rb
 - lib/csb/version.rb
+- skills/csb/SKILL.md
 homepage: https://github.com/aki77/csb
 licenses:
 - MIT
@@ -126,14 +126,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A simple and streaming support CSV template engine for Ruby on Rails.
 test_files: []

data/gemfiles/rails71.gemfile

@@ -1,5 +0,0 @@
-source "http://rubygems.org"
-
-gem 'rails', '~> 7.1.4'
-
-gemspec path: '../'