better_translate 1.0.0.1 → 1.1.1

data/SECURITY.md

@@ -0,0 +1,160 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities. Currently supported versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.1.x   | :white_check_mark: |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Security Measures
+
+BetterTranslate implements multiple security measures to protect your data and application:
+
+### 🔒 Static Security Analysis
+- **Brakeman**: Automated security scanner running on every commit
+- Checks for 76+ security vulnerabilities including:
+  - SQL Injection
+  - Cross-Site Scripting (XSS)
+  - Command Injection
+  - File Access vulnerabilities
+  - Unsafe Deserialization
+  - Mass Assignment issues
+
+### 🛡️ Dependency Security
+- **Bundler Audit**: Regular checks for vulnerable dependencies
+- Automated dependency updates via Dependabot (if configured)
+- Minimal runtime dependencies (only Faraday)
+
+### 🔐 API Key Protection
+- API keys are never logged or stored in code
+- VCR cassettes automatically anonymize API keys
+- `.env` files are git-ignored by default
+- Comprehensive validation prevents key exposure
+
+### ✅ Code Quality
+- **RuboCop**: Style and security linting
+- **Steep**: Static type checking
+- 93%+ test coverage with comprehensive test suite
+- Type-safe configuration with validation
+
+## Reporting a Vulnerability
+
+We take security seriously. If you discover a security vulnerability, please follow these steps:
+
+### 🚨 **DO NOT** disclose the vulnerability publicly
+
+Please report security vulnerabilities privately to protect users.
+
+### 📧 How to Report
+
+**Email**: alessio.bussolari@pandev.it
+
+**Subject**: `[SECURITY] BetterTranslate Vulnerability Report`
+
+**Include in your report**:
+1. **Description** of the vulnerability
+2. **Steps to reproduce** the issue
+3. **Potential impact** and attack scenarios
+4. **Suggested fix** (if you have one)
+5. **Your contact information** for follow-up
+
+### ⏱️ Response Timeline
+
+- **Initial Response**: Within 48 hours
+- **Status Update**: Within 7 days
+- **Fix Timeline**: Depending on severity
+  - Critical: 24-48 hours
+  - High: 7 days
+  - Medium: 30 days
+  - Low: 90 days
+
+### 🎁 Recognition
+
+We appreciate security researchers who responsibly disclose vulnerabilities:
+
+- Your name will be credited in our CHANGELOG (unless you prefer to remain anonymous)
+- We may offer a "Hall of Fame" mention in this file
+- Significant findings may be eligible for acknowledgment in release notes
+
+## Security Best Practices
+
+When using BetterTranslate:
+
+### ✅ Recommended Practices
+
+1. **API Keys**:
+   - Store API keys in environment variables
+   - Use `.env` files (never commit them)
+   - Rotate keys regularly
+   - Use separate keys for dev/staging/production
+
+2. **Configuration**:
+   - Validate all configuration before use
+   - Use `config.validate!` explicitly
+   - Review exclusion lists for sensitive data
+   - Enable dry_run mode for testing
+
+3. **File Permissions**:
+   - Restrict access to locale files
+   - Review backup files (`.bak`) security
+   - Use appropriate file permissions (644 for files, 755 for directories)
+
+4. **Dependencies**:
+   - Run `bundle audit` regularly
+   - Keep gems updated
+   - Review CHANGELOG for security updates
+
+### ❌ Avoid These Mistakes
+
+1. **DO NOT** hardcode API keys in source code
+2. **DO NOT** commit `.env` files to version control
+3. **DO NOT** expose translation API keys in client-side code
+4. **DO NOT** disable SSL verification in production
+5. **DO NOT** ignore Brakeman or RuboCop security warnings
+
+## Security Scanning
+
+### Run Security Checks Locally
+
+```bash
+# Run Brakeman security scanner
+bundle exec rake brakeman
+
+# Check for vulnerable dependencies
+bundle exec bundler-audit check --update
+
+# Run full test suite with security checks
+bundle exec rake  # includes spec, rubocop, steep, brakeman
+```
+
+### Continuous Integration
+
+Our CI pipeline automatically runs:
+- Brakeman security scanner
+- RuboCop with security cops
+- Steep type checking
+- Comprehensive test suite (541 tests)
+- Code coverage analysis (93%+)
+
+## Additional Resources
+
+- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
+- [Ruby Security](https://ruby-lang.org/en/security/)
+- [Brakeman Documentation](https://brakemanscanner.org/docs/)
+- [Bundler Audit](https://github.com/rubysec/bundler-audit)
+
+## Security Hall of Fame
+
+Thank you to these security researchers who helped improve BetterTranslate:
+
+<!-- Future contributors will be listed here -->
+_No vulnerabilities reported yet._
+
+---
+
+**Last Updated**: 2025-10-23
+**Contact**: alessio.bussolari@pandev.it

data/Steepfile

@@ -19,7 +19,6 @@ target :lib do
   library "pathname"
   library "monitor"
   library "logger"
-  library "set"
   library "json"
   library "yaml"
   library "securerandom"

data/brakeman.yml

@@ -0,0 +1,37 @@
+# Brakeman configuration file
+# https://brakemanscanner.org/docs/options/
+
+# Set application path (defaults to current directory)
+:app_path: "."
+
+# Set Rails version (detected automatically)
+# :rails_version: "8.1.0"
+
+# Enable additional security checks
+:force_scan: true
+
+# Show all files processed
+:report_progress: true
+
+# Skip certain checks (none skipped by default)
+:skip_checks: []
+
+# Only run specific checks (empty means run all)
+:run_checks: []
+
+# Set confidence levels to report (1=High, 2=Medium, 3=Weak)
+:min_confidence: 2
+
+# Ignore specific warnings
+:ignore_file: ".brakeman.ignore"
+
+# Additional paths to scan
+:additional_checks_path: []
+
+# Paths to exclude from scanning
+:skip_files:
+  - "spec/"
+  - "test/"
+
+# Exit with error code if warnings found
+:exit_on_warn: true

data/codecov.yml

@@ -0,0 +1,34 @@
+# Codecov configuration
+# Documentation: https://docs.codecov.com/docs/codecov-yaml
+
+codecov:
+  require_ci_to_pass: yes
+
+coverage:
+  precision: 2
+  round: down
+  range: "70...100"
+
+  status:
+    project:
+      default:
+        target: 90%
+        threshold: 1%
+        if_ci_failed: error
+
+    patch:
+      default:
+        target: 90%
+        threshold: 1%
+
+comment:
+  layout: "reach,diff,flags,tree,footer"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+ignore:
+  - "spec/**/*"
+  - "vendor/**/*"
+  - "gemfiles/**/*"

data/lib/better_translate/analyzer/code_scanner.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Scans code files to find i18n key references
+    #
+    # Supports multiple patterns:
+    # - t('key') / t("key")
+    # - I18n.t(:key) / I18n.t('key')
+    # - <%= t('key') %> in ERB
+    #
+    # @example Basic usage
+    #   scanner = CodeScanner.new("app/")
+    #   keys = scanner.scan
+    #   #=> #<Set: {"users.greeting", "products.list"}>
+    #
+    class CodeScanner
+      # I18n patterns to match
+      #
+      # Matches:
+      # - t('users.greeting')
+      # - t("users.greeting")
+      # - I18n.t(:users.greeting)
+      # - I18n.t('users.greeting')
+      # - I18n.translate('users.greeting')
+      I18N_PATTERNS = [
+        /\bt\(['"]([a-z0-9_.]+)['"]/i,             # t('key') or t("key")
+        /\bI18n\.t\(:([a-z0-9_.]+)/i,              # I18n.t(:key)
+        /\bI18n\.t\(['"]([a-z0-9_.]+)['"]/i,       # I18n.t('key')
+        /\bI18n\.translate\(['"]([a-z0-9_.]+)['"]/i # I18n.translate('key')
+      ].freeze
+
+      # File extensions to scan
+      SCANNABLE_EXTENSIONS = %w[.rb .erb .html.erb .haml .slim].freeze
+
+      # @return [String] Path to scan (file or directory)
+      attr_reader :path
+
+      # @return [Set] Found i18n keys
+      attr_reader :keys
+
+      # @return [Array<String>] List of scanned files
+      attr_reader :files_scanned
+
+      # Initialize scanner with path
+      #
+      # @param path [String] File or directory path to scan
+      #
+      def initialize(path)
+        @path = path
+        @keys = Set.new
+        @files_scanned = []
+      end
+
+      # Scan path and extract i18n keys
+      #
+      # @return [Set] Set of found i18n keys
+      # @raise [FileError] if path does not exist
+      #
+      # @example
+      #   scanner = CodeScanner.new("app/")
+      #   keys = scanner.scan
+      #   #=> #<Set: {"users.greeting"}>
+      #
+      def scan
+        validate_path!
+
+        files = collect_files
+        files.each do |file|
+          scan_file(file)
+          @files_scanned << file
+        end
+
+        @keys
+      end
+
+      # Get count of unique keys found
+      #
+      # @return [Integer] Number of unique keys
+      #
+      def key_count
+        @keys.size
+      end
+
+      private
+
+      # Validate that path exists
+      #
+      # @raise [FileError] if path does not exist
+      #
+      def validate_path!
+        return if File.exist?(path)
+
+        raise FileError.new(
+          "Path does not exist: #{path}",
+          context: { path: path }
+        )
+      end
+
+      # Collect all scannable files from path
+      #
+      # @return [Array<String>] List of file paths
+      #
+      def collect_files
+        if File.file?(path)
+          return [path] if scannable_file?(path)
+
+          return []
+        end
+
+        Dir.glob(File.join(path, "**", "*")).select do |file|
+          File.file?(file) && scannable_file?(file)
+        end
+      end
+
+      # Check if file should be scanned
+      #
+      # @param file [String] File path
+      # @return [Boolean]
+      #
+      def scannable_file?(file)
+        SCANNABLE_EXTENSIONS.any? { |ext| file.end_with?(ext) }
+      end
+
+      # Scan single file and extract keys
+      #
+      # @param file [String] File path
+      #
+      def scan_file(file)
+        content = File.read(file)
+
+        # Remove commented lines to avoid false positives
+        lines = content.split("\n")
+        active_lines = lines.reject { |line| line.strip.start_with?("#", "//", "<!--") }
+        active_content = active_lines.join("\n")
+
+        I18N_PATTERNS.each do |pattern|
+          active_content.scan(pattern) do |match|
+            key = match.is_a?(Array) ? match.first : match
+            @keys.add(key) if key
+          end
+        end
+      rescue StandardError => e
+        # Skip files that can't be read
+        warn "Warning: Could not scan #{file}: #{e.message}" if ENV["VERBOSE"]
+      end
+    end
+  end
+end

data/lib/better_translate/analyzer/key_scanner.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module BetterTranslate
+  module Analyzer
+    # Scans YAML translation files and extracts all keys in flatten format
+    #
+    # @example Basic usage
+    #   scanner = KeyScanner.new("config/locales/en.yml")
+    #   keys = scanner.scan
+    #   #=> { "users.greeting" => "Hello", "users.welcome" => "Welcome %{name}" }
+    #
+    class KeyScanner
+      # @return [String] Path to the YAML file
+      attr_reader :file_path
+
+      # @return [Hash] Flatten keys extracted from YAML
+      attr_reader :keys
+
+      # Initialize scanner with YAML file path
+      #
+      # @param file_path [String] Path to YAML file
+      #
+      def initialize(file_path)
+        @file_path = file_path
+        @keys = {}
+      end
+
+      # Scan YAML file and extract all flatten keys
+      #
+      # @return [Hash] Flatten keys with their values
+      # @raise [FileError] if file does not exist
+      # @raise [YamlError] if YAML is invalid
+      #
+      # @example
+      #   scanner = KeyScanner.new("en.yml")
+      #   keys = scanner.scan
+      #   #=> { "users.greeting" => "Hello" }
+      #
+      def scan
+        validate_file!
+
+        begin
+          content = YAML.load_file(file_path)
+
+          # Skip root language key (en, it, fr, etc.) and start from its content
+          if content.is_a?(Hash) && content.size == 1
+            root_key = content.keys.first.to_s
+            content = content[root_key] || {} if root_key.match?(/^[a-z]{2}(-[A-Z]{2})?$/)
+          end
+
+          flatten_keys(content)
+        rescue Psych::SyntaxError => e
+          raise YamlError.new(
+            "Invalid YAML syntax in #{file_path}",
+            context: { file: file_path, error: e.message }
+          )
+        end
+
+        @keys
+      end
+
+      # Get total count of keys
+      #
+      # @return [Integer] Number of keys
+      #
+      def key_count
+        @keys.size
+      end
+
+      private
+
+      # Validate that file exists
+      #
+      # @raise [FileError] if file does not exist
+      #
+      def validate_file!
+        return if File.exist?(file_path)
+
+        raise FileError.new(
+          "Translation file does not exist: #{file_path}",
+          context: { file: file_path }
+        )
+      end
+
+      # Flatten nested hash into dot-notation keys
+      #
+      # @param hash [Hash] Nested hash to flatten
+      # @param prefix [String] Prefix for current level
+      #
+      # @example
+      #   flatten_keys({ "users" => { "greeting" => "Hello" } })
+      #   #=> { "users.greeting" => "Hello" }
+      #
+      def flatten_keys(hash, prefix = nil)
+        hash.each do |key, value|
+          current_key = prefix ? "#{prefix}.#{key}" : key.to_s
+
+          if value.is_a?(Hash)
+            flatten_keys(value, current_key)
+          else
+            @keys[current_key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/better_translate/analyzer/orphan_detector.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module BetterTranslate
+  module Analyzer
+    # Detects orphan i18n keys (keys defined but never used in code)
+    #
+    # @example Basic usage
+    #   all_keys = { "users.greeting" => "Hello", "orphan" => "Unused" }
+    #   used_keys = Set.new(["users.greeting"])
+    #
+    #   detector = OrphanDetector.new(all_keys, used_keys)
+    #   orphans = detector.detect
+    #   #=> ["orphan"]
+    #
+    class OrphanDetector
+      # @return [Hash] All translation keys with their values
+      attr_reader :all_keys
+
+      # @return [Set] Keys that are used in code
+      attr_reader :used_keys
+
+      # @return [Array<String>] Orphan keys (not used in code)
+      attr_reader :orphans
+
+      # Initialize detector
+      #
+      # @param all_keys [Hash] All translation keys from YAML files
+      # @param used_keys [Set] Keys found in code
+      #
+      def initialize(all_keys, used_keys)
+        @all_keys = all_keys
+        @used_keys = used_keys
+        @orphans = []
+      end
+
+      # Detect orphan keys
+      #
+      # Compares all keys with used keys and identifies those that are never referenced.
+      #
+      # @return [Array<String>] List of orphan key names
+      #
+      # @example
+      #   detector.detect
+      #   #=> ["orphan_key", "another.orphan"]
+      #
+      def detect
+        @orphans = all_keys.keys.reject { |key| used_keys.include?(key) }
+      end
+
+      # Get count of orphan keys
+      #
+      # @return [Integer] Number of orphan keys
+      #
+      def orphan_count
+        @orphans.size
+      end
+
+      # Get details of orphan keys with their values
+      #
+      # @return [Hash] Hash of orphan keys and their translation values
+      #
+      # @example
+      #   detector.orphan_details
+      #   #=> { "orphan_key" => "This is never used" }
+      #
+      def orphan_details
+        # @type var result: Hash[String, untyped]
+        result = {}
+        @orphans.each do |key|
+          result[key] = all_keys[key]
+        end
+        result
+      end
+
+      # Calculate usage percentage
+      #
+      # @return [Float] Percentage of keys that are used (0.0 to 100.0)
+      #
+      # @example
+      #   detector.usage_percentage
+      #   #=> 75.0  # 6 out of 8 keys are used
+      #
+      def usage_percentage
+        return 0.0 if all_keys.empty?
+
+        used_count = all_keys.size - @orphans.size
+        (used_count.to_f / all_keys.size * 100).round(1).to_f
+      end
+    end
+  end
+end