rosett-ai 1.3.3 → 1.5.10

data/doc/REEK_CONFIGURATION.md

@@ -1,166 +0,0 @@
-# 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

@@ -1,253 +0,0 @@
-# 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 |