feat(skills): add code-health diagnostic skill

[DaniBron]

Summary

Adds a code-health skill under development/ that combines knowledge graph topology with static quality metrics to produce risk-weighted diagnostics, community health scores, circular dependency detection, and a Main Sequence plot (SDP + SAP per Robert C. Martin).

What it does

• Builds a knowledge graph of the target codebase (via graphifyy)
• Runs radon (CC/MI/LOC) and ruff (lint stats)
• Cross-references both into a single risk-scored view
• Detects complexity contagion chains (call paths where CC compounds)
• Finds circular module dependencies (ADP violations)
• Generates an interactive HTML dashboard with clickable drill-downs

Self-contained

The skill works standalone — it builds an AST-only graph via the graphifyy Python library when no graph.json exists, so users don't need the /graphify skill as a prerequisite. If /graphify is installed separately, its richer semantic graph is used automatically.

Dependencies

Auto-installed on first run:

• graphifyy (~50MB, brings tree-sitter parsers for 20+ languages)
• radon (cyclomatic complexity, maintainability index, LOC)
• ruff (lint statistics)

The graphifyy install is chunky because it bundles tree-sitter parsers. This is a known cost and is called out in the SKILL.md.

Testing

Tested end-to-end on a fresh Python environment with all dependencies uninstalled. The pip install + AST graph build + cross-reference pipeline produces valid output.

Files added

• cli-tool/components/skills/development/code-health/SKILL.md (6KB — skill instructions)
• cli-tool/components/skills/development/code-health/LICENSE.txt (MIT)
• cli-tool/components/skills/development/code-health/scripts/crossref.py (87KB — cross-reference engine + HTML generator)

Test plan

• Install the skill via `npx claude-code-templates`
• Run `/code-health` on a small Python project
• Verify `code-health-out/health_report.html` renders correctly
• Verify interactive drill-downs work (click risk rows, click Main Sequence plot dots)

🤖 Generated with Claude Code

---

Summary by cubic

Adds a new development/code-health diagnostic skill that fuses the knowledge graph with static analysis to surface risk-weighted hotspots, contagion chains, and architecture issues with an interactive HTML report. This update also fixes community counting and hardens the HTML generator.

• Affected area: components (cli-tool/components/); new skill at skills/development/code-health (regenerate docs/components.json)
• Cross-references graph with radon/ruff; finds cycles and Main Sequence outliers; outputs code-health-out/crossref.json and code-health-out/health_report.html
• Self-contained: auto-builds an AST-only graph if no graph.json; auto-installs graphifyy, radon, ruff (Python 3.10+)
• Robustness/docs: use in-memory results in HTML generator, fix community “0” undercount, escape ids/labels/files in HTML, clarify --report vs --html with bash examples
• Env: no new environment variables or secrets

^{Written for commit 219cdbb. Summary will update on new commits.}

[vercel]

@DaniBron is attempting to deploy a commit to the Daniel Avila's projects Team on Vercel.

A member of the Team first needs to authorize it.

[DaniBron]

FYI the Security Audit, Vercel preview, and comment-poster failures appear to be pre-existing fork-permission issues (the actions/github-script step can't write back to a forked PR without explicit permissions: write in the workflow, and Vercel doesn't auto-deploy previews for unauthorized forks). The code itself and the audit step that produced the report both succeeded only the downstream comment-poster failed with a 403.

[cubic-dev-ai]

4 issues found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="cli-tool/components/skills/development/code-health/scripts/crossref.py">

<violation number="1" location="cli-tool/components/skills/development/code-health/scripts/crossref.py:734">
P2: Community totals are undercounted because the filter drops valid community ID `0` by using truthiness instead of a `None` check.</violation>

<violation number="2" location="cli-tool/components/skills/development/code-health/scripts/crossref.py:901">
P2: Repository-derived strings are inserted into generated HTML/DOM without escaping, enabling HTML/JS injection in the report.</violation>

<violation number="3" location="cli-tool/components/skills/development/code-health/scripts/crossref.py:1003">
P2: `generate_html` inconsistently ignores its `results` input and re-reads architecture data from disk, which can render stale or mismatched Main Sequence/cycle sections.</violation>
</file>

<file name="cli-tool/components/skills/development/code-health/SKILL.md">

<violation number="1" location="cli-tool/components/skills/development/code-health/SKILL.md:120">
P2: Subcommand docs are contradictory (`--report` says skip Step 2 and only `html` is exemplified), creating a real risk of running the wrong crossref mode.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}