code-health

Spec 060 introduced code-health as the static-analysis sibling of tdd-loop, under ADR-0017's "detect the language → drive its blessed tools → normalize → degrade gracefully" framing. Like tdd.py, the deterministic detection + subprocess invocation live in health.py; this SKILL.md drives the judgment layer. If another installed skill's description identifies it as handling linting / static analysis / code quality, the Claude Code skill router prefers it — the deferral is category-based.

What this skill does

Detects the project's ecosystem and runs its linter, normalizing the result so callers can branch deterministically. Ecosystem detection is table-driven — each ecosystem (Python, Node) is a data-structure entry, so adding a language is an entry, not a control-flow fork. Current scope: Python (ruff) + Node (eslint), each with advisory secondary signals.

• A .jig/lint-command override always wins and bypasses ecosystem detection entirely (honored verbatim — same semantics as tdd.py's .jig/test-command).
• Otherwise detects the ecosystem by marker files (pyproject.toml / *.py for Python; package.json for Node) and resolves its primary linter:
  • Python — ruff on PATH → uvx ruff → pipx run ruff (ephemeral), invoked as ruff check --output-format=json <dir>.
  • Node — eslint on PATH → npx eslint (ephemeral), invoked as eslint --format json <dir>.
• Parses the result into a tight summary — a findings count + the top rule codes, not the raw dump (per spec 057's "tight envelope, not a transcript").
• Adds an advisory dimension that is reported, not gating (it never changes the exit code):
  • Python — complexity: an advisory ruff probe with --select C901,PLR0911,PLR0912,PLR0913,PLR0915 surfaces a per-function complexity signal ("complexity: N function(s) over threshold; top: …").
  • Python — type checking: an advisory pyright --outputjson probe resolves pyright on PATH, then uvx pyright, then pipx run pyright. Type diagnostics are summarized as a count + representative rules ("pyright: N type diagnostic(s); top: …"). If no type-checker resolves, it emits pyright: skipped (no type-checker) …. Like every advisory signal, it is reported, never gating.
  • Node — formatting: an advisory prettier --check probe surfaces files that need formatting ("prettier: N file(s) need formatting").
  • Cross-ecosystem — duplication: an advisory probe (run for BOTH Python and Node) reports copy/paste duplication. It is native-first (an explicit extension point for a future per-ecosystem native duplication tool — currently empty, since no jig ecosystem ships a distinct native detector), falls back to an ephemeral npx jscpd when npx is on PATH (the Node analogue of pipx run, works on any language, installs nothing), and otherwise emits duplication: skipped (no detector) — install a duplication tool or Node (npx jscpd) to enable. When it runs, the summary is a tight percentage + the top clones as file:line ("duplication: 4.2% (12 clones); top: foo.py:10, bar.py:88") — never the raw jscpd log. Like the other advisory signals it is reported, never gating (it cannot change the exit code).
• Normalizes the primary linter's exit code:
  • 0 — clean (no findings)
  • 1 — findings exist (the linter ran and reported issues)
  • 2 — no linter resolvable, no recognized ecosystem, OR the resolved tool failed to start
• Degrades gracefully (AC4), never a stack trace:
  • no markers → exit 2 + "no recognized ecosystem (Python/Node) found — set .jig/lint-command to run your linter".
  • one ecosystem, no resolvable linter → exit 2 + an ecosystem-specific recommendation (ruff/pipx for Python; eslint/npx for Node).
  • mixed (2+ ecosystems) → exit 2 + a recommendation naming the detected ecosystems and pointing at .jig/lint-command to disambiguate.