rosett-ai 1.3.3

data/doc/REEK_CONFIGURATION.md

@@ -0,0 +1,166 @@
+# Reek Configuration Documentation
+
+This document describes the Reek configuration for the Rosett-AI project and documents issues that were identified and fixed.
+
+## Reference
+
+- **Reek Version**: 6.5.0 (March 2025)
+- **Documentation Source**: <https://github.com/troessner/reek>
+- **Local Reference**: `~/git/Community/Github/troessner/reek`
+
+## Issues Fixed (2026-01-20)
+
+### Issue 1: Deprecated Ruby Regexp Syntax
+
+**Problem**: The configuration used Reek 4-style `!ruby/regexp` tags which are no longer supported in Reek 5+.
+
+**Error Message**:
+
+```text
+Error: Invalid configuration file .reek.yml, error is Tried to load unspecified class: Regexp
+```
+
+**Before (Invalid)**:
+
+```yaml
+UncommunicativeMethodName:
+  reject:
+    - !ruby/regexp /^[a-z]$/
+    - !ruby/regexp /[0-9]$/
+```
+
+**After (Valid)**:
+
+```yaml
+UncommunicativeMethodName:
+  reject:
+    - "/^[a-z]$/"
+    - "/[0-9]$/"
+```
+
+**Affected Detectors**:
+
+- `UncommunicativeMethodName`
+- `UncommunicativeModuleName`
+- `UncommunicativeParameterName`
+- `UncommunicativeVariableName`
+
+**Reference**: [Reek 4 to Reek 5 Migration Guide](https://github.com/troessner/reek/blob/master/docs/Reek-4-to-Reek-5-migration.md)
+
+---
+
+### Issue 2: Array Method Name Not Quoted
+
+**Problem**: The `[]` (array accessor) method name in `allow_calls` was interpreted as an empty YAML array instead of the string `"[]"`.
+
+**Error Message**:
+
+```text
+Error: Invalid configuration file .reek.yml, error is
+[/detectors/DuplicateMethodCall/allow_calls/2] must be a string.
+```
+
+**Before (Invalid)**:
+
+```yaml
+DuplicateMethodCall:
+  allow_calls:
+    - puts
+    - print
+    - []
+```
+
+**After (Valid)**:
+
+```yaml
+DuplicateMethodCall:
+  allow_calls:
+    - puts
+    - print
+    - "[]"
+```
+
+**Reference**: [Duplicate Method Call Documentation](https://github.com/troessner/reek/blob/master/docs/Duplicate-Method-Call.md)
+
+---
+
+### Issue 3: Duplicate YAML Keys
+
+**Problem**: The `TooManyStatements` detector had duplicate `exclude:` keys. In YAML, duplicate keys cause the second value to overwrite the first, silently breaking the configuration.
+
+**Before (Invalid)**:
+
+```yaml
+TooManyStatements:
+  enabled: true
+  max_statements: 10
+  exclude:
+    - initialize
+  exclude: []  # This overwrites the above!
+```
+
+**After (Valid)**:
+
+```yaml
+TooManyStatements:
+  enabled: true
+  max_statements: 10
+  exclude:
+    - initialize
+```
+
+---
+
+## Custom Configuration Values
+
+The following settings deviate from Reek's defaults. These are intentional project-specific adjustments:
+
+| Detector | Option | Project Value | Default Value | Rationale |
+|----------|--------|---------------|---------------|-----------|
+| `DataClump` | `min_clump_size` | 3 | 2 | Less strict for small projects |
+| `DuplicateMethodCall` | `max_calls` | 2 | 1 | Allow reasonable duplication |
+| `LongParameterList` | `max_params` | 4 | 3 | Slightly more permissive |
+| `NestedIterators` | `max_allowed_nesting` | 2 | 1 | Allow one level of nesting |
+| `RepeatedConditional` | `max_ifs` | 3 | 2 | Allow more conditionals |
+| `TooManyConstants` | `max_constants` | 7 | 5 | Configuration-heavy modules |
+| `TooManyInstanceVariables` | `max_instance_variables` | 5 | 4 | Slightly more permissive |
+| `TooManyStatements` | `max_statements` | 10 | 5 | Allow longer methods |
+| `UtilityFunction` | `public_methods_only` | true | false | Only check public methods |
+| `UnusedPrivateMethod` | `enabled` | true | false | Enable unused method detection |
+| `IrresponsibleModule` | `enabled` | false | true | Disabled (no mandatory docs) |
+| `MissingSafeMethod` | `enabled` | false | true | Disabled |
+
+## Disabled Checks for Specific Contexts
+
+### Spec Directory
+
+The following detectors are disabled for the `spec/` directory:
+
+- `UtilityFunction`
+- `FeatureEnvy`
+- `TooManyStatements`
+
+### Excluded Classes/Methods
+
+- `DuplicateMethodCall`: `RosettAi::Thor::Tasks::Behaviour`, `RosettAi::Thor::Tasks::Documentation`
+- `FeatureEnvy`: `RosettAi::Configuration#deep_merge`
+- `SubclassedFromCoreClass`: `RosettAi::Error`
+- `TooManyInstanceVariables`: `RosettAi::Thor::Tasks::Behaviour`
+- `TooManyMethods`: `RosettAi::Thor::Tasks::Behaviour`, `RosettAi::Thor::Tasks::Documentation`
+
+## Excluded Paths
+
+The following paths are excluded from analysis:
+
+- `vendor/`
+- `tmp/`
+- `cache/`
+- `coverage/`
+
+## Best Practices
+
+1. **Always quote method names that are special characters**: `"[]"`, `"[]="`
+2. **Use string-wrapped regex patterns**: `"/pattern/"` instead of `!ruby/regexp /pattern/`
+3. **Avoid duplicate YAML keys**: YAML parsers silently use the last value
+4. **Keep local reference documentation**: Clone tool repositories for offline reference
+5. **Verify against latest versions**: Check tool documentation before configuration changes

data/doc/REFERENCE.md

@@ -0,0 +1,253 @@
+# Configuration Reference
+
+This document provides a comprehensive reference for all rai configuration, file locations, environment variables, and CLI options.
+
+## Configuration Hierarchy
+
+Configuration is resolved in order of increasing specificity:
+
+1. **Built-in defaults** (compiled into rosett-ai)
+2. **Global rai config** (`~/.config/rosett-ai/config.yml`)
+3. **Global Claude Code settings** (`~/.claude/settings.json`)
+4. **Local Claude Code settings** (`~/.claude/settings.local.json`)
+5. **Project rai config** (`.rosett-ai/config.yml`)
+6. **Project Claude Code settings** (`.claude/settings.json`)
+7. **CLI flags** (always override everything)
+
+## Global Configuration
+
+### `~/.config/rosett-ai/config.yml`
+
+Runtime configuration for rosett-ai itself. Created by `rai init --global`.
+
+```yaml
+default_engine: claude        # Engine used when --engine is not specified
+cache:
+  enabled: true               # Cache adopt analysis results
+  ttl_hours: 24               # Cache time-to-live in hours
+detect:
+  on_init: true               # Run engine detection during init --global
+```
+
+**Schema**: `conf/schemas/rai_config_schema.json`
+
+### Available engines
+
+| Engine | Package | Description |
+|--------|---------|-------------|
+| `claude` | `rosett-ai-engine-claude` | Claude Code (Anthropic) |
+| `generic` | `rosett-ai-engine-generic` | Generic AI assistant |
+| `agents_md` | `rosett-ai-engine-agents-md` | AGENTS.md (vendor-neutral) |
+| `ollama` | `rosett-ai-engine-ollama` | Ollama (local LLM) |
+| `gpt_neox` | `rosett-ai-engine-gpt-neox` | GPT-NeoX (EleutherAI) |
+| `goose` | `rosett-ai-engine-goose` | Goose (Block) |
+| `aider` | `rosett-ai-engine-aider` | Aider (AI pair programming) |
+| `cursor` | `rosett-ai-engine-cursor` | Cursor (Anysphere) |
+| `copilot` | `rosett-ai-engine-copilot` | GitHub Copilot |
+| `windsurf` | `rosett-ai-engine-windsurf` | Windsurf (Codeium) |
+
+## Project Configuration
+
+### `.rosett-ai/config.yml`
+
+Per-project rai configuration. Created by `rai init --project`.
+
+```yaml
+project_name: my-project      # Project identifier
+default_engine: claude         # Override global default engine
+```
+
+### `.rosett-ai/conf/`
+
+Project-specific source files:
+
+| Directory | Content |
+|-----------|---------|
+| `conf/behaviour/` | Behaviour YAML files (rules, priorities) |
+| `conf/design/` | Design document YAML files |
+
+## Engine Configuration
+
+### Discovery
+
+raictl discovers engine plugins through three mechanisms:
+
+1. **Gem discovery** (`Gem.find_files`): Standard RubyGems path. Works when `GEM_PATH` matches the Ruby ABI version.
+2. **Embedded fallback** (`/opt/rosett-ai/embedded/lib/ruby/gems/`): Version-agnostic scan of the embedded gem tree. Handles ABI mismatch between embedded Ruby and engine gems.
+3. **Custom path** (`RAI_ENGINE_PATH`): Colon-separated list of directories for development/testing.
+
+### Installation
+
+Engines are installed as separate `.deb` packages:
+
+```bash
+apt install rosett-ai-engine-claude
+apt install rosett-ai-engine-generic
+```
+
+### Target Profiles
+
+Each engine provides a target profile (`conf/target.yml`) declaring:
+
+```yaml
+name: claude
+description: Claude Code (Anthropic) target
+backend: claude
+engine_version: ">=1.0.0"
+output_format: markdown
+output_dir: null
+max_context_window: 200000
+rendering:
+  include_source_metadata: true
+  include_priority_annotations: true
+  include_generated_marker: true
+```
+
+**Schema**: `conf/schemas/target_schema.json`
+
+## Behaviour Files
+
+### Schema
+
+```yaml
+name: string                   # Unique identifier
+description: string            # Human-readable description
+version: string                # Semver version
+author: string                 # Author name
+created_at: string             # ISO date
+modified_at: string            # ISO date
+modified_by: string            # Last modifier
+sensitive: boolean             # Exclude from API analysis
+used_in: [string]              # Cross-references
+rules:
+  - id: string                 # Unique rule ID (e.g. rule_001)
+    description: string        # Rule description (supports multiline)
+    priority: integer           # 1-100 (higher = more important)
+    enabled: boolean           # Whether rule is active
+```
+
+**Schema**: `conf/schemas/behaviour_schema.json`
+
+## Design Documents
+
+### Schema
+
+```yaml
+name: string                   # Unique identifier
+domain: string                 # Domain area (core, security, etc.)
+version: string                # Semver version
+status: string                 # draft | review | approved | deprecated
+intent: string                 # What this design achieves
+constraints: [string]          # Technical/business constraints
+acceptance_criteria: [string]  # Verification criteria
+dependencies: [string]         # Other design dependencies (optional)
+examples: [{scenario, expected, not_expected}]  # Examples (optional)
+anti_patterns: [string]        # What to avoid (optional)
+preferences: [string]          # Soft preferences (optional)
+```
+
+**Schema**: `conf/schemas/design_schema.json`
+
+## Claude Code Configuration
+
+Scope files in `conf/claude_code/` (or engine-specific config dirs) compile to Claude Code JSON settings.
+
+| Scope | Output | Purpose |
+|-------|--------|---------|
+| `managed` | `managed-settings.json` | rosett-ai-managed settings |
+| `user` | `settings.json` | User-level preferences |
+| `project` | `project-settings.json` | Project-specific settings |
+| `local` | `settings.local.json` | Machine-local overrides |
+
+## CLI Options Reference
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--version`, `-v` | Show version |
+| `--help`, `-h` | Show help |
+
+### `rai compile`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--engine NAME` | configured | Target engine |
+| `--verbose` | false | Show detailed output |
+| `--simulate` | false | Dry run with diffs |
+| `--vendor` | false | Write lockfile |
+| `--strict` | false | Treat warnings as errors |
+| `--locales` | false | Compile locale files |
+
+### `rai config compile`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--engine NAME` | configured | Target engine |
+| `--verbose` | false | Show detailed output |
+| `--simulate` | false | Dry run |
+| `--scope NAME` | all | Compile specific scope only |
+
+### `rai init`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--global` | false | Set up `~/.claude/` structure |
+| `--local` | false | Set up `.claude/` structure |
+| `--project` | false | Set up `.rosett-ai/` structure |
+| `--no-compile` | false | Skip rule compilation |
+
+### `rai adopt`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--api` | false | Enable remote API analysis |
+| `--verbose` | false | Show processing details |
+| `--elaborate` | false | Show detailed findings |
+
+### `raictl build package`
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--clean` | false | Clean staging directory |
+| `--verbose` | false | Show build details |
+| `--architecture` | native | Target architecture |
+| `--ruby-version` | current | Override Ruby version |
+| `--output-dir` | `pkg/` | Output directory |
+
+## Environment Variables
+
+| Variable | Purpose | Set By |
+|----------|---------|--------|
+| `RAI_ORIGINAL_PWD` | Preserves user's working directory when running from `.deb` wrapper | `wrapper.sh` |
+| `RAI_ENGINE_PATH` | Colon-separated custom engine discovery paths | User |
+| `RAI_LOG_LEVEL` | Log verbosity (`DEBUG`, `INFO`, `WARN`, `ERROR`) | User |
+
+## File Locations Summary
+
+### Global (per-user)
+
+| Path | Purpose |
+|------|---------|
+| `~/.config/rosett-ai/config.yml` | rosett-ai runtime config |
+| `~/.claude/settings.json` | Claude Code user settings |
+| `~/.claude/settings.local.json` | Machine-local overrides |
+| `~/.claude/rules/` | Compiled rule files |
+
+### Project
+
+| Path | Purpose |
+|------|---------|
+| `.rosett-ai/config.yml` | Project rai config |
+| `.rosett-ai/conf/behaviour/` | Project behaviours |
+| `.rosett-ai/conf/design/` | Project design docs |
+| `.claude/` | Project Claude Code config |
+
+### Installation (`.deb`)
+
+| Path | Purpose |
+|------|---------|
+| `/opt/rosett-ai/app/` | Application code |
+| `/opt/rosett-ai/embedded/` | Embedded Ruby + gems |
+| `/opt/rosett-ai/bin/raictl` | Wrapper script |
+| `/usr/local/bin/raictl` | Symlink |