importu 0.1.0 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 919b992ad441913c1a9de0cb80f81640f95be6031133908b14b792ce3831bf15
+  data.tar.gz: 555d5534282aab463239f6d8323c78083d75e2d861e0627b502948a7c04a7a1c
+SHA512:
+  metadata.gz: b950525fd0c9998a6b6897debb9658ffb0d9c1ed7360aa0e870264daaa17184c6b5ffcdbee2991bd680f5838b427516dffb4cfd8a24fdff688f99e48c2197870
+  data.tar.gz: eb2fda5952a2a18baba157a55799d06d934babad3922b4f829ccbeba854e69f46eea71ebcd58f7990977d7fa3c21ca9fe677faaf1767b851e2938b4c25c445d7

data/.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig helps maintain consistent coding styles
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

data/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.1", "3.2", "3.3", "4.0"]
+        appraisal: [standalone, rails-7-2, rails-8-0, rails-8-1]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Install appraisal dependencies
+        run: bundle exec appraisal ${{ matrix.appraisal }} bundle install
+
+      - name: Run tests
+        run: bundle exec appraisal ${{ matrix.appraisal }} rspec
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+      - name: Verify YARD documentation coverage
+        run: bundle exec rake yardstick

data/.gitignore

@@ -1,3 +1,7 @@
 Gemfile.lock
 .bundle/
+.yardoc/
+coverage/
+doc/
+spec/examples.txt
 vendor/bundle

data/.rspec

@@ -0,0 +1 @@
+--order random

data/.rubocop.yml

@@ -0,0 +1,311 @@
+plugins:
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "gemfiles/**/*"
+    - "vendor/**/*"
+
+# Match existing style: allow flexible layout
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/SpaceInsideBlockBraces:
+  Enabled: false
+
+Layout/FirstArrayElementIndentation:
+  Enabled: false
+
+Layout/FirstHashElementIndentation:
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/MultilineHashBraceLayout:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+# Allow one-liner methods for simple accessors
+Style/SingleLineMethods:
+  Enabled: false
+
+# Match existing style: allow compact empty class bodies
+Style/EmptyMethod:
+  EnforcedStyle: compact
+
+# Allow trailing comma in multiline for cleaner diffs
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+
+# Match existing style: prefer double quotes
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Match existing style: allow proc { } and -> { } based on context
+Style/Lambda:
+  EnforcedStyle: literal
+
+# Allow raising with string message directly
+Style/RaiseArgs:
+  Enabled: false
+
+# Disable guard clause enforcement (existing style is mixed)
+Style/GuardClause:
+  Enabled: false
+
+# Match existing style: allow explicit return in short methods
+Style/RedundantReturn:
+  Enabled: false
+
+# Match existing style: use && and || over and/or
+Style/AndOr:
+  EnforcedStyle: always
+
+# Match existing style: allow conditional assignment
+Style/ConditionalAssignment:
+  Enabled: false
+
+# Allow rescuing StandardError explicitly
+Style/RescueStandardError:
+  Enabled: false
+
+# Match existing style: allow `private def` syntax
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+
+# Disable overly pedantic cops
+Style/Documentation:
+  Enabled: false
+
+Style/DocumentationMethod:
+  Enabled: false
+
+# Match existing style: allow compact module/class definitions
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+# Match existing style: allow rescue modifier for simple cases
+Style/RescueModifier:
+  Enabled: false
+
+# Match existing style: allow string concatenation
+Style/StringConcatenation:
+  Enabled: false
+
+Style/LineEndConcatenation:
+  Enabled: false
+
+# Match existing style: allow word arrays with quotes
+Style/WordArray:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+# Match existing style: allow hash rocket for alignment
+Style/HashSyntax:
+  EnforcedShorthandSyntax: never
+
+Style/RedundantSelf:
+  Enabled: true
+
+# Allow redundant :: for top-level constants (clearer intent)
+Style/RedundantConstantBase:
+  Enabled: false
+
+# Allow block comments for larger sections
+Style/BlockComments:
+  Enabled: false
+
+# Allow multiline if modifier
+Style/MultilineIfModifier:
+  Enabled: false
+
+# Allow has_key? for clarity
+Style/PreferredHashMethods:
+  Enabled: false
+
+# Allow empty string interpolation
+Style/EmptyStringInsideInterpolation:
+  Enabled: false
+
+# Allow multiline ternary (matches existing style)
+Style/MultilineTernaryOperator:
+  Enabled: false
+
+Style/HashConversion:
+  Enabled: true
+
+# Allow parallel assignment (matches existing style)
+Style/ParallelAssignment:
+  Enabled: false
+
+# Allow Proc.new style (matches existing style)
+Style/Proc:
+  Enabled: false
+
+# Allow existing except pattern
+Style/HashExcept:
+  Enabled: false
+
+Style/RedundantBegin:
+  Enabled: true
+
+# Keep existing self assignment patterns
+Style/RedundantSelfAssignmentBranch:
+  Enabled: false
+
+# Gemspec settings
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Gemspec/OrderedDependencies:
+  Enabled: true
+
+Style/ExpandPathArguments:
+  Enabled: true
+
+Lint/UnusedBlockArgument:
+  Enabled: true
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Lint/UselessAssignment:
+  Enabled: true
+
+# Allow 1.times for spec clarity
+Lint/UselessTimes:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - "spec/**/*"
+
+# Allow percent string arrays with quotes
+Lint/PercentStringArray:
+  Enabled: false
+
+# Metrics
+Metrics/BlockLength:
+  Max: 60
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+    - "lib/importu/converters.rb"  # Converter definitions are intentionally grouped
+
+Metrics/MethodLength:
+  Max: 25
+  Exclude:
+    - "lib/importu/converters.rb"  # Converter definitions are intentionally grouped
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# Naming
+Naming/BlockForwarding:
+  Enabled: false
+
+# Allow memoization with different variable names (intentional pattern)
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+Performance/RedundantMerge:
+  Enabled: true
+
+# Allow existing case indentation style
+Layout/CaseIndentation:
+  Enabled: false
+
+# Allow assignment in condition (idiomatic Ruby pattern)
+Lint/AssignmentInCondition:
+  Enabled: false
+
+# Allow missing super in custom exceptions (intentional)
+Lint/MissingSuper:
+  Enabled: false
+
+# Allow empty blocks in specs (intentional DSL usage)
+Lint/EmptyBlock:
+  Enabled: false
+
+# Keep existing argument forwarding style
+Style/ArgumentsForwarding:
+  Enabled: false
+
+# Allow if modifier to be optional
+Style/IfUnlessModifier:
+  Enabled: false
+
+# Allow existing next/break style
+Style/Next:
+  Enabled: false
+
+# Allow trailing commas in method calls (existing style)
+Style/TrailingCommaInArguments:
+  Enabled: false
+
+# Allow semicolons in one-liners (existing test style)
+Style/Semicolon:
+  Enabled: false
+
+# Allow flexible hash brace spacing
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+# Enforce frozen_string_literal
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+# Allow simple heredoc delimiters
+Naming/HeredocDelimiterNaming:
+  Enabled: false
+
+# Allow slight overruns in specs
+Layout/LineLength:
+  Max: 105

data/.simplecov

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+require "simplecov"
+
+# Make each appraisal have a unique simplecov name. Needed to allow merging
+# of results since each appraisal may only run a subset of relevant specs.
+gemfile = ENV.fetch("BUNDLE_GEMFILE", "system")
+SimpleCov.command_name "appraisal:#{File.basename(gemfile, ".gemfile")}"
+
+SimpleCov.start do
+  add_filter do |source_file|
+    # Filter out all files that are not in the gem's lib/ directory
+    source_file.filename.start_with?("#{SimpleCov.root}/lib/") == false
+  end
+end

data/.yardstick.yml

@@ -0,0 +1,36 @@
+---
+# Minimum documentation coverage required for verifications to pass
+threshold: 70
+
+# Specify if the coverage summary should be displayed
+verbose: true
+
+# List of paths to measure. List may contain paths to files or globs
+path:
+  - lib/**/*.rb
+
+# Specify if the threshold should match the coverage
+require_exact_threshold: false
+
+# Rules that get applied to each source code file
+rules:
+  # Restrict method summary to 80 characters. This is annoying because where
+  # else are you supposed to be able to describe the behavior of the method
+  # or instructions on replacing it with your own implementation?
+  Summary::Length:
+    enabled: false
+    exclude: []
+
+  # Summary should not end with a period. This is a YARD convention but
+  # conflicts with natural documentation style when using multiple sentences.
+  Summary::Delimiter:
+    enabled: false
+    exclude: []
+
+  # Require summary to appear on one line in comments. Even if we left the
+  # 80 character restriction, this would be annoying because methods and
+  # attributes are often indented so you lose quite a few characters from
+  # a possible description without breaking the 80 character terminal width.
+  Summary::SingleLine:
+    enabled: false
+    exclude: []

data/Appraisals

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+appraise "standalone" do
+  # w/o any frameworks
+end
+
+appraise "rails-7-2" do
+  gem "sqlite3", "~> 2.0"
+  gem "database_cleaner-active_record"
+  gem "activerecord", "~> 7.2.0"
+end
+
+appraise "rails-8-0" do
+  gem "sqlite3", "~> 2.0"
+  gem "database_cleaner-active_record"
+  gem "activerecord", "~> 8.0.0"
+end
+
+appraise "rails-8-1" do
+  gem "sqlite3", "~> 2.0"
+  gem "database_cleaner-active_record"
+  gem "activerecord", "~> 8.1.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-01-28
+
+### Breaking Changes
+
+See [UPGRADING.md](UPGRADING.md) for detailed migration steps.
+
+- Require Ruby >= 3.1
+- Add csv and bigdecimal as gem dependencies (no longer default gems in Ruby 3.4+)
+- Replace multi_json with stdlib json (JSON::ParserError instead of MultiJson::DecodeError)
+- Drop Rails 4.x and 5.x support; minimum is now Rails 7.2
+
+### Added
+
+- Add CONTRIBUTING.md with development setup and architecture overview
+- Add explicit `backend: :auto` option for discoverable backend auto-detection
+
+### Changed
+
+- `require "importu"` now loads the Importer class (previously required explicit `require "importu/importer"`)
+- Update README with Quick Start, Sources, and Allowed Actions sections
+- Improve YARD documentation coverage (55% to 70%+)
+- Improve MissingField error to include available fields from source data
+- Improve error messages when create/update actions are not allowed (now includes fix guidance)
+- Document before_save as a backend hook that backends may choose to honor
+- Extract AR-specific error normalization from Summary into ActiveRecord backend
+- InvalidRecord now accepts normalized_message for aggregation-friendly error messages
+
+### Fixed
+
+- Fix datetime converter to avoid Rails deprecation warning
+- Fix validation_errors not being passed to InvalidRecord in ActiveRecord backend
+- Remove phantom require for nonexistent backends/ruby file
+- Add explicit require for delegate stdlib
+- Add explicit require for date stdlib
+- Add explicit require for forwardable stdlib
+- Fix ConverterStub to properly initialize Proc superclass
+- Fix keyword argument splatting throughout codebase
+- Fix CSV source to create fresh reader on each rows call
+- Fix JSON source to handle empty documents
+- Fix ActiveRecord backend for Rails 7+ errors API
+
+## [0.1.0] - 2017-09-25
+
+Initial release.

data/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Importu
+
+## Development Setup
+
+```bash
+git clone https://github.com/dhedlund/importu.git
+cd importu
+bundle install
+bundle exec appraisal install
+```
+
+## Running Checks
+
+The preflight task runs specs, RuboCop, and YARD coverage in one command:
+
+```bash
+bundle exec rake preflight
+```
+
+To run checks individually:
+
+```bash
+bundle exec rspec              # Test suite (standalone, no Rails)
+bundle exec rubocop            # Code style
+bundle exec rake yardstick     # Documentation coverage
+```
+
+To test against specific Rails versions:
+
+```bash
+bundle exec appraisal rspec              # All Rails versions
+bundle exec appraisal standalone rspec   # No Rails
+bundle exec appraisal rails-8-1 rspec    # Specific version
+```
+
+## Pull Requests
+
+Before submitting a PR, run the preflight checks:
+
+```bash
+bundle exec rake preflight
+```
+
+This runs the test suite, RuboCop, and YARD coverage verification.
+
+Also:
+
+1. Add tests for new functionality
+2. Update CHANGELOG.md under `[Unreleased]` for user-facing changes
+
+## Architecture Overview
+
+The codebase is organized around a few core concepts:
+
+- **Sources** (`lib/importu/sources/`) - Parse input formats (CSV, JSON, XML, Ruby hashes). Each source provides a `rows` enumerator.
+
+- **Backends** (`lib/importu/backends/`) - Persist records to a data store. The ActiveRecord backend is included; others can be added.
+
+- **Middleware** (`lib/importu/backends/middleware/`) - Wrap backends to add cross-cutting behavior like duplicate detection and action enforcement.
+
+- **Converters** (`lib/importu/converters.rb`) - Transform raw field values into typed data. Built-in converters handle strings, integers, dates, booleans, etc.
+
+- **Summary** (`lib/importu/summary.rb`) - Aggregates import results (created, updated, invalid counts and error details).
+
+The importer DSL (`lib/importu/config_dsl.rb`) ties these together, letting you declare fields, converters, and backend configuration in a readable format.
+
+## Adding a New Source
+
+Implement a class with:
+- `initialize(infile, **options)` - Accept input and source-specific options
+- `rows` - Return an enumerator yielding hashes (one per record)
+
+See `lib/importu/sources/csv.rb` for an example.
+
+## Adding a New Backend
+
+Implement a class with:
+- `self.supported_by_model?(model)` - Return true if this backend handles the model
+- `initialize(model:, finder_fields:, **options)` - Accept configuration
+- `find(record)` - Look up existing record, return nil if not found
+- `create(record)` - Create new record, return `[status, object]`
+- `update(record, object)` - Update existing record, return `[status, object]`
+
+Register it with `Importu::Backends.registry.register(:name, YourBackend)`.
+
+See `lib/importu/backends/active_record.rb` for an example.

data/Gemfile

@@ -1,4 +1,8 @@
-source 'http://rubygems.org'
+# frozen_string_literal: true
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in importu.gemspec
 gemspec
+
+gem "irb" # Required by YARD on Ruby 4.0+
+gem "yardstick", "~> 0.9", require: false

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Daniel Hedlund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.