habit-hooks-ruby 1.5.0__tar.gz

habit_hooks_ruby-1.5.0/.gitignore

@@ -0,0 +1,26 @@
+# Per-plugin Node tool deps (installed via pnpm install; see pnpm-workspace.yaml)
+node_modules/
+dist
+coverage
+.DS_Store
+.idea
+.claude-channel/
+*.tgz
+*.log
+.vscode/
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.spec-runs/
+
+# Workflow orchestration script (run from ~/.claude, never a repo deliverable)
+.claude/workflows-build-overnight.js
+
+# Agent worktrees (created by the harness inside the checkout)
+.claude/worktrees/
+/scratches/
+
+# unsupervised-issues run signals (live mode switch + stop flag)
+.unsupervised-issues.mode
+.unsupervised-issues.stop

habit_hooks_ruby-1.5.0/CLAUDE.md

@@ -0,0 +1,171 @@
+# habit-hooks-ruby notes
+
+## Architecture
+
+### The project's `.rubocop.yml` decides everything
+
+The sensor passes no `--only` and no `--config`. RuboCop finds the project's
+config by its own upward walk, so a project's habit-hooks run is the run it gets
+from RuboCop directly. There is no shipped fallback config, and the plugin never
+writes one into a project. The README carries a suggested `.rubocop.yml` as
+documentation only — unlike jscpd or pmd, RuboCop's config already exists in
+almost every real Ruby project, so this plugin has no fallback case to cover.
+
+`--force-exclusion` is the one flag the sensor adds, and it is not optional.
+RuboCop applies `AllCops: Exclude:` to the files it *discovers*, but treats a
+file named on the command line as a deliberate request and lints it anyway.
+Since habit-hooks always names a scope, without that flag a project's own
+exclusions would stop meaning anything the moment this tool ran.
+
+### An unmapped cop is forwarded, not dropped
+
+This is the same exception to "a sensor emits vocabulary smells only" that the
+root `CLAUDE.md` makes for eslint: a cop that fired is one the project's own
+`.rubocop.yml` turned on, so forwarding it forwards the project's own decision.
+
+The smell key is the cop name verbatim, `Style/StringLiterals`. Nothing downstream breaks on one: the
+guide lookup misses, the finding renders through `uncoached.md`, and the root
+`uncoached` key (default `suggest`) decides whether it fails the run.
+
+Two cops are unmapped **on purpose** rather than by omission, so do not "fix"
+them by adding rows. `Metrics/ClassLength` and `Metrics/ModuleLength` measure a
+class or module, and the vocabulary has no class-scoped smell for them to back.
+They stay **uncoached** — forwarded under their own names, rendered through
+`uncoached.md`, `suggest` until a class and module scoped coach exists.
+
+The three complexity cops all map to `high-complexity` (human decision). They
+are correlated but independent — `PerceivedComplexity` weights nesting and
+`AbcSize` counts assignments and calls, so either fires without
+`CyclomaticComplexity` — and an unmapped complexity cop coached a genuinely
+tangled method through `uncoached.md` when the real guide applied verbatim. The
+old objection, one method reported three times over, is dissolved by the
+mapper: this sensor groups every cop that fired on a smell into one finding's
+issue list, which is never deduped (issue #140), so a method tripping two cops
+keeps both measurements inside a single coaching block.
+
+## Gotchas
+
+### RuboCop reads a file argument as options, then as a glob
+
+A scope filename is exact, and RuboCop reads its file arguments two other ways
+before it reads them as names. A filename beginning with `-` is parsed as short
+options — `-c` among them, which takes the rest as its `--config` value — and an
+argument containing a `*` is handed to `Dir[]`
+(`TargetFinder#process_explicit_path`), so a literal star sweeps in every file
+it matches. `run_rubocop` therefore puts `--` between its flags and the files,
+and `literal_spelling_of` escapes the glob metacharacters.
+
+The escaping is narrower than it looks, and has to be. RuboCop globs only an
+argument containing a `*`; every other one it takes verbatim, backslashes
+included, so escaping a `?` in a starless path would name a file that does not
+exist and the run would die on `Error: No such file or directory`. The other
+metacharacters are escaped only inside a starred argument, where `Dir[]` is
+reading the whole thing as a pattern. The literal-star behavioural test runs
+only where a filesystem allows a `*` in a name — Windows forbids it — so it
+skips there through
+`tests/platform_probe.A_FILESYSTEM_THAT_ALLOWS_A_STAR_IN_A_FILENAME`.
+
+### RuboCop's exit code lies when the binstub never reached RuboCop
+
+`ruff_sensor` can trust ruff's exit code. `rubocop` is a RubyGems
+binstub beginning `#!/usr/bin/env ruby`, so it is only as good as the `ruby`
+that answers first. Point it at an interpreter it is not installed into (a
+version manager left off `PATH`, the wrong bundle, macOS's system Ruby 2.6) and
+it dies in `find_spec_for_exe` with a Ruby traceback and **exit 1** — the code
+reserved for "I found offences". Judged on the code alone, that is a clean file
+from a tool that never started, which is the false-clean class issue #88 exists
+for.
+
+So the report is the evidence, not the code. `--format json` prints its envelope
+on every run RuboCop completed, down to `"files": []` when it inspected nothing,
+so no envelope means no run whatever it exited with. `report()` answers `None`
+for anything that is not a report, and it requires the `files` key rather than
+merely valid JSON. `rubocop_crashed()` takes the parsed report as an argument
+instead of re-deriving it, so the rule lives in one place and `main` cannot
+drift from what the tests exercise.
+
+Ask this of any wrapped tool reached through an interpreter shim rather than a
+binary. The cost of getting it wrong is silence, and silence reads as success.
+
+The envelope check has one concern: a cop that *raises exceptions*.
+By default, RuboCop rescues the exception, reports the crash on stderr,
+and exits 1 with a valid envelope listing that file's offences as `[]`.
+This isn't what habit-hooks needs to detect the crash. So `--raise-cop-error`
+is used to make a RuboCop crash become an `Error:` and exit 2, which
+habit-hooks interprets as a failed run.
+
+`tests/test_the_sensor_runs_the_rubocop_it_is_handed.py` has to hand `ruby` back
+on a directory of its own for the same reason. The binstub and its interpreter
+live in one directory, so taking `rubocop` off `PATH` takes `ruby` with it, and
+the test would then be proving the crash rather than the lookup.
+
+### RuboCop globs every ancestor directory looking for a gemspec
+
+`TargetRuby` settles which Ruby to parse as by trying, in order,
+`TargetRubyVersion` in the config, then any `*.gemspec`, then `.ruby-version`.
+The gemspec step is a `Dir.glob` up every ancestor directory to the filesystem
+root, and **`.ruby-version` does not prevent it**, because RuboCop looks for the
+gemspec first. A Rails app, which has no gemspec, therefore sends RuboCop
+climbing out of the project on every run. A gem stops the climb by having a
+gemspec; everything else stops it by pinning `TargetRubyVersion`.
+
+That is RuboCop's own behaviour and the sensor reproduces it rather than
+papering over it, per the precedence rule in the root `CLAUDE.md`. It matters
+for the tests because the spec harness runs each case in
+`<repo>/.spec-runs/tmpXXXX/`: a case pinning neither climbs through this
+checkout and out into the home directory, where a sandboxed dev machine denies
+the glob outright and the sensor fails for a reason that has nothing to do with
+the case. Every case in `docs/ruby-plugin.spec.md` and
+`tests/installed_projects.ruby_project` pins `TargetRubyVersion`.
+
+It is the RuboCop counterpart of the root `CLAUDE.md`'s `GIT_CEILING_DIRECTORIES`
+rule and of jscpd's `.gitignore` walk: a wrapped tool that searches upward has
+to be given a floor, or it finds ours.
+
+### A Rails project's rubocop is the only one that can read its config
+
+A `.rubocop.yml` naming cops from an extension gem is a hard RuboCop error when
+that gem is not loadable:
+
+```
+Error: `Rails/*` has been extracted to the `rubocop-rails` gem.
+```
+
+Nearly every Rails repo pins rubocop plus `rubocop-rails` / `rubocop-rspec` /
+`rubocop-performance` in its `Gemfile`, and those gems load only under the
+project's own bundle. This is the likeliest way the sensor fails in practice,
+and it is why the plugin's rubocop detector declares
+`search_paths = ["bin"]` (`src/habit_hooks_ruby/config.toml`):
+`bundle binstubs rubocop` writes `bin/rubocop`, and every lookup for that
+tool — `missing_tools` clearing it, `sensors/named_tools.py` resolving the
+recipe's `${detector:rubocop}` — searches the project's `bin` ahead of the
+default path.
+
+The lookup belongs in the core and not in this sensor. `missing_tools`
+clears a tool by asking `tool_executable`, and `sensors/spawn.py` spawns the
+file it answered with, so a second answer here would let setup clear a rubocop
+the run then does not use. And `bin` is deliberately **not** on the default
+search path (`project_paths.tool_search_path`), only on this detector's:
+`node_modules/.bin` and `.venv/bin` are directories an install keeps to
+itself, where a `bin` may hold a project's own scripts, and a script named
+after a tool should not outrank a real install beside it. Naming the
+directory on the detector keeps it in play for exactly the tools that live
+in it.
+
+## Testing
+
+`tests/conftest.py` puts `src/habit_hooks_ruby/sensors` on `sys.path` so the
+helper loads as a loose top-level module, which is how
+`${python} ${dir}/rubocop_sensor.py` loads it. Reaching it as
+`habit_hooks_ruby.sensors.rubocop_sensor` is a path no run ever takes.
+
+A missing rubocop is a `pytest.fail`, not a skip, matching every other plugin: a
+machine without it is a suite that has quietly stopped gating, not a machine
+this plugin does not apply to.
+
+The split between `test_the_rubocop_pipeline_maps_cops_to_smells.py` and
+`test_the_rubocop_sensor_runs_the_real_tool.py` is worth keeping. The first says
+what RuboCop's output *becomes* and runs no subprocess; the second proves
+RuboCop still produces output of the shape the first assumes. A RuboCop upgrade
+that renames `cop_name` or restructures `location` fails the second alone, which
+is the signal you want.

habit_hooks_ruby-1.5.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.5
+Name: habit-hooks-ruby
+Version: 1.5.0
+Summary: The Ruby Habit Hooks plugin
+Project-URL: Homepage, https://habit-hooks.com
+Project-URL: Repository, https://github.com/habit-hooks/habit-hooks
+Project-URL: Issues, https://github.com/habit-hooks/habit-hooks/issues
+Project-URL: Changelog, https://github.com/habit-hooks/habit-hooks/blob/main/CHANGELOG.md
+License-Expression: MIT
+Keywords: ai-coding-agents,ci,code-quality,code-review,code-smells,coding-agents,developer-tools,linter,refactoring,rubocop,ruby,static-analysis,technical-debt
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# habit-hooks-ruby
+
+The Ruby Habit Hooks plugin: wraps [`rubocop`](https://rubocop.org/) for
+code-smell detection. Instead of a bare offence, each finding is
+coached by listing the smell, guide for fixing, then a list of file locations.
+This causes the agent to focus on fixing the smell rather than the metric.
+
+```text
+── high-complexity (1 issue) ──
+
+High cyclomatic complexity means one function makes too many decisions at once. The count is the symptom; tangled responsibilities are the cause.
+
+**Untangle the decisions:**
+1. Lift guards out first — turn precondition checks into early returns so the happy path stays flat. Much of the count is preconditions wrapped around the real work.
+2. Change the shape of what remains: an `if`/`else` chain switching on one value is often a lookup table or polymorphism in disguise; a nested loop is often a filter/map pipeline.
+3. If the branches are genuinely separate jobs, extract one function per branch, each named for the responsibility it handles.
+
+Useful tip: describe each branch in one sentence. Two branches with the same sentence belong together; a branch you cannot name cleanly wants its own function.
+
+**AVOID**: merging conditions with and/or, or rewriting branches as ternaries, just to lower the score — the decisions remain, only the counter moves. You are done when a first-time reader can hold the whole function in their head.
+
+app/services/billing.rb:6
+```
+
+# Setup
+
+The steps are:
+
+1. Install the plugin.
+2. Enable it in your `.habit-hooks/config.toml`.
+3. Make sure you have rubocop installed.
+4. Make sure your `.rubocop.yml` enables the cops you want to see.
+
+## Install the plugin
+
+```sh
+uv tool install "habit-hooks[ruby]"   # pip and pipx work too
+```
+
+Or let setup do it: with habit-hooks already installed, `habit-hooks init` in your
+project detects ruby, names this plugin in `.habit-hooks/config.toml`, and offers to
+run the install for you — see the [Habit-Hooks README #install](https://github.com/habit-hooks/habit-hooks#install).
+
+## Enable the plugin
+
+Installing a plugin does not switch it on — it has to be named in
+`plugins` before habit-hooks runs it.
+
+```toml
+# .habit-hooks/config.toml
+plugins = ["ruby", "generic"]
+```
+
+Keep `generic` in the list. Most of the smells this plugin reports are coached
+by guides `generic` ships; without it they fall back to a short generic prompt.
+
+## Sensors: install rubocop
+
+The ruby plugin supports the rubocop sensor. It can use any rubocop on your `PATH`, but it is best to point it at the one your project uses. 
+
+Point it at your project's own rubocop:
+
+**If your `Gemfile` pins rubocop, or your `.rubocop.yml` names an extension gem
+(`rubocop-rails`, `rubocop-rspec`, `rubocop-performance`), generate binstubs:**
+
+```sh
+bundle binstubs rubocop
+```
+
+Otherwise, if you have no rubocop yet, install one:
+
+- `rubocop` — `gem install rubocop`
+
+### How it finds rubocop
+
+habit-hooks' rubocop detector searches your project's `bin/` ahead of the
+machine's `PATH`, so `bin/rubocop` is what it will run — under your bundle,
+with your extension gems loaded.
+
+Without this, habit-hooks runs whatever `rubocop` your `PATH` answers with, and
+a config naming cops that rubocop cannot load is a hard error rather than a
+lint result:
+
+```
+Error: `Rails/*` has been extracted to the `rubocop-rails` gem.
+```
+
+habit-hooks reports that as a failed run.
+
+### Configure your `.rubocop.yml`
+
+The sensor runs `rubocop` and reads what comes back.  RuboCop discovers your `.rubocop.yml`
+exactly as it does when you run rubocop by hand.  The `--force-exclusion` is the one flag
+habit-hooks adds, so your `AllCops: Exclude:` keeps applying even though habit-hooks names files
+explicitly.
+
+Cops are mapped to canonical smells and are reported under it:
+
+| Cop | Smell |
+|-----|-------|
+| `Metrics/ParameterLists` | `too-many-parameters` |
+| `Metrics/MethodLength` | `oversized-function` |
+| `Metrics/BlockLength` | `oversized-block` |
+| `Metrics/CyclomaticComplexity` | `high-complexity` |
+| `Metrics/PerceivedComplexity` | `high-complexity` |
+| `Metrics/AbcSize` | `high-complexity` |
+| `Metrics/BlockNesting` | `deep-nesting` |
+| `Lint/UselessAssignment` | `unused-variable` |
+| `Lint/SuppressedException` | `swallowed-exception` |
+| `Lint/Syntax` | `parse-error` |
+
+All other cops are **forwarded under their own name** by default.
+Recommended: add coaches for cops as needed (see [Customization](#customization)).
+Set the root `uncoached` key to `ignore` to drop these cops,
+or `enforce` to fail the run on them 
+([config.md](https://github.com/habit-hooks/habit-hooks/blob/main/docs/config.md)).
+
+#### A starting `.rubocop.yml`
+
+If you have no config yet, this turns on the structural cops this plugin maps
+and nothing else. It is a suggestion, not a default. Habit-hooks never writes
+it for you and never passes it to rubocop.
+
+```yaml
+AllCops:
+  NewCops: enable
+  Exclude:
+    - 'db/schema.rb'
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+
+Metrics/ParameterLists:
+  Max: 4
+Metrics/MethodLength:
+  Max: 20
+Metrics/CyclomaticComplexity:
+  Max: 10
+Metrics/BlockNesting:
+  Max: 3
+Lint/UselessAssignment:
+  Enabled: true
+Lint/SuppressedException:
+  Enabled: true
+```
+
+# Customization
+
+Ruby Habit Hooks is customizable without modifying the installed package. Project
+files under `.habit-hooks/ruby/` override the corresponding files shipped by the
+Ruby plugin. Commit these overrides if they are intended to apply to the whole
+project.
+
+## Add project-specific coaching
+
+Replace any Ruby guide by creating a file with the same name under
+`.habit-hooks/ruby/guides/`. For example,
+`.habit-hooks/ruby/guides/high-complexity.md` replaces the default coaching for
+the `high-complexity` smell while leaving all other guides unchanged.
+
+
+An unmapped cop forwarded under its own name can use a custom filename through the project
+config:
+
+```toml
+[smells."Style/StringLiterals"]
+guide = "style-string-literals.md"
+```
+
+Then add a guide at `.habit-hooks/ruby/guides/style-string-literals.md`. For example:
+
+```markdown
+Use the quote style established by this project. preserve interpolation and readability.
+
+{% for issue in issues -%}
+{{ issue.details.file }}:{{ issue.details.line }}
+{% endfor %}
+```
+
+Guides are Markdown Jinja templates. They can use `smell` and `language`, read
+smell-level `details`, and loop over `issues` to show each offense.  The loop in
+the example above writes the file and line of each issue (required, otherwise the
+agent will not know where the offense occurred).
+
+## Add a cop-to-smell mapping
+
+Prefer mapping a cop to an existing general smell when the guidance fits. This
+lets the project benefit from shared coaching and keeps the smell vocabulary
+small. If the cop represents a smell that should be useful beyond your project,
+consider contributing the mapping, guide, and any needed vocabulary changes in
+a pull request to the [Habit Hooks project](https://github.com/habit-hooks/habit-hooks).
+
+The built-in cop mappings live in `sensors/rubocop_report.py`, in the
+`COP_SMELLS` table.
+
+To add a mapping for a project, copy that file to
+`.habit-hooks/ruby/sensors/rubocop_report.py` and add an entry, for example:
+
+```python
+COP_SMELLS = {
+    # existing mappings ...
+    "Style/StringLiterals": "project-style",
+}
+```
+
+Because the sensor helper imports this file from its own directory, also copy
+`rubocop_sensor.py` and `rubocop.toml` to the same override directory (.habit-hooks/ruby/sensors).
+Keep the recipe in the TOML file the same; its `${dir}` then points at the override and
+loads your customized report module.
+
+If the new mapping uses an existing smell, its existing guide and severity are
+used. For a new smell, add a guide and configure its severity as needed:
+
+```toml
+[smells.project-style]
+severity = "suggested"
+```
+
+Then add `.habit-hooks/ruby/guides/project-style.md`.
+
+## Add or replace a sensor
+
+A sensor is a TOML recipe under `sensors/`. To replace the RuboCop sensor,
+override `.habit-hooks/ruby/sensors/rubocop.toml`; to add a separate sensor,
+create a new recipe such as `.habit-hooks/ruby/sensors/custom-check.toml` and
+add its name to the Ruby plugin's `sensors` list in
+`.habit-hooks/ruby/config.toml`:
+
+```toml
+sensors = ["rubocop", "custom-check"]
+```
+
+The plugin config override is a complete replacement, so copy the shipped
+Ruby `config.toml` and preserve its `language`, `files`, `transformers`, and
+`detectors` entries when adding a sensor. Declare every external command the
+sensor uses in `detectors`, and use `${detector:<name>}` in its recipe when the
+sensor invokes that command.
+
+The sensor must print a JSON array of Habit Hooks findings. See the
+[sensor interface](https://github.com/habit-hooks/habit-hooks/blob/main/docs/sensor-interface.spec.md)
+for the finding shape and available recipe placeholders.
+
+For example, a simple custom sensor returning a canned finding to demonstrate the customization.
+
+- Create
+`.habit-hooks/ruby/sensors/custom-check.toml`:
+
+```toml
+command = "${dir}/custom-check.sh"
+```
+
+- Then create the executable `.habit-hooks/ruby/sensors/custom-check.sh`:
+
+```sh
+#!/bin/sh
+printf '%s\n' '[{"smell":"custom-check","details":{},"issues":[{"key":"app/models/example.rb","details":{"file":"app/models/example.rb","line":1,"message":"Canned custom-check result","source":"custom-check"}}]}]'
+```
+
+The sensor's issue paths should be relative to the project, and its
+output must always be a JSON array of findings.
+
+- Enable it by copying the entire `plugins/ruby/src/habit_hooks_ruby/config.toml` to `.habit-hooks/ruby/config.toml` and adding `"custom-check"` to the `sensors` list in the plugin config
+override. for example:
+```
+sensors = ["rubocop", "custom-check"]  
+```