habit-hooks-php 1.0.0__tar.gz

habit_hooks_php-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# 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_php-1.0.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: habit-hooks-php
+Version: 1.0.0
+Summary: The PHP Habit Hooks plugin
+Requires-Python: >=3.11

habit_hooks_php-1.0.0/docs/php-plugin.spec.md

@@ -0,0 +1,120 @@
+# The php plugin — acceptance
+
+The php plugin runs its sensor through the real `habit-sensors` pipeline. These
+cases run the **actual** tool (PHPMD, bundled as a `.phar` next to the sensor)
+against a fixture with a known smell and assert the canonical finding comes out,
+mapped to the smell keys in [smell-vocabulary.md](smell-vocabulary.md).
+
+`habit-sensors` is the installed CLI; `php` is on the system `PATH`. The sensor
+runs `php phpmd.phar` with PHP error reporting silenced (PHP's deprecation
+notices would otherwise leak onto the JSON stdout) and normalises PHPMD's
+exit-2-on-violations into a clean run.
+
+📄.habit-hooks/config.toml
+```toml
+plugins = ["php"]
+```
+
+## phpmd sensor maps rule names to canonical smells
+
+The `phpmd` sensor runs PHPMD with the `codesize,unusedcode` rulesets and shapes
+each violation into one finding per smell, stamping `source: "phpmd:<rule>"` on
+each issue. An eleven-parameter function trips `ExcessiveParameterList` →
+`too-many-parameters`, and its dead local trips `UnusedLocalVariable` →
+`unused-variable`.
+
+📄billing.php
+```php
+<?php
+function charge($a, $b, $c, $d, $e, $f, $g, $h, $i, $j, $k) {
+    $unused = 1;
+    return $a + $b + $c + $d + $e + $f + $g + $h + $i + $j + $k;
+}
+```
+
+```bash
+habit-sensors --all | jq 'sort_by(.smell)[] | {smell, language, key: (.issues[0].key | sub(".*/"; "")), line: .issues[0].details.line, source: .issues[0].details.source}'
+```
+
+🖥️ ✅
+```json
+{
+  "smell": "too-many-parameters",
+  "language": "php",
+  "key": "billing.php",
+  "line": 2,
+  "source": "phpmd:ExcessiveParameterList"
+}
+{
+  "smell": "unused-variable",
+  "language": "php",
+  "key": "billing.php",
+  "line": 3,
+  "source": "phpmd:UnusedLocalVariable"
+}
+```
+
+## phpmd sensor maps a deeply-branched function to high-complexity
+
+A function with a dozen independent branches exceeds PHPMD's cyclomatic
+complexity threshold, tripping `CyclomaticComplexity` → `high-complexity`.
+PHPMD's overlapping `NPathComplexity` is intentionally not mapped, so the same
+function reports a single smell.
+
+📄report.php
+```php
+<?php
+function classify($n) {
+    if ($n == 1) return 1;
+    if ($n == 2) return 2;
+    if ($n == 3) return 3;
+    if ($n == 4) return 4;
+    if ($n == 5) return 5;
+    if ($n == 6) return 6;
+    if ($n == 7) return 7;
+    if ($n == 8) return 8;
+    if ($n == 9) return 9;
+    if ($n == 10) return 10;
+    if ($n == 11) return 11;
+    return 0;
+}
+```
+
+```bash
+habit-sensors --all | jq '.[] | {smell, language, source: .issues[0].details.source}'
+```
+
+🖥️ ✅
+```json
+{
+  "smell": "high-complexity",
+  "language": "php",
+  "source": "phpmd:CyclomaticComplexity"
+}
+```
+
+## A crashing phpmd fails the run, never reports clean
+
+PHPMD exits non-zero on a file it cannot parse. The sensor surfaces that as a
+failure — a crashed tool is never a clean run. It 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.
+
+📄broken.php
+```php
+<?php function ( {
+```
+
+```bash
+habit-sensors --all
+```
+
+🖥️ ❌ 1
+```json
+[]
+```
+
+🚨
+```text
+habit-sensors: sensor 'phpmd' failed: python ${dir}/phpmd_sensor.py ${files}
+```

habit_hooks_php-1.0.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "habit-hooks-php"
+version = "1.0.0"
+description = "The PHP Habit Hooks plugin"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.entry-points."habit_hooks.plugins"]
+php = "habit_hooks_php"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/habit_hooks_php"]
+artifacts = ["src/habit_hooks_php/sensors/phpmd.phar"]

habit_hooks_php-1.0.0/src/habit_hooks_php/__init__.py

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

habit_hooks_php-1.0.0/src/habit_hooks_php/config.toml

@@ -0,0 +1,5 @@
+# PHP plugin defaults.
+language = "php"
+files = ["**/*.php"]
+sensors = ["phpmd"]
+transformers = []

habit_hooks_php-1.0.0/src/habit_hooks_php/guides/unused-variable.md

@@ -0,0 +1,4 @@
+{% include "includes/line_level_issues.md" %}
+An unused local variable is dead weight: the reader has to prove to themselves it does not matter. It usually signals one of three things — a computation whose result is never consumed (delete the computation, not just the assignment), a leftover from a refactor that moved logic elsewhere, or a value you meant to use and forgot to wire in (the real bug).
+
+Decide which it is before deleting. If the right-hand side has side effects you still need, keep the call but drop the binding. If it was meant to be returned or passed on, finish that thread rather than silencing the warning. Suppressing it with a throwaway name hides the question instead of answering it.

habit_hooks_php-1.0.0/src/habit_hooks_php/sensors/phpmd.toml

@@ -0,0 +1 @@
+command = "python ${dir}/phpmd_sensor.py ${files}"

habit_hooks_php-1.0.0/src/habit_hooks_php/sensors/phpmd_sensor.py

@@ -0,0 +1,91 @@
+"""Run PHPMD and print canonical smell findings.
+
+PHPMD exits 2 when it finds violations and 1 on a real error, so a bare pipe
+cannot tell a clean run from a crash. This wrapper runs PHPMD against the scoped
+files, treats only 0/2 as success, and shapes each rule into the canonical
+finding, mapping PHPMD rule names to smell keys.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+RULE_SMELLS = {
+    "ExcessiveParameterList": "too-many-parameters",
+    "CyclomaticComplexity": "high-complexity",
+    "ExcessiveMethodLength": "oversized-function",
+    "UnusedLocalVariable": "unused-variable",
+}
+
+RULESETS = "codesize,unusedcode"
+SUCCESS_EXIT_CODES = (0, 2)
+
+
+def run_phpmd(files: list[str]) -> subprocess.CompletedProcess[str]:
+    phar = str(Path(__file__).with_name("phpmd.phar"))
+    command = [
+        "php",
+        "-d",
+        "error_reporting=0",
+        "-d",
+        "display_errors=0",
+        phar,
+        ",".join(files),
+        "json",
+        RULESETS,
+    ]
+    return subprocess.run(command, capture_output=True, text=True)
+
+
+def violations(report: dict) -> list[dict]:
+    return [
+        {"file": file["file"], "violation": violation}
+        for file in report.get("files", [])
+        for violation in file["violations"]
+    ]
+
+
+def issue(entry: dict) -> dict:
+    violation = entry["violation"]
+    return {
+        "key": entry["file"],
+        "details": {
+            "file": entry["file"],
+            "line": violation["beginLine"],
+            "message": violation["description"],
+            "source": "phpmd:" + violation["rule"],
+        },
+    }
+
+
+def findings(entries: list[dict]) -> list[dict]:
+    by_smell: dict[str, list[dict]] = {}
+    for entry in entries:
+        smell = RULE_SMELLS.get(entry["violation"]["rule"])
+        if smell is not None:
+            by_smell.setdefault(smell, []).append(issue(entry))
+    return [
+        {"smell": smell, "details": {}, "issues": issues}
+        for smell, issues in by_smell.items()
+    ]
+
+
+def main() -> int:
+    files = sys.argv[1:]
+    if not files:
+        print("[]")
+        return 0
+    result = run_phpmd(files)
+    if result.returncode not in SUCCESS_EXIT_CODES:
+        sys.stderr.write(result.stderr or result.stdout)
+        return 2
+    report = json.loads(result.stdout)
+    print(json.dumps(findings(violations(report))))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())