codehealth — Ussyverse Code Health & Test Governance CLI

codehealth is a local-first CLI that orchestrates the 13 ussyverse code-analysis tools as parallel subprocesses, normalizes everything they emit into one common evidence schema, and composes a unified report: CODEHEALTH.md (human) + codehealth.json (machine). It ships as a GitHub Action that runs on every pull request and posts a summary comment.

Evidence philosophy: raw evidence, no authority scores. This tool deliberately collapses nothing into a single "health score". Each analyzer keeps its own voice; every finding carries the raw evidence and a suggested next check, not a verdict. The report exists so a human can follow the leads — coverage gaps are reported as loudly as findings. Findings are leads for human review, not conclusions.

The 13 analyzers

Tool	What it contributes
sentinelussy	code anomalies vs a learned self-profile (artificial immune system)
triageussy	build/test/runtime error log diagnosis ("crime scene")
rosettussy	docstring/doc-drift quality (C-Score per function)
stenographussy	zero-width chars, homoglyphs, Trojan-Source bidi, stego
seralussy	per-module maturity stage from git ecology
calibreussy	test-instrument metrology: Gauge R&R, drift, flakiness Type A/B
assayussy	business-logic ratio, mixed concerns, slag
coronerussy	CI failure forensics (needs a pipeline-run description)
churnmapussy	git churn coupling territories and heat
levainussy	test-suite lifecycle health from JUnit XML
lehrussy	test fragility under env stress (glass physics)
kompressiussy	compression-based entropy/redundancy hotspots
gridironussy	dependency SPOFs, voltage/collapse, grid compliance

See ADAPTERS.md for the verified per-tool interface spec (invocations, output formats, exit-code semantics, gotchas) — the single source of truth each adapter implements.

Installation

Requires Python ≥ 3.11.

# 1. the orchestrator
pip install -e .

# 2. the analyzers (from local clones or from GitHub)
for r in sentinelussy triageussy rosettussy stenographussy seralussy calibreussy \
         assayussy coronerussy churnmapussy levainussy lehrussy kompressiussy gridironussy; do
  pip install https://github.com/ussyverse/$r/archive/refs/heads/main.tar.gz
done

(Or pip install -e /path/to/<repo> for local clones; install triageussy non-editable if the clone must stay pristine — see ADAPTERS.md §5.)

Usage

codehealth analyze /path/to/repo              # auto-discovers .codehealth.*
codehealth analyze . -c .codehealth.toml -o ./out --tool stenographussy --tool gridiron
codehealth analyze --list-tools

Outputs <output_dir>/CODEHEALTH.md, <output_dir>/codehealth.json, and <output_dir>/codehealth.html — a self-contained interactive dashboard (zero external dependencies, works from file://) with per-tool accordions, a filterable findings explorer, severity stats, and the cross-reference / missing-evidence / next-checks sections. Exit code: 0 when all selected analyzers completed; 2 when at least one analyzer crashed (reports are still written — a crashing subprocess never crashes the run).

Configuration

.codehealth.toml (or .codehealth.json) at the target root:

[tool.codehealth]
target = "."
output_dir = "./codehealth-out"
tools = ["sentinelussy", "triageussy", "rosettussy", "stenographussy", "seralussy",
         "calibreussy", "assayussy", "coronerussy", "churnmapussy", "levainussy",
         "lehrussy", "kompressiussy", "gridironussy"]

[tool.codehealth.triageussy]
log_path = "./build.log"          # error log to diagnose (else auto-discovered, else skipped)

[tool.codehealth.calibreussy]
junit_path = "./test-results.xml" # JUnit XML → imported into a temp calibre DB

[tool.codehealth.levainussy]
junit_path = "./test-results.xml"

[tool.codehealth.lehrussy]
results_path = "./tests/lehr-results.json"  # array of {test_name, passed, os, ...}

[tool.codehealth.coronerussy]
run_path = "./run.json"           # pipeline-run dir/file (else auto-discovered, else skipped)

Tools whose required inputs are missing are skipped gracefully with the reason recorded in both artifacts (status: "skipped", skip_reason) and called out in the report's Missing evidence section.

Evidence schema

Every analyzer normalizes to (see codehealth.schema.json_schema(), embedded in every codehealth.json):

{
  "tool": "stenography", "version": "1.0.0", "exit_code": 1, "duration_seconds": 0.42,
  "findings": [{"id": "STEN001", "file": "src/app.py", "line": 12,
                "category": "security", "severity": "high", "message": "...",
                "evidence": { }, "suggested_check": "..."}],
  "metrics": { }, "raw_output": "...",
  "status": "ok", "skip_reason": null
}

category ∈ security|anomaly|docs|test-health|complexity|coupling|dependency|hygiene|info; severity ∈ critical|high|medium|low|info; status ∈ ok|skipped|error. The native tool payload is always preserved in evidence and the verbatim output in raw_output.

GitHub Action

# examples/codehealth-workflow.yml — copy to .github/workflows/codehealth.yml
# (a ready-to-use copy also lives in .github/workflows/ in this repo)
on: [pull_request, workflow_dispatch]
permissions:
  pull-requests: write
  contents: read
jobs:
  codehealth:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0        # git-history analyzers (churnmap, seral) need real history
      - uses: ussyverse/codehealth@v1   # or: uses: ./
      - uses: actions/upload-artifact@v4
        with:
          name: codehealth-report
          path: codehealth-out/

The Docker-based action runs the CLI and posts (or updates, via a <!-- codehealth --> marker) a PR comment with the summary; the full report is attached as a workflow artifact and appended to the job summary. Inputs: target, config, output_dir, tools, post_comment (all optional). GITHUB_TOKEN is used with the pull-requests: write permission. Test locally with act: act pull_request.

Reports

CODEHEALTH.md sections: Summary (per-tool table + severity counts) → Cross-references (files flagged by multiple tools; heuristic overlaps like high-churn × low-doc-quality) → Findings by tool (tables, metrics, raw output in <details>) → Missing evidence (skips and zero-finding tools, framed as coverage gaps) → Suggested next checks (deduplicated, severity-ordered checklist). The same content ships as an interactive single-file HTML dashboard (codehealth.html) and as the machine-readable codehealth.json.

Development & demo

python3 -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests/ -q
# recorded demo on a repo with intentional issues:
cd examples/sample-repo && ../../.venv/bin/codehealth analyze . -c .codehealth.toml

examples/sample-repo/ contains planted issues (undocumented functions, a zero-width space, a diagnosable build log, a circular import, high churn on one file, a dormant/flaky test, dependency SPOFs). The recorded run — 12 ok / 1 skipped, 62+ findings, 11 analyzers producing normalized findings — is in examples/VALIDATION.md with the demo report at examples/CODEHEALTH.demo.md and the interactive dashboard at examples/codehealth.demo.html.