habit-hooks-ruby 1.5.0__py3-none-any.whl

habit_hooks_ruby/__init__.py

@@ -0,0 +1 @@
+"""The ruby Habit Hooks plugin: package data discovered via the habit_hooks.plugins entry point."""

habit_hooks_ruby/config.toml

@@ -0,0 +1,47 @@
+# Ruby plugin defaults.
+language = "ruby"
+# A project naming no `files` of its own scans what its plugins declare, so this
+# is the first run for anyone `habit-hooks init` set up. Ruby keeps source in
+# files RuboCop already lints without an extension between them — a Rakefile, a
+# Gemfile and a gemspec are Ruby, and a project's own cops apply to them.
+#
+# The exclusions name Ruby's own source shapes one by one — every included
+# shape needs its own negative, or it leaks back in: an installed gem ships
+# its own `Rakefile` and `.gemspec`, and Rails' scratch directory copies
+# whatever it scratches. They still never name the whole directory, because a
+# plugin's exclusions bind the union of every active plugin's globs, not just
+# its own (docs/config.md, and the comment in the java plugin's config that a
+# bare `!**/build/**` once stopped a python+java project scanning its own
+# `scripts/build/*.py`). `vendor/` is where Bundler puts installed gems and
+# `tmp/` is Rails' scratch directory: Ruby the project did not write. Rails
+# generates `db/schema.rb`, so it is nobody's to fix by hand.
+files = [
+  "**/*.rb",
+  "**/*.rake",
+  "**/Rakefile",
+  "**/Gemfile",
+  "**/*.gemspec",
+  "!**/vendor/**/*.rb",
+  "!**/vendor/**/*.rake",
+  "!**/vendor/**/Rakefile",
+  "!**/vendor/**/Gemfile",
+  "!**/vendor/**/*.gemspec",
+  "!**/tmp/**/*.rb",
+  "!**/tmp/**/*.rake",
+  "!**/tmp/**/Rakefile",
+  "!**/tmp/**/Gemfile",
+  "!**/tmp/**/*.gemspec",
+  "!**/db/schema.rb",
+]
+sensors = ["rubocop"]
+transformers = []
+
+# The rubocop sensor spawns the rubocop binary directly. `bundle binstubs
+# rubocop` puts the project's own copy at `bin/rubocop`, and for a
+# `.rubocop.yml` naming extension gems, the project's copy is the only one that
+# can read it (see this plugin's README). `bin` is not on the default search
+# path — a project may keep its own scripts under a name like that — so the
+# detector names it, and only the lookups for rubocop search it.
+detectors = [
+  { name = "rubocop", kind = "command", install = "gem install rubocop", search_paths = ["bin"] },
+]

habit_hooks_ruby/guides/oversized-block.md

@@ -0,0 +1,9 @@
+A block that has grown past a dozen lines almost always has more than one responsibility, and that is the smell to chase, not the line count itself.
+
+Analyse responsibilities first: what distinct concerns does this block handle? Do these concerns belong in methods? Is the block a candidate for a method on a class?
+
+Find true responsibility boundaries rather than splitting at the threshold: `apply_part_one` / `apply_part_two` carved off to fit the line count is one responsibility wearing two names.
+
+A concrete technique: write what the block does in one short sentence and refactor until the code reads as close to it as possible. If you cannot say what it does in one sentence, it almost certainly does more than one thing.
+
+{% include "includes/line_level_issues.md" %}

habit_hooks_ruby/guides/parse-error.md

@@ -0,0 +1,7 @@
+A fatal parse error means RuboCop could not analyse the file at all, so every other cop went unchecked there too. Real issues in this file are currently invisible.
+
+Check, in order: a syntax error (`ruby -c <file>` names the line); a `TargetRubyVersion` in `.rubocop.yml` older than the syntax the file uses (pattern matching or endless methods under a 2.x target); a generated file that is not valid Ruby.
+
+You've fixed it when a deliberate change to the file produces the ordinary offence you'd expect, since that proves analysis is running again. Keep the file in the lint set: it is exactly the file most in need of the other cops.
+
+{% include "includes/file_level_issues.md" %}

habit_hooks_ruby/sensors/rubocop.toml

@@ -0,0 +1 @@
+argv = ["${python}", "${dir}/rubocop_sensor.py", "${detector:rubocop}", "${files}"]

habit_hooks_ruby/sensors/rubocop_report.py

@@ -0,0 +1,110 @@
+"""RuboCop's JSON report, parsed and shaped into the canonical findings.
+
+RuboCop's own JSON nests offences under each file; this flattens them, groups by
+smell and shapes each into the canonical finding.
+
+**An unmapped cop is forwarded, not dropped**, which is the opposite of the knip
+sensor and the same as the eslint one. CLAUDE.md's test for a wrapped tool is
+"whose vocabulary is it?" Knip's key set is knip's own, but a cop that fired is
+one the project's ``.rubocop.yml`` turned on, so forwarding it saves running
+RuboCop separately. Its smell key is the cop name verbatim
+(``Style/StringLiterals``). A ``/`` in a smell key is already precedented by
+eslint forwarding ``@typescript-eslint/no-explicit-any``. Nothing downstream
+breaks on one. An uncatalogued smell renders through ``uncoached.md``, and the
+root ``uncoached`` key (default ``suggest``) decides whether it fails the run.
+
+``Metrics/ClassLength`` and ``Metrics/ModuleLength`` are the two cops
+deliberately left uncoached: they measure a class or module, and the vocabulary
+has no class-scoped smell for them to back. Like every unmapped cop they are
+forwarded under their own names and rendered through ``uncoached.md``,
+``suggest`` until a class and module scoped coach exists.
+
+The three complexity cops share one smell on purpose. They are correlated but
+independent. A method tripping two cops keeps both measurements inside a single coaching
+block.
+
+``Metrics/BlockLength`` maps to its own smell rather than to
+``oversized-function``: a block is an anonymous function the project never
+named, and its coaching (name the work as a method, let the declaration point
+at it) differs enough from a method's to warrant the ruby plugin's own guide.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+COP_SMELLS = {
+    "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",
+}
+
+
+def report(result: subprocess.CompletedProcess[str]) -> dict | None:
+    """RuboCop's JSON report, or ``None`` where it produced none.
+
+    ``files`` has to be there, not merely valid JSON. That key is what makes it
+    a report rather than something else that happens to parse.
+    """
+    text = result.stdout.strip()
+    if not text:
+        return None
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) and "files" in parsed else None
+
+
+def offenses(parsed: dict) -> list[dict]:
+    """RuboCop's per-file nesting flattened, each offence carrying its path."""
+    return [
+        {"file": entry["path"], "offense": offense}
+        for entry in parsed.get("files", [])
+        for offense in entry["offenses"]
+    ]
+
+
+def smell_of(cop_name: str) -> str:
+    """This plugin's smell for a cop, or the cop itself where it has none.
+
+    ``.get`` with the cop as its own default, never a bare lookup. The string
+    comes from RuboCop and nothing constrains it to the table above (issue #83).
+    """
+    return COP_SMELLS.get(cop_name, cop_name)
+
+
+def issue(entry: dict) -> dict:
+    offense = entry["offense"]
+    return {
+        "key": entry["file"],
+        "details": {
+            "file": entry["file"],
+            "line": offense["location"]["line"],
+            "column": offense["location"]["column"],
+            "message": offense["message"],
+            "source": "rubocop:" + offense["cop_name"],
+        },
+    }
+
+
+def findings(entries: list[dict]) -> list[dict]:
+    by_smell: dict[str, list[dict]] = {}
+    for entry in entries:
+        by_smell.setdefault(smell_of(entry["offense"]["cop_name"]), []).append(entry)
+    return [
+        {
+            "smell": smell,
+            "details": {},
+            "issues": [issue(entry) for entry in by_smell[smell]],
+        }
+        for smell in sorted(by_smell)
+    ]

habit_hooks_ruby/sensors/rubocop_sensor.py

@@ -0,0 +1,159 @@
+"""Run RuboCop and print canonical findings, mapped from cop name to smell.
+
+**Which cops run is the project's business, not ours.** The sensor passes no
+``--only`` and no ``--config``. RuboCop finds ``.rubocop.yml`` by walking up from
+each inspected file, exactly as it does when run by hand, so a project's habit-
+hooks run is the run it gets from the tool directly. ``--force-exclusion`` is the
+one flag that keeps that true. Without it, naming files on the command line
+overrides the project's own ``AllCops: Exclude:``.
+
+Parsing and shaping live next door in ``rubocop_report``, a neighbour imported
+as a top-level module because a helper runs as a loose script — the interpreter
+puts the helper's own directory first on ``sys.path`` (CLAUDE.md, "A plugin
+helper imports its neighbours as top-level modules").
+
+The plugin ships no RuboCop of its own, so the sensor names ``${detector:rubocop}``
+and its ``sys.argv[1]`` is the file this project runs for it, and the scoped
+files follow. A rubocop nobody installed never reaches here at all. The part
+has no file for it, so the run answers with the missing-command notice before
+anything is spawned.
+
+**A scope filename is a name, never an option or a pattern.** RuboCop reads its
+file arguments both ways, and the argv guards each: ``--`` ends option parsing
+before any file is named, and :func:`literal_spelling_of` escapes the glob
+metacharacters RuboCop would otherwise expand.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+
+from rubocop_report import findings, offenses, report
+
+# RuboCop's own contract: 0 is clean, 1 is "offences found". Anything else
+# means RuboCop never produced a real report, the same distinction
+# `part_output.py`'s TOOL_EXIT_CODES draws for a part run directly.
+#
+# The exit code alone is not enough here, which is a Ruby problem rather than a
+# RuboCop one. `rubocop` is a RubyGems binstub with a `#!/usr/bin/env ruby`
+# shebang, so it is only as good as the `ruby` that answers first. Point it at
+# an interpreter whose gems it is not installed into, whether a version
+# manager left off PATH, the wrong bundle, or 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". Trusting that would report a rubocop that
+# never started as a clean file (#88).
+#
+# So the report is the evidence, not the code. `--format json` prints the
+# envelope on every run RuboCop actually completed, down to `"files": []` when
+# it inspected nothing. No report means no run.
+TOOL_EXIT_CODES = (0, 1)
+
+# The characters `Dir[]` reads as a pattern rather than a name. RuboCop hands
+# an argument to `Dir[]` only when it contains a `*` (see
+# `literal_spelling_of`), so these matter only inside an argument that does.
+_GLOB_METACHARACTERS = re.compile(r"[*?\[\]{}\\]")
+
+
+def literal_spelling_of(path: str) -> str:
+    """A scope filename spelled so RuboCop reads it as the file it names.
+
+    RuboCop globs any argument containing a ``*`` —
+    ``TargetFinder#process_explicit_path`` passes it to ``Dir[]`` — so a
+    literal star would sweep in every file it matches. A backslash is ``Dir[]``'s
+    own escape for "this character, literally", which leaves the escaped
+    string still containing a ``*`` for RuboCop to notice and hand to ``Dir[]``
+    in the first place.
+
+    The other metacharacters are escaped only inside such an argument. A path
+    without a ``*`` RuboCop takes verbatim, backslashes included, so escaping a
+    ``?`` there would name a file that does not exist and the run would die on
+    ``Error: No such file or directory``.
+    """
+    if "*" not in path:
+        return path
+    return _GLOB_METACHARACTERS.sub(r"\\\g<0>", path)
+
+
+def run_rubocop(rubocop: str, files: list[str]) -> subprocess.CompletedProcess[str]:
+    """What RuboCop said, spawned as the file this sensor was handed for it.
+
+    The file rather than the name. A name would be looked up again by the
+    spawn, and Windows' own lookup adds ``.exe`` and nothing else, where
+    RubyGems installs a ``.bat`` shim.
+
+    ``--force-exclusion`` is not a nicety. RuboCop applies ``AllCops: Exclude:``
+    to the files it discovers, but a file named explicitly on the command line
+    is taken as a deliberate request and linted anyway. Without it, a
+    project's own exclusions stop meaning anything the moment habit-hooks passes
+    a scope.
+
+    ``--`` ends option parsing before the files, so a valid filename beginning
+    with ``-`` is a file rather than a pile of short options — ``-c`` among them,
+    which takes the rest as its ``--config`` value.
+
+    ``--raise-cop-error`` is what makes a cop that raises an ``Error:`` and
+    exit 2, detectable by habit-hooks as a failed run. A run with offences
+    and no crash is untouched, they exit 1 with a valid envelope.
+    """
+    return subprocess.run(
+        [
+            rubocop,
+            "--format",
+            "json",
+            "--force-exclusion",
+            "--raise-cop-error",
+            "--",
+            *[literal_spelling_of(file) for file in files],
+        ],
+        capture_output=True,
+        encoding="utf-8",
+        errors="replace",  # sensors.spawn's policy
+    )
+
+
+def rubocop_crashed(
+    result: subprocess.CompletedProcess[str], parsed: dict | None
+) -> bool:
+    """Whether this run is one whose answer can be believed.
+
+    Both halves are needed. The exit code catches the failures RuboCop reports
+    as failures; the missing report catches the one it cannot: a binstub that
+    never reached RuboCop at all, which exits 1 like a run full of offences
+    (see :data:`TOOL_EXIT_CODES`).
+
+    The report is passed in rather than parsed here so that this is the only
+    place the rule is written. :func:`main` needs the parsed report anyway, and
+    a version of this that re-derived it would be a second copy of the decision,
+    free to drift from the one the tests exercise.
+    """
+    return result.returncode not in TOOL_EXIT_CODES or parsed is None
+
+
+def main() -> int:
+    rubocop = sys.argv[1]
+    files = sys.argv[2:]
+    # A scope that resolved to nothing measured nothing, and RuboCop handed no
+    # paths falls back to its own default and scans everything under the
+    # current directory. Without this guard a docs-only change reports every
+    # legacy smell in the tree and fails the run (#93).
+    if not files:
+        print("[]")
+        return 0
+    result = run_rubocop(rubocop, files)
+    parsed = report(result)
+    if rubocop_crashed(result, parsed):
+        # `or result.stdout`: a binstub that could not find its own gem writes
+        # its traceback to stderr, but a RuboCop that failed on the config
+        # writes `Error: ...` to stdout. Whichever one it is, the tool's own
+        # words are the only thing the reader can act on.
+        sys.stderr.write(result.stderr or result.stdout)
+        return 2
+    print(json.dumps(findings(offenses(parsed))))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

habit_hooks_ruby-1.5.0.dist-info/METADATA

@@ -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"]  
+```

habit_hooks_ruby-1.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+habit_hooks_ruby/__init__.py,sha256=IDQkTs3XygPeFrj24uTPDXiU165SPzfjWddf4QFrCAk,100
+habit_hooks_ruby/config.toml,sha256=HPAT3pBTy8PVt3n094T_Rw_U96b1-5aXd_GuPR-YrsM,2072
+habit_hooks_ruby/guides/oversized-block.md,sha256=Siy5k3RC9rNsE0LTD5I5OpHu7Y-eTnQqiwMZt0zBQUk,777
+habit_hooks_ruby/guides/parse-error.md,sha256=ZGJijGB9_YX2w1bXJfkG8IxV6lIdAOL3V1TwThkqYlA,683
+habit_hooks_ruby/sensors/rubocop.toml,sha256=uH-Vb_xiubtU0ZirIWS7dX1_XQg3iqHI_ngMHlEYBHY,84
+habit_hooks_ruby/sensors/rubocop_report.py,sha256=d8xFDVHBvuaUZJmCFCUN0xb_vKGAPUSZ0lqoS3insmU,4215
+habit_hooks_ruby/sensors/rubocop_sensor.py,sha256=OckPokxoOQIGJTDN8J2pDcu0MjSewiXIh839s5Y_ucA,7045
+habit_hooks_ruby-1.5.0.dist-info/METADATA,sha256=KxMhBYeBLV1UWVUeSCrI8S5d5VGFZBrZee9YCBa5EsI,10827
+habit_hooks_ruby-1.5.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+habit_hooks_ruby-1.5.0.dist-info/entry_points.txt,sha256=kC7UTDgDJIj_h_d9uO18B6H66q0l97MW8aqPJrK_vP4,46
+habit_hooks_ruby-1.5.0.dist-info/RECORD,,

habit_hooks_ruby-1.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

habit_hooks_ruby-1.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[habit_hooks.plugins]
+ruby = habit_hooks_ruby