Skip to content

CLAUDE.md

Latest commit

 

History

History
66 lines (49 loc) · 3.15 KB

CLAUDE.md

File metadata and controls

66 lines (49 loc) · 3.15 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

  • Run tests: bundle exec rake spec or bundle exec rspec
  • Run linting: bundle exec rubocop
  • Run both tests and linting: bundle exec rake (default task)
  • Auto-fix linting issues: bundle exec rubocop -A
  • Install dependencies: bundle install
  • Run specific test: bundle exec rspec spec/path/to/specific_spec.rb
  • Run test with focus: bundle exec rspec --tag focus (for tests marked with focus: true)

Architecture Overview

ContextualConfig is a Ruby gem for context-aware configuration management built around three core architectural layers:

1. Core Concerns (lib/contextual_config/concern/)

  • Configurable: Provides validations, scopes, and basic configuration functionality. Expects database columns: key, config_data (jsonb), scoping_rules (jsonb), priority (integer), deleted_at (datetime)
  • Lookupable: Handles configuration lookup logic with find_applicable_config(key:, context:) and find_all_applicable_configs(context:)
  • SchemaDrivenValidation: Optional JSON schema validation for config_data and scoping_rules

2. Matching Engine (lib/contextual_config/services/)

  • ContextualMatcher: Core matching logic that evaluates scoping rules against context
  • Uses specificity scoring (more specific rules win) and priority ordering (lower numbers = higher priority)
  • Special handling for timing rules with date range evaluation
  • Supports extensible rule types through private methods like evaluate_timing_rule

3. Configuration Management

  • Configuration: Global gem settings for caching, logging, timing evaluation
  • ModuleRegistry: Allows modules to register custom configurations and model classes
  • Generators: Rails generator for creating configuration tables with proper indexes

Key Design Patterns

  • Context-driven matching: Configurations match based on runtime context hash
  • Priority + Specificity resolution: More specific rules beat less specific, higher priority (lower number) wins ties
  • JSONB-based flexibility: Both config data and scoping rules stored as JSONB for schema flexibility
  • Concerns-based modularity: Mix and match functionality via ActiveSupport::Concern modules
  • Service-based matching: Centralized matching logic in ContextualMatcher service

Database Schema Expectations

Models using these concerns should have:

t.string :key, null: false
t.jsonb :config_data, null: false, default: {}
t.jsonb :scoping_rules, null: false, default: {}
t.integer :priority, null: false, default: 100
t.datetime :deleted_at
t.text :description
t.string :type # For STI if needed

Testing Strategy

  • In-memory SQLite database for fast test runs (95 passing tests)
  • Concerns tested independently and through integration tests
  • Database cleaned between each test run
  • RSpec configuration in spec/spec_helper.rb sets up test schema and database
  • JSON serialization used for SQLite compatibility (instead of JSONB)
  • Comprehensive test coverage for matching logic, caching, logging, and validation