better_translate 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80868b0f529d5c8310efabe07a402bd89d015e6bced86a3c0e2689e288d702f6
-  data.tar.gz: fdaede4b54e2c956d3f2cc936f221a83703a2001e1d647fec3abe2283d11e157
+  metadata.gz: 602a159b9ba2217e813a2d2b2f5b121e2fcc33006b18f12de64a99eb83ba3b16
+  data.tar.gz: 9c4db4fb12302620492af42d6db5e369f2d00fac3c62d288d6d11e872bb5acf1
 SHA512:
-  metadata.gz: 90a863900c1e132d7be3bf96a80a66cfad9580e38d7c634fd0e8dcea891be5768ff4cd548eadae6a74dde15a18c4f839a047e8e0653e6642272e518e6859ebac
-  data.tar.gz: 3ffb3062a2919d7296fe0ad95f28f29d5352ea3c126f12d09c89229378194a6386c4da65a7d419e7868d34d2297353a2561364600b1b5fe09d30ee9a24244408
+  metadata.gz: a67b31f8cc1aa48775baddae6982f2bcc0e18a9a3966981b40a6b122e976ebd93922f17cbfc7ae8eeddd8741668006eafcedec13dcdf63cfdd209ed2695f4de3
+  data.tar.gz: a5f455c8a676a0899bab3e03bf71ed51c6d4a5b16e81cb1bfb6ef90e560352758319a6616e1f269039a47decf14e72070bdfe39be5ebec6457c83cbd9b79a47e

data/CLAUDE.md

@@ -75,10 +75,21 @@ bundle exec rake steep
 # or
 bundle exec steep check
 
-# Run default rake task (runs spec, rubocop, and steep)
+# Run default rake task (runs spec, rubocop, steep, and brakeman)
 bundle exec rake
 ```
 
+### Security
+```bash
+# Run Brakeman security scanner
+bundle exec rake brakeman
+# or
+bundle exec brakeman --force --no-pager
+
+# Check for security vulnerabilities in dependencies
+bundle exec bundler-audit check --update
+```
+
 ### Documentation
 ```bash
 # Generate YARD documentation
@@ -91,12 +102,6 @@ bundle exec yard server
 bundle exec yard stats
 ```
 
-### Security
-```bash
-# Check for security vulnerabilities in dependencies
-bundle exec bundler-audit check --update
-```
-
 ### Type Checking (RBS/Steep)
 ```bash
 # Run type checking

data/CONTRIBUTING.md

@@ -0,0 +1,432 @@
+# Contributing to BetterTranslate
+
+First off, thank you for considering contributing to BetterTranslate! 🎉
+
+It's people like you that make BetterTranslate such a great tool. We welcome contributions from everyone, whether you're fixing a typo or implementing a major feature.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Workflow](#development-workflow)
+- [Testing](#testing)
+- [Code Style](#code-style)
+- [Commit Messages](#commit-messages)
+- [Pull Requests](#pull-requests)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Features](#suggesting-features)
+
+## Code of Conduct
+
+This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby >= 3.0.0
+- Bundler
+- Git
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/better_translate.git
+   cd better_translate
+   ```
+
+3. Add the upstream repository:
+   ```bash
+   git remote add upstream https://github.com/alessiobussolari/better_translate.git
+   ```
+
+### Install Dependencies
+
+```bash
+bundle install
+```
+
+### Set Up Environment
+
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Add your API keys (optional, only needed for integration tests):
+   ```env
+   OPENAI_API_KEY=sk-...
+   GEMINI_API_KEY=...
+   ANTHROPIC_API_KEY=sk-ant-...
+   ```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+Always create a new branch for your work:
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Your Changes
+
+- Write clean, readable code
+- Follow the existing code style
+- Add tests for new features
+- Update documentation as needed
+
+### 3. Run Tests
+
+Before committing, make sure all tests pass:
+
+```bash
+# Run all tests
+bundle exec rake
+
+# Or run individual checks:
+bundle exec rake spec          # Tests
+bundle exec rake rubocop       # Linting
+bundle exec rake steep         # Type checking
+bundle exec rake brakeman      # Security scan
+```
+
+### 4. Commit Your Changes
+
+```bash
+git add .
+git commit -m "feat: Add awesome feature"
+```
+
+See [Commit Messages](#commit-messages) for guidelines.
+
+### 5. Push and Create PR
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub.
+
+## Testing
+
+### Test Structure
+
+- **Unit Tests**: `spec/better_translate/`
+  - Fast, no API calls
+  - Use WebMock for HTTP stubs
+
+- **Integration Tests**: `spec/integration/`
+  - Real API interactions via VCR
+  - Require API keys for first run
+  - Subsequent runs use recorded cassettes
+
+### Running Tests
+
+```bash
+# All tests
+bundle exec rspec
+
+# Only unit tests (fast)
+bundle exec rspec spec/better_translate/
+
+# Only integration tests
+bundle exec rspec spec/integration/ --tag integration
+
+# Specific file
+bundle exec rspec spec/better_translate/translator_spec.rb
+
+# Specific line
+bundle exec rspec spec/better_translate/translator_spec.rb:42
+```
+
+### Writing Tests
+
+**We follow Test-Driven Development (TDD)**:
+
+1. **RED**: Write a failing test
+2. **GREEN**: Write minimum code to pass
+3. **REFACTOR**: Clean up code
+
+Example:
+
+```ruby
+RSpec.describe MyNewFeature do
+  describe "#awesome_method" do
+    it "does something awesome" do
+      feature = MyNewFeature.new
+      result = feature.awesome_method
+
+      expect(result).to eq("awesome")
+    end
+  end
+end
+```
+
+### Test Coverage
+
+We maintain **93%+ test coverage**. New code should include tests:
+
+```bash
+# Check coverage
+bundle exec rspec
+# View coverage report: open coverage/index.html
+```
+
+## Code Style
+
+### RuboCop
+
+We use RuboCop for code style enforcement:
+
+```bash
+# Check style
+bundle exec rubocop
+
+# Auto-fix issues
+bundle exec rubocop -a
+```
+
+### Key Guidelines
+
+- Use double quotes for strings
+- 2 spaces for indentation (no tabs)
+- Maximum line length: 120 characters
+- Frozen string literals at top of files: `# frozen_string_literal: true`
+- YARD documentation for public methods
+
+### YARD Documentation
+
+All public methods must have YARD documentation:
+
+```ruby
+# Translates text to target language
+#
+# @param text [String] The text to translate
+# @param lang [String] Target language code (e.g., "it", "fr")
+# @return [String] Translated text
+# @raise [ValidationError] If input is invalid
+#
+# @example
+#   translate("Hello", "it") #=> "Ciao"
+#
+def translate(text, lang)
+  # ...
+end
+```
+
+### Type Checking
+
+We use Steep for static type checking:
+
+```bash
+# Run type checker
+bundle exec steep check
+
+# Check specific file
+bundle exec steep check lib/better_translate/translator.rb
+```
+
+Type signatures go in `sig/` directory (RBS format).
+
+## Commit Messages
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+### Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+### Examples
+
+```bash
+# Good commits
+git commit -m "feat: Add support for JSON locale files"
+git commit -m "fix: Handle nil values in translations"
+git commit -m "docs: Update README with new examples"
+git commit -m "test: Add coverage for edge cases"
+
+# With scope
+git commit -m "feat(cli): Add --dry-run flag"
+git commit -m "fix(cache): Fix TTL expiration bug"
+```
+
+### Multi-line Commits
+
+For complex changes:
+
+```
+feat: Add parallel translation support
+
+- Implement thread-based concurrent execution
+- Add max_concurrent_requests configuration
+- Include progress tracking for parallel operations
+
+Closes #42
+```
+
+## Pull Requests
+
+### Before Submitting
+
+- [ ] Tests pass: `bundle exec rake`
+- [ ] Code follows style guide
+- [ ] YARD documentation added for public methods
+- [ ] CHANGELOG.md updated (for notable changes)
+- [ ] README.md updated (if needed)
+
+### PR Title
+
+Use conventional commit format:
+
+```
+feat: Add awesome feature
+fix: Resolve critical bug
+docs: Improve installation guide
+```
+
+### PR Description Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+How has this been tested?
+
+## Checklist
+- [ ] Tests pass locally
+- [ ] Tests added for new features
+- [ ] Documentation updated
+- [ ] No RuboCop offenses
+- [ ] No Brakeman warnings
+```
+
+### Review Process
+
+1. Automated checks run (CI/CD)
+2. Maintainer reviews code
+3. Address feedback if needed
+4. Maintainer merges PR
+
+## Reporting Bugs
+
+### Before Submitting
+
+- Check existing issues
+- Try latest version
+- Gather reproduction steps
+
+### Bug Report Template
+
+```markdown
+**Describe the bug**
+Clear description of the bug
+
+**To Reproduce**
+Steps to reproduce:
+1. ...
+2. ...
+3. ...
+
+**Expected behavior**
+What you expected to happen
+
+**Actual behavior**
+What actually happened
+
+**Environment**
+- Ruby version: [e.g., 3.3.4]
+- BetterTranslate version: [e.g., 1.1.0]
+- OS: [e.g., macOS, Ubuntu]
+
+**Additional context**
+Any other relevant information
+```
+
+## Suggesting Features
+
+We love feature suggestions! Open an issue with:
+
+```markdown
+**Feature Description**
+Clear description of the feature
+
+**Use Case**
+Why is this feature needed?
+
+**Proposed Solution**
+How should it work?
+
+**Alternatives Considered**
+Other approaches you've thought about
+
+**Additional Context**
+Screenshots, mockups, examples, etc.
+```
+
+## Development Commands
+
+```bash
+# Run all checks
+bundle exec rake
+
+# Individual checks
+bundle exec rake spec          # Tests (541 examples)
+bundle exec rake rubocop       # Linting
+bundle exec rake steep         # Type checking
+bundle exec rake brakeman      # Security scan
+
+# Code quality
+bundle exec rubocop -a         # Auto-fix style issues
+bundle exec yard doc           # Generate documentation
+bundle exec bundler-audit      # Check dependencies
+
+# Interactive console
+bin/console
+
+# Demo app
+ruby spec/dummy/demo_translation.rb
+```
+
+## Questions?
+
+Feel free to:
+- Open an issue
+- Start a discussion
+- Email: alessio.bussolari@pandev.it
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to BetterTranslate! 🚀

data/README.md

@@ -2,9 +2,15 @@
 
 > AI-powered YAML locale file translator for Rails and Ruby projects
 
+[![CI](https://github.com/alessiobussolari/better_translate/actions/workflows/main.yml/badge.svg)](https://github.com/alessiobussolari/better_translate/actions/workflows/main.yml)
+[![codecov](https://codecov.io/gh/alessiobussolari/better_translate/branch/main/graph/badge.svg)](https://codecov.io/gh/alessiobussolari/better_translate)
+[![Gem Version](https://badge.fury.io/rb/better_translate.svg)](https://badge.fury.io/rb/better_translate)
+[![Downloads](https://img.shields.io/gem/dt/better_translate)](https://rubygems.org/gems/better_translate)
 [![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-[![Gem Version](https://img.shields.io/badge/version-1.1.0-green.svg)](https://rubygems.org/gems/better_translate)
+[![Security](https://img.shields.io/badge/security-brakeman-green)](https://brakemanscanner.org/)
+[![Type Check](https://img.shields.io/badge/types-steep-blue)](https://github.com/soutaro/steep)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/alessiobussolari/better_translate/graphs/commit-activity)
 
 BetterTranslate automatically translates your YAML locale files using cutting-edge AI providers (ChatGPT, Google Gemini, and Anthropic Claude). It's designed for Rails applications but works with any Ruby project that uses YAML-based internationalization.
 

data/Rakefile

@@ -15,4 +15,17 @@ task :steep do
   sh "bundle exec steep check"
 end
 
-task default: %i[spec rubocop steep]
+# Security scanning with Brakeman
+desc "Run security scanning with Brakeman"
+task :brakeman do
+  require "brakeman"
+  result = Brakeman.run(
+    app_path: ".",
+    print_report: true,
+    pager: false,
+    force_scan: true
+  )
+  exit Brakeman::Warnings_Found_Exit_Code unless result.filtered_warnings.empty?
+end
+
+task default: %i[spec rubocop steep brakeman]

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"