familia 2.0.0.pre15 → 2.0.0.pre16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 00416beac08786c1fffd75a0c2578669c6a0d18169824ca1a23e9122018a386b
-  data.tar.gz: c38f7bfe985a7d6151abf2ce4b6d7ca32ddb97adf8d069880f7e919662937851
+  metadata.gz: ebaf394ebbccf9d096e87da84c693040c71d963860002a9d970d9b04edc11b6c
+  data.tar.gz: 4862991d1b2a1538876089030657986eb1b56f5551c7e5e9978a1009c77e86f9
 SHA512:
-  metadata.gz: a3d6a60c86460578567fbd6f33e96c8ae0ee2dbfc80f3ffc6f123dc6fb84c6020efd359601122e63543c0128401d235587e9770df8acbbfa1f55cb908a012e07
-  data.tar.gz: 5062f93d7494df05a6d62dade395a0522ca8ab02afd4fdc5a00ee21db08b05ace8c3227d07739ef7cdd727fa72888ea4ec415491eb60028b25166d107d574e8e
+  metadata.gz: 533af9a33a115e8a59c87ae35e5b82401e1d72edbe43fd4a2963a3ca25a2c1ac259e5aaf02e68945d9d2f576393c6f77e9843ec87c4ed92696ca41d0b06e4d4c
+  data.tar.gz: b74dca7e415cbd0d6933beb77185e7738d33b3c10a704569120892fa9062fe92874fe2b879439f8d9508b8d02ba0e8154c79cb1546b029ac9e6bbdde442fd5e1

data/.github/workflows/code-quality.yml

@@ -0,0 +1,138 @@
+name: Code Quality
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write  # Needed to post comments on PRs
+
+jobs:
+  reek:
+    name: Reek Code Analysis
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Configure Bundler for secure gem installation
+        run: |
+          bundle config set --local path 'vendor/bundle'
+          bundle config set --local deployment 'false'
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Run Reek analysis
+        run: |
+          echo "=== Running Reek code analysis ==="
+          echo "This analysis identifies code smells and potential improvements."
+          echo "Results are informational and won't fail the build."
+          echo ""
+
+          # Run reek and capture output (don't fail on warnings)
+          # Use success-exit-code to prevent failures from stopping the analysis
+          bundle exec reek --format=text --success-exit-code 0 --failure-exit-code 0 || true
+
+          echo ""
+          echo "=== Reek analysis complete ==="
+        continue-on-error: true  # Don't fail the build on code smells
+
+      - name: Generate Reek report (if analysis available)
+        run: |
+          echo "=== Generating detailed Reek report ==="
+
+          # Generate JSON report for potential future processing
+          bundle exec reek --format=json --success-exit-code 0 --failure-exit-code 0 > reek-report.json || true
+
+          # Display summary
+          if [ -s reek-report.json ]; then
+            echo "Reek JSON report generated: $(wc -l < reek-report.json) lines"
+            echo "Top code smell types found:"
+            jq -r '.[].smells[].smell_type' reek-report.json 2>/dev/null | sort | uniq -c | sort -rn | head -10 || echo "Unable to parse JSON report"
+          else
+            echo "No code smells detected or analysis failed"
+          fi
+        continue-on-error: true
+
+      - name: Upload Reek report as artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: reek-report
+          path: reek-report.json
+          retention-days: 30
+
+  # Add other code quality checks here
+  additional-quality-checks:
+    name: Additional Quality Checks
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Configure Bundler for secure gem installation
+        run: |
+          bundle config set --local path 'vendor/bundle'
+          bundle config set --local deployment 'false'
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Check for TODO/FIXME comments
+        run: |
+          echo "=== Scanning for TODO/FIXME comments ==="
+          echo "This helps track technical debt and action items."
+          echo ""
+
+          # Find TODO/FIXME comments (excluding this workflow file)
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            xargs grep -Hn -i -E "(TODO|FIXME|HACK|XXX|NOTE):" 2>/dev/null | \
+            head -20 || echo "No TODO/FIXME comments found"
+        continue-on-error: true
+
+      - name: Check Ruby file syntax
+        run: |
+          echo "=== Checking Ruby syntax ==="
+          echo "Validates that all Ruby files have correct syntax."
+          echo ""
+
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            while read -r file; do
+              if ! ruby -c "$file" > /dev/null 2>&1; then
+                echo "Syntax error in: $file"
+                ruby -c "$file"
+              fi
+            done
+        continue-on-error: true
+
+      - name: Check for long lines
+        run: |
+          echo "=== Checking for long lines (>120 characters) ==="
+          echo "Identifies potentially hard-to-read code lines."
+          echo ""
+
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            xargs grep -Hn "^.\{121,\}$" | \
+            head -10 || echo "No overly long lines found"
+        continue-on-error: true

data/.github/workflows/code-smellage.yml

@@ -0,0 +1,145 @@
+name: Any Code Smellage?
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write # Needed to post comments on PRs
+
+jobs:
+  reek:
+    name: Reek Code Analysis
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Configure Bundler for secure gem installation
+        run: |
+          bundle config set --local path 'vendor/bundle'
+          bundle config set --local deployment 'false'
+
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Run Reek analysis
+        run: |
+          echo "=== Running Reek code analysis ==="
+          echo "This analysis identifies code smells and potential improvements."
+          echo "Results are informational and won't fail the build."
+          echo ""
+
+          # Run reek and capture output (don't fail on warnings)
+          # Use success-exit-code to prevent failures from stopping the analysis
+          bundle exec reek --format=text --success-exit-code 0 --failure-exit-code 0 || true
+
+          echo ""
+          echo "=== Reek analysis complete ==="
+        continue-on-error: true # Don't fail the build on code smells
+
+      - name: Generate Reek report (if analysis available)
+        run: |
+          echo "=== Generating detailed Reek report ==="
+
+          # Generate JSON report for potential future processing
+          bundle exec reek --format=json --success-exit-code 0 --failure-exit-code 0 > reek-report.json || true
+
+          # If no JSON was generated, create an empty valid JSON array
+          if [ ! -s reek-report.json ]; then
+            echo "[]" > reek-report.json
+            echo "No code smells detected - created empty report"
+          else
+            echo "Reek JSON report generated: $(wc -l < reek-report.json) lines"
+            echo "Top code smell types found:"
+            jq -r '.[].smells[].smell_type' reek-report.json 2>/dev/null | sort | uniq -c | sort -rn | head -10 || echo "Unable to parse JSON report"
+          fi
+
+          # Also generate a human-readable HTML report for easier viewing
+          bundle exec reek --format=html --success-exit-code 0 --failure-exit-code 0 > reek-report.html || echo "<!-- No code smells detected -->" > reek-report.html
+        continue-on-error: true
+
+      - name: Upload Reek report as artifact
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: reek-report
+          path: |
+            reek-report.json
+            reek-report.html
+          if-no-files-found: ignore
+          retention-days: 30
+
+  # Add other code quality checks here
+  additional-quality-checks:
+    name: Additional Quality Checks
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Configure Bundler for secure gem installation
+        run: |
+          bundle config set --local path 'vendor/bundle'
+          bundle config set --local deployment 'false'
+
+      - name: Install dependencies
+        run: bundle install --jobs 4 --retry 3
+
+      - name: Check for TODO/FIXME comments
+        run: |
+          echo "=== Scanning for TODO/FIXME comments ==="
+          echo "This helps track technical debt and action items."
+          echo ""
+
+          # Find TODO/FIXME comments (excluding this workflow file)
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            xargs grep -Hn -i -E "(TODO|FIXME|HACK|XXX|NOTE):" 2>/dev/null | \
+            head -20 || echo "No TODO/FIXME comments found"
+        continue-on-error: true
+
+      - name: Check Ruby file syntax
+        run: |
+          echo "=== Checking Ruby syntax ==="
+          echo "Validates that all Ruby files have correct syntax."
+          echo ""
+
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            while read -r file; do
+              if ! ruby -c "$file" > /dev/null 2>&1; then
+                echo "Syntax error in: $file"
+                ruby -c "$file"
+              fi
+            done
+        continue-on-error: true
+
+      - name: Check for long lines
+        run: |
+          echo "=== Checking for long lines (>120 characters) ==="
+          echo "Identifies potentially hard-to-read code lines."
+          echo ""
+
+          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
+            xargs grep -Hn "^.\{121,\}$" | \
+            head -10 || echo "No overly long lines found"
+        continue-on-error: true

data/.github/workflows/docs.yml

@@ -1,3 +1,5 @@
+# .github/workflows/docs.yml
+---
 name: Build and Publish YARD Documentation
 
 on:
@@ -7,9 +9,14 @@ on:
   workflow_dispatch:
     inputs:
       reason:
-        description: 'Reason for manual documentation build'
+        description: "Reason for manual documentation build"
         required: false
-        default: 'Manual documentation update'
+        default: "Manual documentation update"
+      debug_enabled:
+        type: boolean
+        description: "Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)"
+        required: false
+        default: false
 
 permissions:
   contents: read
@@ -33,23 +40,39 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.4'
+          ruby-version: "3.4"
           bundler-cache: true
 
       - name: Install dependencies
         run: bundle install
 
+      - name: Setup tmate session
+        uses: mxschmitt/action-tmate@7b6a61a73bbb9793cb80ad69b8dd8ac19261834c # v3
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+        with:
+          detached: true
+
       - name: Build YARD documentation
         run: |
-          bundle exec yard doc --output-dir ./doc
-          # Ensure doc directory exists and create .nojekyll file to prevent GitHub Pages Jekyll processing
-          mkdir -p ./doc
-          touch ./doc/.nojekyll
+          # Generate docs with maximum volume
+          bundle exec yard doc --debug --backtrace 2>&1 | tee yard_debug.log
+
+          # Display the last 10 lines of the log file
+          tail -n 10 yard_debug.log
+
+          # Search for specific error messages in the log file
+          grep -A 5 -B 5 "Exception occurred" yard_debug.log || echo "No exceptions found (good!)"
+          grep -A 5 -B 5 "Cannot resolve link" yard_debug.log || echo "No unresolved links found (good!)"
+
+          # Ensure public directory exists and create .nojekyll file to
+          # prevent GitHub Pages Jekyll processing
+          mkdir -p ./public
+          touch ./public/.nojekyll
 
       - name: Upload documentation artifacts
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./doc
+          path: ./public
 
   deploy:
     environment:

data/.gitignore

@@ -19,7 +19,7 @@ log
 tmp
 vendor
 *.gem
-doc/
+public/
 
 # Ignore WIP or temp dev files with uppercase names
 [A-Z]*.md

data/.pre-commit-config.yaml

@@ -50,7 +50,6 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: check-yaml
-      - id: detect-private-key
       - id: mixed-line-ending
       - id: check-added-large-files
         args: ["--maxkb=1000"]
@@ -59,6 +58,13 @@ repos:
       - id: check-merge-conflict
       - id: forbid-submodules
 
+  - repo: https://github.com/thoughtworks/talisman
+    rev: v1.32.2
+    hooks:
+      - id: talisman-commit
+        env:
+          TALISMAN_SCAN_MODE: CI
+
   - repo: https://github.com/avilaton/add-msg-issue-prefix-hook
     rev: v0.0.11
     hooks:

data/.reek.yml

@@ -0,0 +1,98 @@
+# .reek.yml
+# Reek configuration for Familia
+#
+# Basic commands:
+#   bundle exec reek                           # Analyze all Ruby files
+#   bundle exec reek lib/                      # Analyze specific directory
+#   bundle exec reek lib/familia/horreum.rb    # Analyze specific file
+#   bundle exec reek --help                    # Show all options
+#   bundle exec reek --docs                    # Open documentation
+#
+# Advanced usage:
+#   bundle exec reek --format=html > report.html     # Generate HTML report
+#   bundle exec reek --format=json                   # JSON output for CI
+#   bundle exec reek --config .reek.yml              # Use specific config
+#   bundle exec reek --show-docs IrresponsibleModule # Explain specific smell
+#   bundle exec reek --failure-exit-code 1           # Exit with error on smells (for CI)
+
+---
+detectors:
+  # Disable some detectors for initial adoption
+  # You can gradually enable these as you clean up the codebase
+
+  # Class/Module Structure
+  IrresponsibleModule:
+    enabled: false # Modules without documentation - start with this disabled
+
+  # Method Complexity
+  TooManyStatements:
+    enabled: true
+    max_statements: 15 # Default is 5, relaxed for initial adoption
+
+  TooManyMethods:
+    enabled: true
+    max_methods: 25 # Default is 15, relaxed for ORMs which often have many methods
+
+  LongParameterList:
+    enabled: true
+    max_params: 4 # Default is 3, slightly relaxed
+
+  # Data Classes and Feature Envy
+  DataClump:
+    enabled: true
+
+  FeatureEnvy:
+    enabled: true
+
+  # Control Structure
+  NestedIterators:
+    enabled: true
+    max_allowed_nesting: 2 # Default is 1, relaxed for data processing
+
+  # Variable and Constant Usage
+  UnusedParameters:
+    enabled: true
+
+  InstanceVariableAssumption:
+    enabled: true
+
+  # Naming
+  UncommunicativeParameterName:
+    enabled: true
+    reject:
+      - '/^.$/' # Single letter names
+      - '/[0-9]$/' # Names ending in numbers
+      - '/^_/' # Names starting with underscore (common Ruby pattern)
+    accept: []
+
+  UncommunicativeVariableName:
+    enabled: true
+    reject:
+      - '/^.$/' # Single letter names
+      - '/[0-9]$/' # Names ending in numbers
+    accept:
+      - e # Exception variable
+      - id # Common identifier
+      - db # Database connection
+      - op # Operation
+      - io # Input/output
+
+  UncommunicativeMethodName:
+    enabled: true
+    reject:
+      - '/^.$/' # Single letter method names
+      - '/[0-9]$/' # Methods ending in numbers
+    accept:
+      - "<<" # Common Ruby operator overload
+
+# Directory and file exclusions
+exclude_paths:
+  - "vendor/**/*.rb"
+  - "tmp/**/*.rb"
+  - "try/**/*.rb" # Test files using tryouts framework
+  - "examples/**/*.rb" # Example code files
+  - "bin/*" # Executable scripts
+  - "*.gemspec" # Gem specification files
+
+# Note: For limiting warnings output, use CLI: bundle exec reek | head -50
+# Note: For failure exit codes, use CLI: bundle exec reek --failure-exit-code 1

data/.rubocop.yml

@@ -16,7 +16,6 @@
 # How to resolve "RuboCop version incompatibility found":
 #  `rubocop --stop-server`
 #
-inherit_from: .rubocop_todo.yml
 
 plugins:
   - rubocop-performance
@@ -28,11 +27,9 @@ AllCops:
   MaxFilesInCache: 100
   TargetRubyVersion: 3.4
   Exclude:
-    - "migrate/**/*.rb"
-    - "migrate/*.rb"
-    - "try/**/*"
-    - "try/*.rb"
-    - "vendor/**/*"
+    - "rspec/**/*.rb"
+    - "tmp/**/*.rb"
+    - "try/**/*.rb"
 
 #
 # Trailing commas
@@ -46,6 +43,7 @@ Style/TrailingCommaInArrayLiteral:
 
 Style/TrailingCommaInArguments:
   Enabled: true
+  EnforcedStyleForMultiline: comma
 
 Style/TrailingCommaInBlockArgs:
   Enabled: true
@@ -62,30 +60,59 @@ Gemspec/DevelopmentDependencies:
 Layout/HashAlignment:
   Enabled: false
 
+# Format with consistent indentation levels rather than vertical dot alignment.
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+  EnforcedStyle: indented
+  IndentationWidth: 2
+
+Layout/IndentationWidth:
+  Width: 2
+
+Layout/ArgumentAlignment:
+  Enabled: false
+
+Layout/DotPosition:
+  EnforcedStyle: leading # or 'trailing'
+
 Lint/Void:
   Enabled: false
 
+Layout/MultilineAssignmentLayout:
+  Enabled: true
+  EnforcedStyle: same_line
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
 Metrics/AbcSize:
   Enabled: false
   Max: 20
 
 Metrics/ClassLength:
   Enabled: true
-  Max: 200
+  Max: 350
 
 Metrics/CyclomaticComplexity:
   Enabled: false
 
 Metrics/MethodLength:
   Enabled: true
-  Max: 40
+  Max: 50
   CountAsOne: ["method_call"]
 
 Metrics/ModuleLength:
   Enabled: true
-  Max: 250
+  Max: 350
   CountAsOne: ["method_call"]
 
+Metrics/ParameterLists:
+  Enabled: true
+  Max: 6
+
 Performance/Size:
   Enabled: true
   Exclude:
@@ -97,8 +124,19 @@ Style/NegatedIfElseCondition:
 Naming/AsciiIdentifiers:
   Enabled: false
 
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
 Style/FrozenStringLiteralComment:
-  Enabled: false
+  Enabled: true
+  EnforcedStyle: never
 
 Naming/MemoizedInstanceVariableName:
   Enabled: false
+
+ThreadSafety/ClassInstanceVariable:
+  Enabled: false
+
+ThreadSafety/MutableClassInstanceVariable:
+  Enabled: false

data/.talismanrc

@@ -0,0 +1,9 @@
+# .talismanrc
+#
+# @see:
+# https://thoughtworks.github.io/talisman/docs/configuring-talisman/ignoring/
+# https://thoughtworks.github.io/talisman/docs/configuring-talisman/severity-threshold/
+#
+threshold: medium
+fileignoreconfig: []
+version: ""

data/.yardopts

@@ -1,30 +1,35 @@
 --readme README.md
 --title "Familia Ruby Library Documentation"
---markup markdown
---markup-provider kramdown
 --protected
 --no-private
+--verbose
+--charset utf-8
+--markup markdown
+--markup-provider redcarpet
+--output-dir public
 --embed-mixin ClassMethods
+--embed-mixin InstanceMethods
 --embed-mixin Features
 --tag feature:"Feature"
 --tag since:"Since Version"
---tag example:"Example Usage"
 --tag note:"Note"
 --tag warning:"Warning"
 --tag deprecated:"Deprecated"
+--tag abstract:"Abstract"
+--tag security:"Security"
 --hide-tag nodoc
 --exclude lib/familia/version.rb
+--readme README.md
+--no-stats
+--no-save
+--no-cache
 lib/**/*.rb
 -
-CHANGELOG.md
+README.md
+CHANGELOG.rst
 LICENSE.txt
-docs/guides/Home.md
-docs/guides/Getting-Started.md
-docs/guides/Feature-System-Guide.md
-docs/guides/Relationships-Guide.md
-docs/guides/relationships-methods.md
-docs/guides/Encrypted-Fields-Overview.md
-docs/guides/Connection-Pooling-Guide.md
-docs/reference/api-technical.md
-docs/migration/*.md
+docs/guides/*
+docs/reference/*
+docs/migrating/*.md
+docs/overview.md
 examples/*.rb