rhales 0.4.0 → 0.5.3

data/.rubocop.yml

@@ -0,0 +1,428 @@
+# .rubocop.yml
+#
+# This is the RuboCop configuration file.
+# It contains the rules and settings for the RuboCop linter.
+#
+# Enable/disable the cops individually. For more information,
+# refer to the RuboCop documentation:
+# https://docs.rubocop.org/rubocop/cops.html
+
+plugins:
+  - rubocop-thread_safety
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  DisabledByDefault: false # flip to true for a good autocorrect time
+  UseCache: true
+  MaxFilesInCache: 1000
+  TargetRubyVersion: 3.4
+  Exclude:
+    - 'bin/bundle'
+    - 'node_modules/**/*'
+    - 'tmp/**/*'
+    - 'vendor/**/*'
+
+RSpec/MultipleExpectations:
+  Enabled: true
+  Max: 5
+
+RSpec/ExampleLength:
+  Enabled: true
+  Max: 10
+
+Layout/CaseIndentation:
+  Enabled: true
+  EnforcedStyle: end # case, end
+  IndentOneStep: false
+  IndentationWidth: 2
+
+Layout/CommentIndentation:
+  Enabled: true
+
+Layout/MultilineMethodCallBraceLayout:
+  Enabled: true
+  EnforcedStyle: new_line # symmetrical, new_line, same_line
+
+Layout/TrailingWhitespace:
+  Enabled: true
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  Enabled: true
+
+Layout/SpaceAroundOperators:
+  Enabled: false
+
+# Use parentheses around a logical expression if it makes easier to read.
+Style/RedundantParentheses:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  Enabled: true
+
+Lint/UselessAssignment:
+  Enabled: true
+
+Lint/DuplicateBranch:
+  Enabled: true
+  IgnoreLiteralBranches: false
+  IgnoreConstantBranches: false
+  IgnoreDuplicateElseBranch: false
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 20
+
+# Offense count: 186
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: true
+  EnforcedStyle: explicit
+
+# When true: Use match? instead of =~ when MatchData is not used. True is preferred but not for autocorrection. Regexs are too picky. Need to manually check every time.
+Performance/RegexpMatch:
+  Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+# The Style/DoubleNegation cop is disabled because double negation provides
+# a concise, idiomatic way to convert values to boolean in Ruby. Alternative
+# approaches like ternary expressions or comparison with nil create unnecessary
+# verbosity without adding clarity. In cases where boolean coercion is the
+# explicit intent, !! clearly communicates this purpose to other Ruby developers.
+Style/DoubleNegation:
+  Enabled: false
+
+# Offense count: non-0
+Style/FormatString:
+  EnforcedStyle: format
+  Enabled: true
+
+Style/FormatStringToken:
+  EnforcedStyle: unannotated
+  Enabled: true
+
+Style/RedundantReturn:
+  Enabled: true
+  AllowMultipleReturnValues: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+# We prefer `extend self` and `class << self`.
+Style/ModuleFunction:
+  Enabled: true
+  AutoCorrect: false
+  EnforcedStyle: extend_self
+
+Style/SymbolArray:
+  EnforcedStyle: brackets
+  Enabled: true
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+
+Style/BlockDelimiters:
+  Enabled: true
+
+Naming/PredicateMethod:
+  Enabled: true
+  Mode: 'conservative'
+  AllowedMethods:
+    - validate!
+    - migrate
+
+# We use class instance variables quite a bit, mostly for readonly values set
+# at boot time. Except for our models with have redis-rb Redis instances
+# connected on their associated db via ModelClass.redis. We're well aware
+# so keeping this disabled reduces warning noise.
+ThreadSafety/ClassInstanceVariable:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: true
+  PreferredName: ex # Default is 'e'
+
+Naming/PredicatePrefix:
+  Enabled: true
+  ForbiddenPrefixes: [is_, has_, have_]
+  AllowedMethods: [
+      has_passphrase?, # correlates with the REST API field `has_passphrase`
+    ]
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+  IndentationWidth: 2
+
+Gemspec/DeprecatedAttributeAssignment:
+  Enabled: true
+
+Gemspec/DevelopmentDependencies:
+  Enabled: true
+
+Layout/ElseAlignment:
+  Enabled: false
+
+Layout/EndAlignment:
+  Enabled: false
+  # Severity: low
+  # SupportedStylesAlignWith: 2
+  # Leave commented out. When we set align with, endless "error occurred"
+  # EnforcedStyle: keyword # keyword, variable, start_of_line
+
+## vvvvvv Causing ruby-lsp errors in zed ? (July 8)
+##
+# Prefer 3 line if/else over one-liner
+Style/GuardClause:
+  Enabled: false
+  MinBodyLength: 3
+  AllowConsecutiveConditionals: false
+
+Layout/ExtraSpacing:
+  Enabled: false
+  AllowForAlignment: true
+  AllowBeforeTrailingComments: true
+  ForceEqualSignAlignment: true
+## ^^^^^^
+
+
+Layout/IndentationConsistency:
+  EnforcedStyle: indented_internal_methods
+  Enabled: true
+
+Layout/IndentationWidth:
+  # We don't want to enforce indentation width because it's doing weird things
+  # with if/else statements that capture values. The `if` expression is aligned
+  # with the right side of the `test` but the `else` expression is aligned with
+  # the start of the line.
+  Width: 2
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: true
+
+Layout/FirstHashElementIndentation:
+  Enabled: true
+
+Lint/Void:
+  Enabled: true
+
+Lint/CopDirectiveSyntax:
+  Enabled: true
+
+# Offense count: 122
+# Assignment Branch Condition size
+Metrics/AbcSize:
+  Enabled: false
+  Max: 20
+
+# Offense count: 217
+Layout/LineLength:
+  Enabled: false
+  AllowHeredoc: true
+  AllowURI: true
+  URISchemes:
+    - https
+  IgnoreCopDirectives: true
+  AllowedPatterns: []
+  SplitStrings: false
+  Max: 100
+
+# Align the arguments of a method call if they span more than one line.
+Layout/ArgumentAlignment:
+  Enabled: true
+  EnforcedStyle: with_fixed_indentation # with_first_argument, with_fixed_indentation
+  IndentationWidth: 2
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: true
+
+Layout/EmptyLineBetweenDefs:
+  Enabled: true
+
+Layout/EmptyLines:
+  Enabled: true
+
+Layout/EmptyLinesAroundAccessModifier:
+  Enabled: true
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: true
+
+Layout/EmptyLinesAroundClassBody:
+  Enabled: true
+
+Layout/EmptyLinesAroundExceptionHandlingKeywords:
+  Enabled: true
+
+Layout/EmptyLinesAroundMethodBody:
+  Enabled: true
+
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: true
+
+Metrics/ClassLength:
+  Enabled: true
+  Max: 350
+
+# Offense count: non-0
+Metrics/MethodLength:
+  Enabled: true
+  Max: 50
+  CountAsOne: ['method_call']
+
+Metrics/ModuleLength:
+  Enabled: true
+  Max: 350
+  CountAsOne: ['method_call']
+
+Performance/Size:
+  Enabled: true
+  Exclude: []
+
+Naming/AsciiIdentifiers:
+  Enabled: true
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Style/NegatedIfElseCondition:
+  Enabled: true
+
+Style/TrailingCommaInArguments:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: true
+  EnforcedStyleForMultiline: comma
+
+# Use #empty? when testing for objects of length 0.
+Style/ZeroLengthPredicate:
+  Enabled: true
+  Safe: true
+
+Style/MethodDefParentheses:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: never
+
+Style/SuperArguments:
+  Enabled: true
+
+# Offense count: non-0
+ThreadSafety/ClassAndModuleAttributes:
+  Description: Avoid mutating class and module attributes.
+  Enabled: true
+  ActiveSupportClassAttributeAllowed: false
+
+ThreadSafety/DirChdir:
+  Description: Avoid using `Dir.chdir` due to its process-wide effect.
+  Enabled: true
+  AllowCallWithBlock: false
+
+# Do not assign mutable objects to class instance variables.
+ThreadSafety/MutableClassInstanceVariable:
+  Description:
+  Enabled: true
+  EnforcedStyle: literals # one of literals, strict
+  SafeAutoCorrect: false
+
+# Avoid starting new threads. Let a framework like Sidekiq handle the threads.
+ThreadSafety/NewThread:
+  Enabled: true
+
+# Avoid instance variables in Rack middleware.
+ThreadSafety/RackMiddlewareInstanceVariable:
+  Description:
+  Enabled: true
+  Include:
+    - lib/middleware/*.rb
+
+# Unsafe autocorrect:
+Performance/MapCompact:
+  Enabled: false
+Performance/StringInclude:
+  Enabled: false
+Style/ClassAndModuleChildren:
+  Enabled: false
+Style/GlobalStdStream:
+  Enabled: false
+Style/HashConversion:
+  Enabled: false
+Style/HashEachMethods:
+  Enabled: false
+Style/IdenticalConditionalBranches:
+  Enabled: false
+Style/MinMaxComparison:
+  Enabled: false
+Style/MutableConstant:
+  Enabled: false
+Style/NumericPredicate:
+  Enabled: false
+Style/RaiseArgs:
+  Enabled: false
+Style/RedundantInterpolation:
+  Enabled: false
+Style/SafeNavigation:
+  Enabled: false
+Style/SpecialGlobalVars:
+  Enabled: false
+Style/StringConcatenation:
+  Enabled: false
+Style/SymbolProc:
+  Enabled: false
+
+# warnings
+Lint/RedundantCopDisableDirective:
+  Enabled: false
+Lint/AssignmentInCondition:
+  Enabled: false
+
+# Manual corrections
+Metrics/BlockLength:
+  Enabled: false
+Metrics/BlockNesting:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false
+Naming/AccessorMethodName:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+Performance/CollectionLiteralInLoop:
+  Enabled: false
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+# warnings
+Lint/DuplicateMethods:
+  Enabled: false
+Lint/UselessOr:
+  Enabled: false
+Lint/UnreachableLoop:
+  Enabled: false
+Lint/MissingCopEnableDirective:
+  Enabled: false
+Lint/MissingSuper:
+  Enabled: false
+Lint/EmptyFile:
+  Enabled: false
+Lint/RescueException:
+  Enabled: false

data/.serena/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+/cache

data/.yardopts

@@ -0,0 +1,56 @@
+# YARD Documentation Configuration
+# Systematic parameter specification for comprehensive API documentation generation
+
+# Access level configuration: Include protected and private methods for complete API coverage
+--protected
+--private
+
+# Markup processing configuration
+--markup markdown
+--markup-provider kramdown
+
+# Output directory specification
+--output-dir doc
+
+# Primary documentation entry point
+--readme README.md
+
+# Supplementary documentation files
+--files CHANGELOG.md,LICENSE.txt
+
+# Path exclusion patterns: Remove non-library code from documentation scope
+--exclude spec/**/*
+--exclude demo/**/*
+--exclude examples/**/*
+--exclude apps/**/*
+--exclude test/**/*
+--exclude tmp/**/*
+
+# Source file inclusion patterns: Target library implementation files
+lib/**/*.rb
+
+# Template specification for comprehensive documentation structure
+--template default
+
+# Additional processing directives
+--verbose
+
+# Documentation metadata
+--title "Rhales - Server-rendered Components with Client-side Hydration"
+
+# Tag processing configuration
+--tag param:"Parameters"
+--tag option:"Options"
+--tag return:"Returns"
+--tag raise:"Raises"
+--tag example:"Example Usage"
+--tag since:"Since"
+--tag todo:"TODO"
+--tag deprecated:"Deprecated"
+--tag api:"API"
+--tag internal:"Internal Use"
+
+# Additional files for processing
+-
+README.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- **Production Logging**: Structured logging via `Rhales.logger=` for security auditing and debugging
+  - View rendering events with template details, timing, and hydration size
+  - Schema validation warnings for production debugging (missing/extra keys)
+  - Error logging with line numbers and section context
+  - Security events: unescaped variable warnings, CSP nonce generation
+  - Performance logging: template compilation, cache behavior, partial resolution
+- Window collision detection prevents silent data overwrites when multiple templates use the same window attribute
+- Explicit merge strategies (shallow, deep, strict) for controlled data sharing between templates
+- `HydrationCollisionError` with detailed error messages showing file paths and line numbers
+- `HydrationRegistry` for thread-safe tracking of window attributes per request
+- `merge_strategy` method on RueDocument to extract merge attribute from data elements
+- JavaScript merge functions for client-side data composition
+- Comprehensive test coverage for collision detection and merge strategies
+
+### Changed
+- Replaced `json-schema` gem with `json_schemer` for better JSON Schema Draft 2020-12 support
+- Improved validation error messages with more structured output from json_schemer
+- Validation performance improved to <0.05ms average (was ~2ms with json-schema)
+
+### Security
+- Window collision detection prevents accidental data exposure by making overwrites explicit
+- All merge operations happen client-side after server-side interpolation and JSON serialization
+- Request-scoped registry prevents cross-request data leakage
+
+## [0.1.0] - 2024-01-XX
+
+### Added
+- Initial release of Rhales
+- Ruby Single File Components (.rue files) with server-side rendering
+- Client-side data hydration with secure JSON injection
+- Handlebars-style template syntax
+- Pluggable authentication adapters
+- Framework-agnostic design with Rails and Roda examples
+- Comprehensive test suite

data/CLAUDE.md

@@ -77,7 +77,7 @@ For complex features requiring parallel work:
 
 ### Key Patterns
 - **Template Syntax**: Uses Handlebars-style syntax (e.g., `{{variable}}`, `{{#if condition}}...{{/if}}`, `{{> partial_name}}`)
-- **Data Hydration**: Uses a `<data>` block in `.rue` files to define a JSON object for client-side hydration, which supports variable interpolation
+- **Data Hydration**: Uses a `<schema>` block in `.rue` files to define a zod v4 schema in plain Javascript for client-side hydration
 - **Security**: Default HTML escaping, CSP nonce support for scripts, and CSRF token handling are built-in
 - **Configuration**: All configuration is handled via an injected `Configuration` object, avoiding global state
 

data/Gemfile

@@ -0,0 +1,29 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rhales.gemspec
+gemspec
+
+group :development, :test do
+  gem 'benchmark'
+  gem 'rack-test'
+  gem 'reek', '~> 6.5'
+  gem 'rspec', '~> 3.12'
+  gem 'simplecov', '~> 0.22'
+end
+
+group :development do
+  gem 'benchmark-ips', '~> 2.0'
+  gem 'bundler', '~> 2.0'
+  gem 'debug'
+  gem 'kramdown', '~> 2.0' # Required for YARD markdown processing
+  gem 'rack', '>= 3.2', '< 4.0'
+  gem 'rack-proxy', require: false
+  gem 'rake', '~> 13.0'
+  gem 'rubocop', '1.81'
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'rubocop-thread_safety', require: false
+  gem 'stackprof', require: false
+  gem 'syntax_tree', require: false
+  gem 'yard', '~> 0.9'
+end