support_table_data 1.4.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57189f00e55af0f6d3476edbe8921bfb7ba341fa9a1c6e51eb0674e66327bd12
-  data.tar.gz: f80d9a8f7ce4877aec13c5f0151ddc017bbcb94ea4b85b2c404b23161d11aaf8
+  metadata.gz: '081b2612659ea90591ecf5fd7386acbb9d10dbd90c20301e12fba39d3d81e4b3'
+  data.tar.gz: b7d4960153f4799031127c8e2fb6ffaa5da49acc1e59833b64c9f417dd9d77df
 SHA512:
-  metadata.gz: df96d9b761bb03c2ddc9bc915bc5441c24f8bf06e20f53fb2d962ae74c19f6828f84f3b4c3f5c1fe6766bceed05c4e64ec6ae458c64c9e6bf549855b4a492222
-  data.tar.gz: 820ebdea69220e6a03c5b0966138285af9c7e3181c73532917d074c392cc0a708d5bb4c67d0d11f937ef0ffd81e828f226f64aa0a632ec7475578d8edc2a53d6
+  metadata.gz: e38a2f56f37888a737c8493ec0078666cf8a138415326946829c506a57fc81f5bc3e8407232e7bacbd82a5d0066d9513dd14340360e9d4179a3b1d51a7d69517
+  data.tar.gz: 569bbabe38749923686c5d9aa757851f6ba3fad64317f18e3fdb209aec9c714ed1f020a6c07a1588464d1ed9c129bb983ae25d5378ae324b0abee8e467e0fa96

data/ARCHITECTURE.md

@@ -0,0 +1,538 @@
+# Support Table Data Architecture
+
+This document describes the architecture and design patterns of the `support_table_data` gem, which provides a robust solution for managing static support tables (lookup tables) in ActiveRecord applications.
+
+## Overview
+
+The SupportTableData gem solves the common problem of managing small, canonical datasets that exist at the intersection of data and code. These support tables contain a limited number of rows with values that are often referenced in application logic, making them critical for proper application function.
+
+## Core Components
+
+### Main Components Overview
+
+```mermaid
+flowchart TB
+    subgraph "Application Layer"
+        Model[ActiveRecord Model]
+        DataFiles[Data Files<br/>YAML/JSON/CSV]
+    end
+
+    subgraph "SupportTableData Gem"
+        Concern[SupportTableData Module]
+        Parser[File Parser]
+        Sync[Data Synchronizer]
+        Helpers[Helper Methods]
+    end
+
+    subgraph "Infrastructure"
+        DB[(Database)]
+        Rails[Rails Environment]
+        Rake[Rake Tasks]
+    end
+
+    Model --> Concern
+    DataFiles --> Parser
+    Parser --> Sync
+    Sync --> DB
+    Concern --> Helpers
+    Rails --> Rake
+    Rake --> Sync
+
+    style Concern fill:#e1f5fe
+    style DataFiles fill:#f3e5f5
+    style DB fill:#e8f5e8
+```
+
+## Data Flow Architecture
+
+The gem follows a clear data flow pattern from static files to database records:
+
+```mermaid
+flowchart LR
+    subgraph "Source Data"
+        YML[YAML Files]
+        JSON[JSON Files]
+        CSV[CSV Files]
+    end
+
+    subgraph "Processing"
+        Parse[File Parser]
+        Validate[Data Validation]
+        Transform[Data Transformation]
+    end
+
+    subgraph "Storage"
+        Memory[In-Memory Cache]
+        DB[(Database Tables)]
+    end
+
+    subgraph "Usage"
+        Helpers[Helper Methods]
+        Queries[Database Queries]
+        Predicates[Predicate Methods]
+    end
+
+    YML --> Parse
+    JSON --> Parse
+    CSV --> Parse
+    Parse --> Validate
+    Validate --> Transform
+    Transform --> Memory
+    Transform --> DB
+    Memory --> Helpers
+    DB --> Queries
+    Helpers --> Predicates
+
+    style Parse fill:#fff3e0
+    style DB fill:#e8f5e8
+    style Helpers fill:#e3f2fd
+```
+
+## Class Structure
+
+### Core Module Design
+
+```mermaid
+classDiagram
+    class SupportTableData {
+        +data_directory : String
+        +sync_all!() : Hash
+        +support_table_classes() : Array
+    }
+
+    class ActiveRecord_Model {
+        +support_table_key_attribute : String
+        +support_table_data_directory : String
+        +add_support_table_data(path)
+        +sync_table_data!() : Array
+        +named_instance(name) : Record
+        +instance_names() : Array
+        +protected_instance?(record) : Boolean
+    }
+
+    class NamedInstanceHelpers {
+        +class_name() : Record
+        +class_name_question() : Boolean
+        +class_name_attribute() : Value
+    }
+
+    class FileParser {
+        +parse_yaml(content) : Hash
+        +parse_json(content) : Hash
+        +parse_csv(content) : Array
+    }
+
+    class DataSynchronizer {
+        +sync_records(data) : Array
+        +create_record(attributes) : Record
+        +update_record(record, attributes) : Record
+    }
+
+    SupportTableData --> ActiveRecord_Model : extends
+    ActiveRecord_Model --> NamedInstanceHelpers : generates
+    ActiveRecord_Model --> FileParser : uses
+    ActiveRecord_Model --> DataSynchronizer : uses
+
+    note for NamedInstanceHelpers "Methods are dynamically generated based on data file content"
+```
+
+## Named Instance System
+
+The gem's most powerful feature is its named instance system, which generates helper methods from data files:
+
+```mermaid
+flowchart TD
+    subgraph "Data File Structure"
+        HashData[Hash-based Data]
+        ArrayData[Array-based Data]
+    end
+
+    subgraph "Method Generation"
+        ClassMethods[Class Methods<br/>Status.pending]
+        InstanceMethods[Instance Methods<br/>status.pending?]
+        AttributeHelpers[Attribute Helpers<br/>Status.pending_id]
+    end
+
+    subgraph "Runtime Usage"
+        FindRecord[Find Specific Record]
+        TestRecord[Test Record Type]
+        GetAttribute[Get Static Attribute]
+    end
+
+    HashData --> ClassMethods
+    HashData --> InstanceMethods
+    ArrayData --> ClassMethods
+    ClassMethods --> FindRecord
+    InstanceMethods --> TestRecord
+    AttributeHelpers --> GetAttribute
+
+    style HashData fill:#f3e5f5
+    style ClassMethods fill:#e3f2fd
+    style InstanceMethods fill:#e8f5e8
+```
+
+## Data Synchronization Process
+
+The synchronization process ensures database consistency with data files:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Model as AR Model
+    participant Parser as File Parser
+    participant DB as Database
+
+    App->>Model: sync_table_data!
+    Model->>Parser: Parse data files
+    Parser-->>Model: Canonical data
+
+    Model->>DB: BEGIN TRANSACTION
+    Model->>DB: Find existing records
+    DB-->>Model: Current records
+
+    loop For each record
+        Model->>Model: Compare attributes
+        alt Record changed
+            Model->>DB: UPDATE record
+        end
+    end
+
+    loop For new records
+        Model->>DB: INSERT record
+    end
+
+    Model->>DB: COMMIT TRANSACTION
+    Model-->>App: Changes summary
+```
+
+## File Format Support
+
+The gem supports multiple data file formats with a unified interface:
+
+```mermaid
+flowchart LR
+    subgraph "Input Formats"
+        YAML[YAML<br/>*.yml, *.yaml]
+        JSON[JSON<br/>*.json]
+        CSV[CSV<br/>*.csv]
+    end
+
+    subgraph "Parser Layer"
+        YAMLParser[YAML::safe_load]
+        JSONParser[JSON::parse]
+        CSVParser[CSV Parser<br/>with headers]
+    end
+
+    subgraph "Output Format"
+        Hash[Hash Structure<br/>Named instances]
+        Array[Array Structure<br/>Simple records]
+    end
+
+    YAML --> YAMLParser
+    JSON --> JSONParser
+    CSV --> CSVParser
+
+    YAMLParser --> Hash
+    YAMLParser --> Array
+    JSONParser --> Hash
+    JSONParser --> Array
+    CSVParser --> Array
+
+    style YAML fill:#e8f5e8
+    style JSON fill:#fff3e0
+    style CSV fill:#f3e5f5
+```
+
+## Dependency Resolution
+
+The gem automatically resolves dependencies between support table models:
+
+```mermaid
+flowchart TB
+    subgraph "Dependency Analysis"
+        Belongs[belongs_to Associations]
+        Explicit[Explicit Dependencies]
+        Through[has_many :through]
+    end
+
+    subgraph "Resolution Strategy"
+        Detect[Detect Dependencies]
+        Sort[Topological Sort]
+        Validate[Circular Detection]
+    end
+
+    subgraph "Load Order"
+        Level1[Independent Models]
+        Level2[Models with Dependencies]
+        Level3[Join Table Models]
+    end
+
+    Belongs --> Detect
+    Explicit --> Detect
+    Through --> Detect
+
+    Detect --> Sort
+    Sort --> Validate
+    Validate --> Level1
+    Level1 --> Level2
+    Level2 --> Level3
+
+    style Detect fill:#e3f2fd
+    style Sort fill:#f3e5f5
+    style Level1 fill:#e8f5e8
+```
+
+## Rails Integration
+
+The gem integrates seamlessly with Rails applications:
+
+```mermaid
+flowchart TD
+    subgraph "Rails Boot Process"
+        Boot[Application Boot]
+        Eager[Eager Loading]
+        Routes[Routes Loading]
+    end
+
+    subgraph "Gem Integration"
+        Railtie[SupportTableData::Railtie]
+        Tasks[Rake Tasks]
+        AutoLoad[Auto Discovery]
+    end
+
+    subgraph "Development Workflow"
+        Migrate[db:migrate]
+        Sync[support_table_data:sync]
+        Test[Test Suite Setup]
+    end
+
+    Boot --> Railtie
+    Eager --> AutoLoad
+    Railtie --> Tasks
+    Tasks --> Sync
+    Migrate --> Sync
+    Sync --> Test
+
+    style Railtie fill:#e3f2fd
+    style Sync fill:#e8f5e8
+    style Test fill:#fff3e0
+```
+
+## Error Handling and Validation
+
+The gem includes comprehensive error handling:
+
+```mermaid
+flowchart TD
+    subgraph "Validation Points"
+        FileFormat[File Format Validation]
+        DataStructure[Data Structure Validation]
+        MethodNames[Method Name Validation]
+        KeyAttributes[Key Attribute Validation]
+    end
+
+    subgraph "Error Types"
+        ParseError[File Parse Errors]
+        NameError[Method Name Conflicts]
+        DataError[Data Consistency Errors]
+        TransactionError[Database Transaction Errors]
+    end
+
+    subgraph "Recovery Strategies"
+        Rollback[Transaction Rollback]
+        ErrorReport[Detailed Error Messages]
+        PartialSync[Skip Invalid Records]
+    end
+
+    FileFormat --> ParseError
+    DataStructure --> DataError
+    MethodNames --> NameError
+    KeyAttributes --> DataError
+
+    ParseError --> ErrorReport
+    NameError --> ErrorReport
+    DataError --> Rollback
+    TransactionError --> Rollback
+
+    style ParseError fill:#ffebee
+    style Rollback fill:#e8f5e8
+    style ErrorReport fill:#fff3e0
+```
+
+## Performance Considerations
+
+The gem is designed for optimal performance with small datasets:
+
+```mermaid
+flowchart LR
+    subgraph "Optimization Strategies"
+        SmallData[Small Dataset Focus<br/>&lt; 100 records]
+        Memoization[Method Memoization]
+        Transaction[Atomic Transactions]
+        LazyLoad[Lazy Method Generation]
+    end
+
+    subgraph "Memory Management"
+        ClassVars[Class Variables]
+        Mutex[Thread Safety]
+        WeakRef[Weak References]
+    end
+
+    subgraph "Database Efficiency"
+        BulkOps[Bulk Operations]
+        IndexHints[Key Attribute Indexing]
+        MinQueries[Minimize Queries]
+    end
+
+    SmallData --> ClassVars
+    Memoization --> Mutex
+    Transaction --> BulkOps
+    LazyLoad --> WeakRef
+
+    ClassVars --> MinQueries
+    Mutex --> IndexHints
+    BulkOps --> MinQueries
+
+    style SmallData fill:#e8f5e8
+    style Transaction fill:#e3f2fd
+    style MinQueries fill:#fff3e0
+```
+
+## Extension Points
+
+The gem provides several extension points for customization:
+
+```mermaid
+flowchart TB
+    subgraph "Customization Options"
+        KeyAttr[Custom Key Attributes]
+        DataDir[Custom Data Directories]
+        Parser[Custom File Parsers]
+        Validation[Custom Validations]
+    end
+
+    subgraph "Integration Hooks"
+        BeforeSync[Before Sync Callbacks]
+        AfterSync[After Sync Callbacks]
+        MethodGen[Method Generation Hooks]
+        ErrorHook[Error Handling Hooks]
+    end
+
+    subgraph "External Gems"
+        Cache[SupportTableCache]
+        Observers[ActiveRecord Observers]
+        Auditing[Auditing Gems]
+    end
+
+    KeyAttr --> BeforeSync
+    DataDir --> MethodGen
+    Parser --> ErrorHook
+    Validation --> AfterSync
+
+    BeforeSync --> Cache
+    MethodGen --> Observers
+    ErrorHook --> Auditing
+
+    style Cache fill:#e3f2fd
+    style BeforeSync fill:#f3e5f5
+    style MethodGen fill:#e8f5e8
+```
+
+## Deployment Strategy
+
+The gem follows a deployment-friendly pattern:
+
+```mermaid
+flowchart LR
+    subgraph "Development"
+        DevData[Dev Data Files]
+        DevDB[Dev Database]
+        DevTest[Test Suite]
+    end
+
+    subgraph "CI/CD Pipeline"
+        Build[Build Process]
+        Migration[Run Migrations]
+        DataSync[Sync Support Data]
+        TestRun[Run Tests]
+    end
+
+    subgraph "Production"
+        ProdDB[Production Database]
+        ProdData[Production Data]
+        Monitor[Monitoring]
+    end
+
+    DevData --> Build
+    DevDB --> Migration
+    DevTest --> TestRun
+
+    Build --> Migration
+    Migration --> DataSync
+    DataSync --> TestRun
+    TestRun --> ProdDB
+
+    ProdDB --> ProdData
+    ProdData --> Monitor
+
+    style DataSync fill:#e8f5e8
+    style TestRun fill:#e3f2fd
+    style Monitor fill:#fff3e0
+```
+
+## Best Practices
+
+### Model Organization
+
+```mermaid
+flowchart TD
+    subgraph "File Structure"
+        Models[app/models/]
+        DataFiles[db/support_tables/]
+        Tests[spec/models/]
+    end
+
+    subgraph "Naming Conventions"
+        ModelFile[status.rb]
+        DataFile[statuses.yml]
+        TestFile[status_spec.rb]
+    end
+
+    subgraph "Content Organization"
+        Includes[Include SupportTableData]
+        Config[Configure Directories]
+        AddData[Add Data Files]
+        Helpers[Define Helpers]
+    end
+
+    Models --> ModelFile
+    DataFiles --> DataFile
+    Tests --> TestFile
+
+    ModelFile --> Includes
+    DataFile --> Config
+    TestFile --> AddData
+    Config --> Helpers
+
+    style ModelFile fill:#e3f2fd
+    style DataFile fill:#f3e5f5
+    style Includes fill:#e8f5e8
+```
+
+## Summary
+
+The SupportTableData gem provides a comprehensive solution for managing static support tables through:
+
+1. **Declarative Configuration**: Define support data in version-controlled files
+2. **Automatic Synchronization**: Keep database records in sync with data files
+3. **Generated Helper Methods**: Clean, readable code for accessing specific records
+4. **Dependency Management**: Automatic resolution of inter-table dependencies
+5. **Rails Integration**: Seamless integration with Rails applications and deployment workflows
+6. **Type Safety**: Compile-time method generation with runtime validation
+7. **Performance**: Optimized for small datasets with minimal overhead
+
+The architecture promotes maintainable code by keeping support data close to the application logic while ensuring data consistency across environments.
+
+<function_calls>
+<invoke name="get-syntax-docs-mermaid">
+<parameter name="file">flowchart.md

data/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.5.1
+
+### Added
+
+- YARD documentation tasks can now take an optional file path argument to add, verify, or remove documentation for a specific support table model instead of all models. For example, you can run `bundle exec rake support_table_data:yard_docs:add[app/models/color.rb]` to add documentation for the `Color` model.
+- Added comment in generated YARD documentation indicating the command to run to update them so that it's clear to users how to keep the documentation up to date.
+- Aliased `support_table_data:yard_docs` to `support_table_data:yard_docs:add` for convenience since adding the documentation is the most common action.
+
+## 1.5.0
+
+### Added
+
+- The default data directory in a Rails application can be set with the `config.support_table.data_directory` option in the Rails application configuration.
+- Added rake task `support_table_data:yard_docs:add` for Rails applications that will add YARD documentation to support table models for the named instance helpers. There is also a task `support_table_data:yard_docs:verify` that can be used in a build pipeline to verify that the documentation is up to date. You can also remove the documentation with the `support_table_data:yard_docs:remove` task.
+- The data synchronization task is now automatically attached to several Rails tasks: `db:seed`, `db:seed:replant`, `db:prepare`, `db:test:prepare`, `db:fixtures:load`. Support tables will be synced after running any of these tasks. This can be disabled by setting `config.support_table.auto_sync = false` in the Rails application configuration.
+
+### Changed
+
+- The default data directory is now set in a Railtie and can be overridden with the `config.support_table.data_directory` option in the Rails application configuration.
+- The `support_table_key_attribute` method now returns "id" if not explicitly set instead of implicitly interpreting `nil` as the primary key. This makes the behavior more consistent and explicit and avoids edge cases when running the code in environments where the database connection is not available. This is a breaking change if the table uses a primary key other than "id" and the `support_table_key_attribute` was not explicitly set to that primary key.
+
 ## 1.4.0
 
 ### Fixed

data/README.md

@@ -8,6 +8,19 @@ This gem provides a mixin for ActiveRecord support table models that allows you
 
 These kinds of models blur the line between data and code. You'll often end up with constants and application logic based on specific values that need to exist in the table. By using this gem, you can easily define methods for loading and comparing specific instances. This can give you cleaner code that reads far more naturally. You can also avoid defining dozens of constants or referencing magic values (i.e. no more hard-coded strings or ids in the code to look up specific records).
 
+## Table of Contents
+
+- [Usage](#usage)
+  - [Specifying Data Files](#specifying-data-files)
+  - [Named Instances](#named-instances)
+    - [Documenting Named Instance Helpers](#documenting-named-instance-helpers)
+  - [Caching](#caching)
+  - [Loading Data](#loading-data)
+  - [Testing](#testing)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Usage
 
 In the examples below, suppose we have a simple `Status` model in which each row has an id and a name, and the name can only have a handful of statuses: "Pending", "In Progress", and "Completed".
@@ -55,7 +68,9 @@ class Status < ApplicationRecord
 
 You cannot update the value of the key attribute in a record in the data file. If you do, a new record will be created and the existing record will be left unchanged.
 
-You can specify data files as relative paths. This can be done by setting the `SupportTableData.data_directory` value. You can override this value for a model by setting the `support_table_data_directory` attribute on its class. In a Rails application, `SupportTableData.data_directory` will be automatically set to `db/support_tables/`. Otherwise, relative file paths will be resolved from the current working directory. You must define the directory to load relative files from before loading your model classes.
+You can specify data files as relative paths. This can be done by setting the `SupportTableData.data_directory` value. You can override this value for a model by setting the `support_table_data_directory` attribute on its class. Otherwise, relative file paths will be resolved from the current working directory. You must define the directory to load relative files from before loading your model classes.
+
+In a Rails application, `SupportTableData.data_directory` will be automatically set to `db/support_tables/`. This can be overridden by setting the `config.support_table.data_directory` option in the Rails application configuration.
 
 **Note**: If you're using CSV files and Ruby 3.4 or higher, you'll need to include the `csv` gem in your Gemfile since it was removed from the standard library in Ruby 3.4.
 
@@ -109,7 +124,6 @@ Helper methods will not override already defined methods on a model class. If a
 
 You can also define helper methods for named instance attributes. These helper methods will return the hard coded values from the data file. Calling these methods does not require a database connection.
 
-
 ```ruby
 class Status < ApplicationRecord
   include SupportTableData
@@ -171,6 +185,21 @@ completed:
   group_name: done
 ```
 
+#### Documenting Named Instance Helpers
+
+In a Rails application, you can add YARD documentation for the named instance helpers by running the rake task `support_table_data:yard_docs`. This will add YARD comments to your model classes for each of the named instance helper methods defined on the model. Adding this documentation will help IDEs provide better code completion and inline documentation for the helper methods and expose the methods to AI agents.
+
+To update a single model file, pass an optional file path argument, for example: `bundle exec rake "support_table_data:yard_docs[app/models/status.rb]"`.
+
+The default behavior is to add the documentation comments at the end of the model class by reopening the class definition. If you prefer to have the documentation comments appear elsewhere in the file, you can add the following markers to your model class and the YARD documentation will be inserted between these markers.
+
+```ruby
+# Begin YARD docs for support_table_data
+# End YARD docs for support_table_data
+```
+
+A good practice is to add a check to your CI pipeline to ensure the documentation is always up to date. You can run the rake task `support_table_data:yard_docs:verify` to do this. It will exit with an error if any models do not have up to date documentation.
+
 ### Caching
 
 You can use the companion [support_table_cache gem](https://github.com/bdurand/support_table_cache) to add caching support to your models. That way your application won't need to constantly query the database for records that will never change.
@@ -198,6 +227,9 @@ class Thing < ApplicationRecord
 end
 ```
 
+> [!TIP]
+> The [support_table](https://github.com/bdurand/support_table) gem combines both gems in a drop in solution for Rails applications.
+
 ### Loading Data
 
 Calling `sync_table_data!` on your model class will synchronize the data in the database table with the values from the data files.
@@ -246,18 +278,33 @@ end
 
 If you use a method to set a `has_many` association on your model, you **must** set the `autosave` option to `true` on the association (see the above example). This will ensure the association records are always saved even if there were no changes to the parent record.
 
-You need to call `SupportTableData.sync_all!` when deploying your application. This gem includes a rake task `support_table_data:sync` that is suitable for hooking into deploy scripts. An easy way to hook it into a Rails application is by enhancing the `db:migrate` task so that the sync task runs immediately after database migrations are run. You can do this by adding code to a Rakefile in your application's `lib/tasks` directory:
+You will need to call `SupportTableData.sync_all!` when deploying your application or running your test suite. This gem includes a rake task `support_table_data:sync` that is suitable for hooking into deploy or CI scripts.
+
+This task is automatically run whenever you run any of these Rails tasks so if these are already part of your deploy or CI scripts, then no additional setup is required:
+
+- `db:seed`
+- `db:seed:replant`
+- `db:prepare`
+- `db:test:prepare`
+- `db:fixtures:load`
+
+You can disable these task enhancements by setting `config.support_table.auto_sync = false` in your Rails application configuration.
+
+> [!TIP]
+> If you also want to hook into the `db:migrate` task so that syncs are run immediately after database migrations, you can do this by adding code to a Rakefile in your application's `lib/tasks` directory. Migrations do funny things with the database connection especially when using multiple databases so you need to re-establish the connection before syncing the support table data.
 
 ```ruby
 if Rake::Task.task_defined?("db:migrate")
   Rake::Task["db:migrate"].enhance do
+    # The main database connection may have artifacts from the migration, so re-establish it
+    # to get a clean connection before syncing support table data.
+    ActiveRecord::Base.establish_connection
+
     Rake::Task["support_table_data:sync"].invoke
   end
 end
 ```
 
-Enhancing the `db:migrate` task also ensures that local development environments will stay up to date.
-
 ### Testing
 
 You must also call `SupportTableData.sync_all!` before running your test suite. This method should be called in the test suite setup code after any data in the test database has been purged and before any tests are run.

data/VERSION

@@ -1 +1 @@
-1.4.0
+1.5.1