code-auditor-mcp 3.4.18 → 3.5.0

package/plugin/scripts/hook-self-audit.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# code-auditor PostToolUse self-audit hook — enforce the self-audit scope
+# (analyzers/ + languages/) at edit time, not just at release (Spec 33 Item 15).
+#
+# Reads the PostToolUse event JSON from stdin, extracts the edited file path,
+# and — only when that file is production source in the self-audit scope — runs
+# `code-audit self-audit --stdin --json` against it. Exit code 2 blocks the edit
+# and feeds the finding JSON back to the agent.
+#
+# This hook is a no-op for every edit outside the self-audit scope (consumer
+# projects, tests, fixtures, and the declarative ruleRegistry table), so it adds
+# no latency to ordinary edits. It runs *in addition to* hook-audit.sh, whose
+# diff-gate enforces invariant rules on every edit.
+set -euo pipefail
+
+# Read event JSON from stdin
+event="$(cat)"
+
+# Extract the file path from the tool input (Write and Edit both use file_path)
+file="$(node -e "
+try {
+  var d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  process.stdout.write(d.tool_input?.file_path || d.tool_input?.path || '');
+} catch(e) { process.stdout.write(''); }
+" <<< "${event}")"
+
+# No file path in the event — nothing to audit
+if [ -z "${file}" ]; then
+  exit 0
+fi
+
+# Normalize the edited file to an absolute path (absolute paths pass through;
+# relative paths resolve against the current working directory).
+case "${file}" in
+  /*) file_abs="${file}" ;;
+  *)  file_abs="$(cd "$(dirname "${file}")" 2>/dev/null && pwd)/$(basename "${file}")" ;;
+esac
+
+# Out-of-repo edit no-op (Spec 35 item 9): an edit outside the audited project
+# must not error the hook.
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  project_abs="$(cd "${CLAUDE_PROJECT_DIR}" 2>/dev/null && pwd)" || project_abs="${CLAUDE_PROJECT_DIR%/}"
+  case "${file_abs}" in
+    "${project_abs}"/*) : ;;   # inside the project — continue
+    *) exit 0 ;;                # outside — nothing to self-audit
+  esac
+fi
+
+# Self-audit scope gate: only production files under src/analyzers/ or
+# src/languages/ are self-audit targets. Everything else — every file in a
+# consumer repo, plus this repo's tests, specs, fixtures, and the declarative
+# ruleRegistry.ts data table — is a no-op. The `self-audit` command re-checks
+# this scope on the reported finding paths, so this is only a cheap pre-filter
+# to keep the hook off the hot path for ordinary edits.
+case "${file_abs}" in
+  *"/src/analyzers/"*|*"/src/languages/"*) : ;;
+  *) exit 0 ;;
+esac
+case "${file_abs}" in
+  *"__tests__"*|*".test."*|*".spec."*|*"fixtures"*|*"ruleRegistry.ts"*) exit 0 ;;
+esac
+
+# Resolve the code-audit binary. The `self-audit` command is new in 3.5.0, so a
+# stale PATH/global binary would silently lack it — prefer the plugin's own
+# bundled CLI first (guaranteed to be the version that ships with this hook),
+# then fall back to project-local → PATH → npx auto-install.
+resolve_code_audit() {
+  # 1. The plugin's own bundled CLI (ships alongside this script in the package;
+  #    dist/cli.js is the `code-audit` bin target, so npm marks it executable).
+  if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js" ]; then
+    echo "${CLAUDE_PLUGIN_ROOT}/../dist/cli.js"
+    return
+  fi
+  # 2. Project-local install (consumer project's own node_modules).
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -x "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit" ]; then
+    echo "${CLAUDE_PROJECT_DIR}/node_modules/.bin/code-audit"
+    return
+  fi
+  # 3. Global install or PATH.
+  if command -v code-audit &>/dev/null; then
+    echo "code-audit"
+    return
+  fi
+  # 4. npx auto-install (first use downloads the package; subsequent runs use the npx cache).
+  echo "npx -y -p code-auditor-mcp@^3.0.0 code-audit"
+}
+CODE_AUDIT_BIN="$(resolve_code_audit)"
+
+# Run the self-audit on the edited file. stdout/stderr are fed back to the agent.
+set +e
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  echo "${file_abs}" | ${CODE_AUDIT_BIN} self-audit --stdin --json -p "${CLAUDE_PROJECT_DIR}"
+else
+  echo "${file_abs}" | ${CODE_AUDIT_BIN} self-audit --stdin --json
+fi
+exit_code=$?
+set -e
+
+# Exit code 2 = a blocking self-audit finding; let it propagate so Claude Code
+# feeds the finding back to the agent.
+if [ ${exit_code} -eq 2 ]; then
+  exit 2
+fi
+
+# Non-zero exit (npx auto-install failure, network issue, etc.) degrades
+# gracefully — never wedge the agent loop.
+exit 0

package/plugin/skills/code-auditor/SKILL-RULE-KINDS.md

@@ -1,6 +1,6 @@
 # Invariant Rule Kinds
 
-Five rule kinds are available in `.codeauditor.json`. Rules are validated at startup — bad configs fail the audit, not silently skipped.
+Seven rule kinds are available in `.codeauditor.json`. Rules are validated at startup — bad configs fail the audit, not silently skipped.
 
 ## Rule Kinds
 
@@ -139,15 +139,61 @@ With language and path constraints:
 
 `$$$` matches zero or more nodes (like `...` in rest patterns). `$$$ARGS` is a named meta-variable. See the [ast-grep pattern guide](https://ast-grep.github.io/guide/pattern-syntax.html) for full syntax.
 
-## Severity Levels
+### `style-mechanism`
+
+Enforce which styling mechanisms are allowed in files matching an optional `path` glob. A style declaration using an unapproved mechanism is flagged.
+
+```json
+{
+  "id": "tailwind-only-in-components",
+  "kind": "style-mechanism",
+  "severity": "warning",
+  "allow": ["tailwind"],
+  "path": "src/components/**",
+  "message": "Only Tailwind utilities in src/components/ — use the project's CSS modules elsewhere"
+}
+```
+
+`allow` lists the permitted mechanisms (`tailwind`, `css-modules`, `styled-components`, `inline`, `css`). `path` is optional — omit it to apply the rule to every file.
+
+### `no-raw-values`
 
-| Severity | Meaning | Hook behavior |
-|----------|---------|---------------|
-| `critical` | Security vulnerabilities, data loss risks | Blocks the edit (`--fail-on critical`) |
-| `warning` | Architecture violations, tech debt | Reported; does not block the edit |
-| `suggestion` | Style issues, minor improvements | Reported; does not block the edit |
+Require designated CSS properties to reference a design token instead of a raw value. A declaration whose normalized value has no token reference (and is not in `allowValues`) is flagged.
+
+```json
+{
+  "id": "no-raw-colors-in-pages",
+  "kind": "no-raw-values",
+  "severity": "warning",
+  "properties": ["color", "background-color"],
+  "allowValues": ["inherit", "transparent"],
+  "path": "src/pages/**",
+  "message": "No raw colors in src/pages/ — use design tokens"
+}
+```
+
+`properties` lists the CSS properties to check. `allowValues` names values that are always permitted without a token reference. `path` is optional.
+
+## Severity Levels
 
-> **Severity controls the gate, never the obligation.** A finding that does not block the edit is still a defect to fix — it passes the gate, not the review.
+Severity ranks how urgent a finding is to fix. It never decides whether a
+finding is real, and it never licenses leaving one unresolved. Whether an edit
+is *blocked* is a separate axis: the edit hook gates on invariant rules that
+declare `gating: true` (a binary, per-rule flag), not on severity.
+
+| Severity | What it means |
+|----------|---------------|
+| `critical` | Security vulnerabilities, data-loss risks |
+| `warning` | Architecture violations, tech debt, missing documentation |
+| `suggestion` | Smaller defects — naming, conventions, minor correctness |
+
+> **Severity ranks urgency, never whether a finding is real.** There is no
+> "noise" tier — every finding is a defect to resolve. A finding that does not
+> block the edit still fails the review unless it is fixed, or the rule that
+> produces it is edited in `.codeauditor.json`. There is no "waive" — a finding
+> leaves the queue only by being resolved or by changing the rule that fires it.
+> Documentation findings are not stylistic: missing
+> JSDoc is a maintainability defect, not a nicety.
 
 ## Validation
 
@@ -155,7 +201,7 @@ Rules are validated against `invariant-rules.schema.json` on startup. Common err
 
 - **Missing required field**: each kind has required fields (e.g., `import-ban` requires `module`)
 - **Invalid severity**: must be one of `critical`, `warning`, `suggestion`
-- **Invalid kind**: must be one of the five kinds above
+- **Invalid kind**: must be one of the seven kinds above
 - **Both allowFrom and denyFrom**: `call-constraint` requires exactly one
 - **Empty pattern**: `ast-pattern` requires a non-empty `pattern` string
 - **Invalid language**: `ast-pattern` language must be `typescript`, `javascript`, or `go`

package/plugin/skills/code-auditor/SKILL.md

@@ -38,12 +38,25 @@ Run an audit before declaring a task complete:
 
 ```bash
 code-audit audit --path .                           # Full audit
-code-audit changed --json --fail-on critical         # Diff-scoped audit (hook contract)
+code-audit changed --json                            # Diff-scoped audit (hook contract)
 ```
 
-Use `code-audit changed` after edits to confirm you haven't introduced violations. If the hook is active it already runs `code-audit changed --fail-on critical` automatically on Write/Edit — pay attention to its output.
+Use `code-audit changed` after edits to confirm you haven't introduced violations. If the hook is active it already runs `code-audit changed` automatically on Write/Edit — pay attention to its output.
 
-Expected output: JSON violation list (with `--json`) or colored terminal summary. Non-zero exit code means violations at or above `--fail-on` severity were found.
+**Every finding is a defect to resolve, not a suggestion to weigh.** After a full audit, work the violations in severity order — criticals first, then warnings, then suggestions — and fix them all. Severity ranks urgency, never whether a finding is real; there is no "noise" tier. Documentation findings (missing JSDoc) are maintainability defects, not stylistic niceties. If you choose not to fix one, record why before moving on — never silently dismiss it.
+
+Expected output: JSON violation list (with `--json`) or colored terminal summary. The full `audit` command exits non-zero when violations at or above `--fail-on` severity exist; the diff-scoped `changed` hook gates on per-rule `gating: true` flags, not severity.
+
+### `code-audit next-file` — fix violations one file at a time
+
+```bash
+code-audit next-file --path .        # Highest-priority file + all its findings
+code-audit next-file --path . --json # Machine-readable
+```
+
+This is the refactoring loop. `next-file` audits the project and returns the single highest-priority file — ranked by highest-severity finding, then total finding count — with every finding on it, ordered critical → warning → suggestion. Fix that file, then run it again: a still-broken file comes back, otherwise the next-worst file surfaces. `{done:true}` means the tree is clean.
+
+There is **no skip or decline affordance**. A finding leaves the queue only by being fixed, or by editing the rule that produces it in `.codeauditor.json` (your rules editor). If a rule keeps firing on something you judge correct, change the rule — never work around it.
 
 ### `code-audit config` — know the project's laws
 
@@ -77,20 +90,6 @@ A **built-in** `scripts-and-tests` profile ships with every install — it exclu
 
 Invariant violations are **immune** to path profile gate exclusion — invariants enforce declared laws and always block.
 
-### `code-audit tasks` — queue remediation work
-
-```bash
-code-audit tasks list                                # List all tasks
-code-audit tasks create --title "Fix SQL injection" --priority high
-code-audit tasks get <taskId>                        # Get task details
-code-audit tasks update <taskId> --status in_progress
-code-audit tasks complete <taskId>                   # Mark task done
-code-audit tasks delete <taskId>                     # Delete a task
-code-audit tasks from-audit                          # Create tasks from audit violations
-```
-
-Use `tasks from-audit` to convert audit violations into a tracked task list so every finding is resolved, not dropped. Work findings in severity order — criticals first, then warnings, then suggestions. Tasks carry fingerprints so duplicates are automatically deduplicated across audit runs. Every finding should end as fixed, not silently dismissed; if you choose not to fix one, record why before moving on.
-
 ### `code-audit index` — refresh the index after structural changes
 
 ```bash
@@ -181,13 +180,13 @@ When an edit hook blocks your edit with a violation message:
 1. **Read the violation** — it includes the invariant rule's `message` field explaining *why* the edit was blocked
 2. **Fix the violation** — change your approach to comply with the invariant
 3. **Do NOT retry the same edit** — the hook will block it again
-4. The hook runs `code-audit changed --fail-on critical`, so only critical-severity invariant violations block the edit. Warnings and suggestions are still violations and must be fixed — they pass the gate, they are not resolved.
+4. The hook runs `code-audit changed`, and its gate is binary and per-rule: an invariant rule blocks the edit only if it declares `gating: true` (regardless of severity). Warnings and suggestions are still violations and must be fixed — they pass the gate, they are not resolved.
 
 The hook auto-installs the package via npx on first use — no manual npm step needed. If the hook reports `[code-auditor] code-audit could not run`, the npx auto-install failed (network, unsupported platform). The agent should try again; if it persists, `npm install code-auditor-mcp` is the manual fix.
 
 ## Host-specific notes
 
-- **Claude Code**: This skill is bundled in the `code-auditor` plugin (`claude plugin install code-auditor`). The plugin also ships a `PostToolUse` hook on `Write|Edit` that runs `code-audit changed --fail-on critical` automatically — the hook feedback section above describes that behavior. The MCP server is available as `mcp__code-auditor__*` tools for shell-less use.
+- **Claude Code**: This skill is bundled in the `code-auditor` plugin (`claude plugin install code-auditor`). The plugin also ships a `PostToolUse` hook on `Write|Edit` that runs `code-audit changed` automatically — the hook feedback section above describes that behavior. The MCP server is available as `mcp__code-auditor__*` tools for shell-less use.
 - **Cursor**: Skill install via `code-audit install --agent cursor`. Cursor's `afterFileEdit` hook fires after the edit and cannot block retroactively, so violations are reported through the strongest available feedback channel — fix them even though the edit already landed.
 - **Codex**: Skill install via `code-audit install --agent codex`. Codex's `PostToolUse` hook provides blocking feedback via exit code 2, replacing the tool result with violation messages.
 - **Gemini CLI**: Skill install only (`code-audit install --agent gemini`). No hook system exists; MCP covers shell-less use.
@@ -201,11 +200,11 @@ The hook auto-installs the package via npx on first use — no manual npm step n
 | Find by import | `code-audit search "dep:<module>"` |
 | Complex functions | `code-audit search "lang:go complexity:>10"` |
 | Look up symbol | `code-audit search --definition "<name>"` |
-| Diff-scoped audit | `code-audit changed --json --fail-on critical` |
+| Diff-scoped audit | `code-audit changed --json` |
 | List invariant rules | `code-audit config rules-list` |
 | Inspect path profiles | `code-audit config profiles` |
 | Resolve file profiles | `code-audit config profiles --file <path>` |
-| Triage violations | `code-audit tasks from-audit` |
+| Next file to fix | `code-audit next-file` |
 | Sync index | `code-audit index sync --path .` |
 | Codebase map | `code-audit map -p .` |
 | Mine conventions | `code-audit conventions list` |