habit-hooks-python 1.0.1__tar.gz → 1.2.0__tar.gz

habit_hooks_python-1.2.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_python-1.0.1 → habit_hooks_python-1.2.0}/PKG-INFO

@@ -1,5 +1,5 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: habit-hooks-python
-Version: 1.0.1
+Version: 1.2.0
 Summary: The Python Habit Hooks plugin
 Requires-Python: >=3.11

{habit_hooks_python-1.0.1 → habit_hooks_python-1.2.0}/docs/python-plugin.spec.md

@@ -65,6 +65,112 @@ habit-sensors --all | jq 'sort_by(.smell)[] | {smell, language, key: (.issues[0]
 }
 ```
 
+## An empty scope runs no sensor, so ruff never scans the whole tree
+
+A scoped run that resolves to **zero** files measured nothing, and no sensor may
+run over it. `ruff` handed no paths falls back to its own default — scan the
+current directory — so without this guard a non-source-only change reports every
+legacy smell in the tree and fails the run (#93). Here `[files]` counts only
+`**/*.py` as source (the plugin default) and `--file README.md` names a doc, so
+the scope is empty even though `legacy.py` carries three real smells. The run
+emits `[]` and exits 0, and the scope layer still says on stderr that it scanned
+nothing.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.deptry]
+disabled = true
+```
+
+📄ruff.toml @plugins/python/src/habit_hooks_python/ruff.toml
+
+📄pyproject.toml
+```toml
+[project]
+name = "demo"
+version = "0.0.0"
+```
+
+📄legacy.py
+```python
+import os
+
+
+def charge(a, b, c, d):
+    unused = 1
+    return a + b + c + d
+```
+
+📄README.md
+```text
+# docs
+```
+
+```bash
+habit-sensors --file README.md
+```
+
+🖥️ ✅
+```json
+[]
+```
+
+🚨
+```text
+habit-sensors: --file 'README.md' is outside [files]; nothing scanned
+```
+
+## A sensor narrowed to no files is as empty a scope as a run with none
+
+`[sensors.<name>] files` narrows the run's scope for that sensor alone, and it
+can leave that sensor nothing while the run as a whole still measured something.
+Its scope is then as empty as the case above's, with the same consequence — so
+the guard is asked per sensor, not once for the run. Here `legacy.py` is in
+scope and carries three real smells, but `ruff` is narrowed to `src/**/*.py`,
+which holds none of them: ruff never runs, and never falls back to scanning the
+tree it was steered away from.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["python"]
+
+[sensors.ruff]
+files = ["src/**/*.py"]
+
+[sensors.deptry]
+disabled = true
+```
+
+📄ruff.toml @plugins/python/src/habit_hooks_python/ruff.toml
+
+📄pyproject.toml
+```toml
+[project]
+name = "demo"
+version = "0.0.0"
+```
+
+📄legacy.py
+```python
+import os
+
+
+def charge(a, b, c, d):
+    unused = 1
+    return a + b + c + d
+```
+
+```bash
+habit-sensors --all
+```
+
+🖥️ ✅
+```json
+[]
+```
+
 ## ruff maps a syntax error to parse-error
 
 A file ruff cannot parse surfaces as `parse-error` (ruff reports it as
@@ -152,7 +258,13 @@ deptry needs a `pyproject.toml` to analyse; without one it exits non-zero
 instead of emitting findings. The sensor must surface that as a failure — a
 crashed tool is never a clean run. The sensor exits with a code outside the
 findings range, so `habit-sensors` raises, names the sensor on stderr, and exits
-1 rather than printing an empty (false-clean) result.
+1 rather than printing an empty (false-clean) result. The failed run carries only
+the reserved `incomplete-run` marker on stdout
+([habit-sensors.spec.md](../../../docs/habit-sensors.spec.md)).
+
+The notice carries deptry's own diagnosis after that first line. That text is
+deptry's to word and names absolute paths, so only the line naming the sensor is
+asserted here.
 
 📄.habit-hooks/config.toml
 ```toml
@@ -169,15 +281,19 @@ def fetch(url):
 ```
 
 ```bash
-habit-sensors --all
+habit-sensors --all | jq -c '[.[].smell]'
 ```
 
 🖥️ ❌ 1
 ```json
-[]
+["incomplete-run"]
 ```
 
-🚨
+```bash
+habit-sensors --all 2>&1 >/dev/null | sed -n 1p
+```
+
+🖥️ ❌ 1
 ```text
 habit-sensors: sensor 'deptry' failed: ${python} ${dir}/deptry_sensor.py
 ```
@@ -189,7 +305,8 @@ The `ruff` sensor pipes the tool into `jq`. A crashing `ruff` (here, a malformed
 naive pipe would let `jq` succeed on empty input and mask the crash as a false-
 clean run. The command sets `pipefail` so the tool's failing exit propagates
 through the pipe; `habit-sensors` then raises, names the sensor on stderr, and
-exits 1.
+exits 1, carrying only the reserved `incomplete-run` marker on stdout
+([habit-sensors.spec.md](../../../docs/habit-sensors.spec.md)).
 
 📄.habit-hooks/config.toml
 ```toml
@@ -210,40 +327,24 @@ import os
 ```
 
 ```bash
-habit-sensors --all
+habit-sensors --all | jq -c '[.[].smell]'
 ```
 
 🖥️ ❌ 1
 ```json
-[]
+["incomplete-run"]
 ```
 
-🚨
+The notice quotes the sensor's whole command — multi-line here, so its first
+line shows only where that command starts — and then ruff's own diagnosis, which
+names the absolute path of the config it could not parse. Only the line naming
+the sensor is stable enough to assert.
+
+```bash
+habit-sensors --all 2>&1 >/dev/null | sed -n 1p
+```
+
+🖥️ ❌ 1
 ```text
 habit-sensors: sensor 'ruff' failed: set -o pipefail
-ruff check --output-format=json --select=C901,PLR0913,PLR0915,F841,F401,BLE001 ${files} | jq '
-  map(. + {smell: ({
-    "C901": "high-complexity",
-    "PLR0913": "too-many-parameters",
-    "PLR0915": "oversized-function",
-    "F841": "unused-variable",
-    "F401": "unused-import",
-    "BLE001": "swallowed-exception",
-    "invalid-syntax": "parse-error"
-  }[.code])})
-  | group_by(.smell)
-  | map({
-      smell: .[0].smell,
-      details: {},
-      issues: map({
-        key: .filename,
-        details: {
-          file: .filename,
-          line: .location.row,
-          column: .location.column,
-          message: .message,
-          source: ("ruff:" + .code)
-        }
-      })
-    })'
 ```

{habit_hooks_python-1.0.1 → habit_hooks_python-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "habit-hooks-python"
-version = "1.0.1"
+version = "1.2.0"
 description = "The Python Habit Hooks plugin"
 requires-python = ">=3.11"
 dependencies = []

habit_hooks_python-1.2.0/src/habit_hooks_python/config.toml

@@ -0,0 +1,16 @@
+# Python plugin defaults.
+language = "python"
+# 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. An installed package is
+# never the project's source; `site-packages` is where one lands whatever the
+# environment is called, so it answers for a `venv/` as well as a `.venv/`.
+files = ["**/*.py", "!**/site-packages/**", "!**/.venv/**", "!**/venv/**"]
+sensors = ["ruff", "deptry"]
+transformers = []
+
+# The ruff sensor pipes its JSON through jq, so a python-only project needs it.
+detectors = [
+  { name = "ruff", kind = "command", install = "pip install ruff" },
+  { name = "deptry", kind = "command", install = "pip install deptry" },
+  { name = "jq", kind = "command", install = "brew install jq" },
+]

{habit_hooks_python-1.0.1 → habit_hooks_python-1.2.0}/src/habit_hooks_python/guides/high-complexity.md

@@ -1,6 +1,5 @@
 High cyclomatic complexity means one function is making too many decisions at once. The smell is not the number, it is that the function has quietly taken on more than one job. The count is the symptom, tangled responsibilities are the cause.
 
-{% include "includes/line_level_issues.md" %}
 Work through it in order:
 
 1. **Name what each branch is for.** Give every branch a one-sentence description of the responsibility it handles. If two branches describe the same thing, they belong together. If a branch has no clean name, that path probably wants its own function.
@@ -10,3 +9,5 @@ Work through it in order:
 Reducing the number without reducing the tangle is not a fix. Do not merge conditions with `and`/`or` just to drop a branch, and do not rewrite `if` statements as ternaries to slip under the check. ruff's mccabe does not count ternary expressions, so that trick lowers the score while a human still has to hold every condition in their head.
 
 The test is not whether the number dropped. It is whether someone reading the function for the first time can hold it in their head at once. If not, it is still doing too much.
+
+{% include "includes/line_level_issues.md" %}

{habit_hooks_python-1.0.1 → habit_hooks_python-1.2.0}/src/habit_hooks_python/guides/swallowed-exception.md

@@ -1,6 +1,5 @@
 A broad `except` (`except:`, `except Exception`, `except BaseException`) that discards the error silently is hiding a failure you have not understood, not handling one you planned for. Before you write it, name the specific error you expect and why. That one sentence is usually the fix.
 
-{% include "includes/line_level_issues.md" %}
 Work through it in order:
 
 1. **Catch only what you can name.** `ValueError`, `KeyError`, `TimeoutError`, whatever the call really raises. If you cannot name it, you are guessing, and every other error should stay free to surface where someone can see it.
@@ -10,3 +9,5 @@ Work through it in order:
 Narrowing the type or adding `# noqa` only to quiet ruff is not a fix if the error is still discarded.
 
 If you are unsure whether this catch is a real decision or a reflex, check with a human before you keep it.
+
+{% include "includes/line_level_issues.md" %}

{habit_hooks_python-1.0.1 → habit_hooks_python-1.2.0}/src/habit_hooks_python/sensors/deptry_sensor.py

@@ -15,11 +15,22 @@ from pathlib import Path
 
 
 def run_deptry(report: Path) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        ["deptry", ".", "--json-output", str(report)],
-        capture_output=True,
-        text=True,
-    )
+    """What deptry said, or what a shell says about a deptry nobody installed.
+
+    ``pip install habit-hooks-python`` brings neither detector with it, so this
+    is the ordinary state of a machine that has just enabled the plugin — and an
+    absent tool raised a ``FileNotFoundError`` out of here, making twenty lines
+    of Python internals the sensor's diagnosis (#114). This wrapper is what looks
+    for deptry, so it answers the way the shell would have, and that phrase is
+    what the run recognises to name the missing tool.
+    """
+    command = ["deptry", ".", "--json-output", str(report)]
+    try:
+        return subprocess.run(command, capture_output=True, text=True)
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(
+            command, 127, "", "deptry: command not found\n"
+        )
 
 
 def deptry_crashed(result: subprocess.CompletedProcess[str], report: Path) -> bool:

habit_hooks_python-1.2.0/tests/test_a_deptry_nobody_installed_is_named.py

@@ -0,0 +1,35 @@
+"""A detector this plugin does not bring with it must still answer in one line.
+
+``pip install habit-hooks-python`` installs neither ruff nor deptry, so a machine
+that has just enabled the plugin is the ordinary case, not the edge one. The ruff
+sensor is a shell command, so the shell answers for it; deptry is spawned from
+Python, where an absent tool is a ``FileNotFoundError`` and twenty lines of
+internals would otherwise become the sensor's diagnosis (#114).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+SENSOR = (
+    Path(__file__).resolve().parents[1]
+    / "src/habit_hooks_python/sensors/deptry_sensor.py"
+)
+
+
+def test_a_deptry_nobody_installed_answers_the_way_a_shell_does(
+    tmp_path: Path,
+) -> None:
+    result = subprocess.run(
+        [sys.executable, str(SENSOR)],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        env={"PATH": "/nonexistent"},
+    )
+
+    assert result.returncode != 0
+    assert result.stdout.strip() == ""
+    assert result.stderr.strip() == "deptry: command not found"

habit_hooks_python-1.2.0/tests/test_the_python_files_leave_installed_packages_alone.py

@@ -0,0 +1,51 @@
+"""What this plugin means when it says which files are its language's.
+
+A project that names no ``files`` of its own scans what its plugins declare, and
+``habit-hooks init`` writes exactly such a config — so what is declared here *is*
+the first run for anyone init set up. A bare ``**/*.py`` reaches into the
+project's virtualenv and reports on every installed package, which buries the
+project's own findings under thousands that are nobody's to fix.
+
+``site-packages`` is where an installed package lands whatever the environment is
+called, so it answers for a ``venv/`` as well as a ``.venv/``.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+import pathspec
+
+PACKAGE = Path(__file__).resolve().parents[1] / "src" / "habit_hooks_python"
+
+PROJECT_SOURCE = ("src/billing.py", "tests/test_billing.py", "conftest.py")
+DEPENDENCIES = (
+    ".venv/lib/python3.12/site-packages/attrs/__init__.py",
+    "venv/lib/python3.11/site-packages/jinja2/environment.py",
+    ".tox/py312/lib/python3.12/site-packages/pytest/__init__.py",
+    # Not under site-packages, so only the environment's own name excludes these
+    # — and it is spelled both ways about equally often.
+    ".venv/bin/activate_this.py",
+    "venv/bin/activate_this.py",
+)
+
+
+def _declared_files() -> pathspec.PathSpec:
+    config = tomllib.loads((PACKAGE / "config.toml").read_text(encoding="utf-8"))
+    return pathspec.PathSpec.from_lines("gitignore", config["files"])
+
+
+def test_the_project_s_own_python_is_source() -> None:
+    spec = _declared_files()
+
+    assert [path for path in PROJECT_SOURCE if spec.match_file(path)] == list(
+        PROJECT_SOURCE
+    )
+
+
+def test_an_installed_package_is_not_this_project_s_source() -> None:
+    """Under either name a virtualenv usually goes by."""
+    spec = _declared_files()
+
+    assert [path for path in DEPENDENCIES if spec.match_file(path)] == []

habit_hooks_python-1.0.1/.gitignore

@@ -1,20 +0,0 @@
-# Per-plugin Node tool deps (installed via npm ci; see plugins/*/package.json)
-node_modules/
-dist
-coverage
-.DS_Store
-.idea
-.claude-channel/
-*.tgz
-*.log
-.vscode/
-.venv/
-__pycache__/
-*.pyc
-.pytest_cache/
-.spec-runs/
-
-/ruff.toml
-
-# Workflow orchestration script (run from ~/.claude, never a repo deliverable)
-.claude/workflows-build-overnight.js

habit_hooks_python-1.0.1/src/habit_hooks_python/config.toml

@@ -1,5 +0,0 @@
-# Python plugin defaults.
-language = "python"
-files = ["**/*.py"]
-sensors = ["ruff", "deptry"]
-transformers = []