code-health-suite 0.8.0__tar.gz

code_health_suite-0.8.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for trusted publisher (OIDC)
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API token needed — uses OIDC trusted publisher

code_health_suite-0.8.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

code_health_suite-0.8.0/DEPLOY.md

@@ -0,0 +1,97 @@
+# Code Health Suite — Deployment Guide
+
+## Status (2026-03-15)
+- Server: **VERIFIED WORKING** (22 tools, 13 engines, initialize + tools/list + tools/call all pass)
+- Package: **BUILD READY** (pyproject.toml + hatchling, zero deps)
+- Tests: 4,164+ passing
+- GitHub Actions: **READY** (.github/workflows/pypi-publish.yml — trusted publisher OIDC)
+
+## Priority Path: Official MCP Registry (~20 min total)
+
+The **Official MCP Registry** (registry.modelcontextprotocol.io) is the highest-value target.
+Linux Foundation-backed industry standard. Preview phase = first-mover advantage window.
+API v0.1 is frozen — publishing now won't break on API changes.
+
+### Step 1: Create GitHub Repo (5 min)
+
+```bash
+cd ~/automation/workspace/code-health-suite
+gh repo create code-health-suite --public --source=. --push
+```
+
+### Step 2: Configure PyPI Trusted Publisher (5 min)
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add new pending publisher:
+   - PyPI project name: `code-health-suite`
+   - Owner: `nge` (your GitHub username)
+   - Repository: `code-health-suite`
+   - Workflow: `pypi-publish.yml`
+   - Environment: `pypi`
+
+### Step 3: Publish to PyPI (3 min)
+
+```bash
+cd ~/automation/workspace/code-health-suite
+git tag v0.5.0
+git push --tags
+# GitHub Actions will auto-publish to PyPI via trusted publisher (OIDC, no API token needed)
+```
+
+Verify at: https://pypi.org/project/code-health-suite/
+
+### Step 4: Publish to Official MCP Registry (5 min)
+
+```bash
+pip install mcp-publisher
+mcp-publisher init          # generates server.json
+mcp-publisher login github  # GitHub OAuth
+mcp-publisher publish       # publishes to registry.modelcontextprotocol.io
+```
+
+Verify at: https://registry.modelcontextprotocol.io
+
+### Post-publish: Check MCP Hive deadline
+- MCP Hive founding provider deadline: **May 11, 2026**
+- Apply at mcphive.com after registry listing is live
+
+---
+
+## Bonus: Additional Distribution Channels
+
+### MCPize Cloud (~5 min)
+
+MCPize deploys local code to their cloud. No GitHub repo needed.
+Revenue split: 85% you / 15% MCPize.
+
+```bash
+cd ~/automation/workspace/code-health-suite
+npx mcpize login
+npx mcpize analyze
+npx mcpize deploy
+```
+
+### Smithery Registry (~5 min, needs GitHub)
+
+```bash
+npx @anthropic-ai/smithery-cli auth login
+npx @anthropic-ai/smithery-cli mcp publish https://github.com/nge/code-health-suite -n code-health-suite
+```
+
+### PulseMCP (2 min)
+Visit https://pulsemcp.com → Submit Server → paste GitHub URL.
+
+---
+
+## Verification Commands
+
+```bash
+# Test server locally
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' | python3 -m code_health_suite
+
+# Test tool listing
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}\n{"jsonrpc":"2.0","method":"notifications/initialized"}\n{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n' | python3 -m code_health_suite
+
+# Run test suite
+cd ~/automation/workspace/code-health-suite && python -m pytest tests/ -q
+```

code_health_suite-0.8.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: code-health-suite
+Version: 0.8.0
+Summary: 16 analysis engines, 28 MCP tools for Python code quality. Zero external dependencies.
+Project-URL: Homepage, https://github.com/neogeweb3/code-health-suite
+Project-URL: Repository, https://github.com/neogeweb3/code-health-suite
+Author-email: Neo <nge@users.noreply.github.com>
+License-Expression: MIT
+Keywords: code-health,complexity,dead-code,mcp,python,security,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Code Health Suite
+
+13 analysis engines, 22 MCP tools for Python code quality. Zero external dependencies.
+
+## Quick Start
+
+### As MCP Server (Claude Desktop / Claude Code)
+
+```json
+{
+  "mcpServers": {
+    "code-health": {
+      "command": "code-health-suite"
+    }
+  }
+}
+```
+
+### Install from PyPI
+
+```bash
+pip install code-health-suite
+```
+
+Or with uvx (no install needed):
+
+```bash
+uvx code-health-suite
+```
+
+### Install from GitHub
+
+```bash
+pip install git+https://github.com/nge/code-health-suite
+```
+
+## Tools
+
+| # | Tool | Engine | What it does |
+|---|------|--------|-------------|
+| 1 | `analyze_complexity` | complexity | Per-function CC, cognitive complexity, nesting, grades |
+| 2 | `get_complexity_score` | complexity | Project health score 0-100 |
+| 3 | `find_dead_code` | dead-code | Unused imports, functions, variables, arguments |
+| 4 | `security_scan` | security | OWASP vulns, CWE-mapped findings |
+| 5 | `get_security_score` | security | Security health score 0-100 |
+| 6 | `analyze_imports` | import-graph | Import dependency graph, circular deps |
+| 7 | `get_import_health` | import-graph | Import architecture score 0-100 |
+| 8 | `find_clones` | clone-detect | Type-1/2/3 code clone detection |
+| 9 | `analyze_test_quality` | test-quality | Test suite metrics, anti-patterns |
+| 10 | `full_health_check` | all engines | Combined report with overall grade |
+| 11 | `find_hotspots` | hotspot | Files with high git churn AND high complexity |
+| 12 | `get_hotspot_score` | hotspot | Project churn-complexity score |
+| 13 | `audit_dependencies` | dep-audit | Outdated/vulnerable dependency check |
+| 14 | `analyze_change_impact` | change-impact | Blast radius of file changes |
+| 15 | `get_coupling_score` | change-impact | Module coupling metrics |
+| 16 | `analyze_types` | type-audit | Type annotation coverage |
+| 17 | `get_type_score` | type-audit | Type coverage score 0-100 |
+| 18 | `audit_env` | env-audit | Environment variable audit |
+| 19 | `audit_git_commits` | git-audit | Commit quality audit (security + complexity) |
+| 20 | `get_git_audit_score` | git-audit | Git commit health score |
+
+## Requirements
+
+- Python 3.10+
+- Zero external dependencies (stdlib only)
+
+## License
+
+MIT

code_health_suite-0.8.0/README.md

@@ -0,0 +1,69 @@
+# Code Health Suite
+
+13 analysis engines, 22 MCP tools for Python code quality. Zero external dependencies.
+
+## Quick Start
+
+### As MCP Server (Claude Desktop / Claude Code)
+
+```json
+{
+  "mcpServers": {
+    "code-health": {
+      "command": "code-health-suite"
+    }
+  }
+}
+```
+
+### Install from PyPI
+
+```bash
+pip install code-health-suite
+```
+
+Or with uvx (no install needed):
+
+```bash
+uvx code-health-suite
+```
+
+### Install from GitHub
+
+```bash
+pip install git+https://github.com/nge/code-health-suite
+```
+
+## Tools
+
+| # | Tool | Engine | What it does |
+|---|------|--------|-------------|
+| 1 | `analyze_complexity` | complexity | Per-function CC, cognitive complexity, nesting, grades |
+| 2 | `get_complexity_score` | complexity | Project health score 0-100 |
+| 3 | `find_dead_code` | dead-code | Unused imports, functions, variables, arguments |
+| 4 | `security_scan` | security | OWASP vulns, CWE-mapped findings |
+| 5 | `get_security_score` | security | Security health score 0-100 |
+| 6 | `analyze_imports` | import-graph | Import dependency graph, circular deps |
+| 7 | `get_import_health` | import-graph | Import architecture score 0-100 |
+| 8 | `find_clones` | clone-detect | Type-1/2/3 code clone detection |
+| 9 | `analyze_test_quality` | test-quality | Test suite metrics, anti-patterns |
+| 10 | `full_health_check` | all engines | Combined report with overall grade |
+| 11 | `find_hotspots` | hotspot | Files with high git churn AND high complexity |
+| 12 | `get_hotspot_score` | hotspot | Project churn-complexity score |
+| 13 | `audit_dependencies` | dep-audit | Outdated/vulnerable dependency check |
+| 14 | `analyze_change_impact` | change-impact | Blast radius of file changes |
+| 15 | `get_coupling_score` | change-impact | Module coupling metrics |
+| 16 | `analyze_types` | type-audit | Type annotation coverage |
+| 17 | `get_type_score` | type-audit | Type coverage score 0-100 |
+| 18 | `audit_env` | env-audit | Environment variable audit |
+| 19 | `audit_git_commits` | git-audit | Commit quality audit (security + complexity) |
+| 20 | `get_git_audit_score` | git-audit | Git commit health score |
+
+## Requirements
+
+- Python 3.10+
+- Zero external dependencies (stdlib only)
+
+## License
+
+MIT

code_health_suite-0.8.0/mcpize.yaml

@@ -0,0 +1,17 @@
+version: 1
+name: code-health-suite
+description: >-
+  13 analysis engines, 22 MCP tools for Python code quality.
+  Complexity, dead code, security, imports, clones, test quality,
+  hotspots, dependencies, change impact, type coverage, env audit,
+  naming conventions, and git commit audit. Zero external dependencies.
+runtime: python
+entry: src/code_health_suite/server.py
+
+build:
+  install: pip install -e .
+
+startCommand:
+  type: stdio
+  command: python
+  args: ["-m", "code_health_suite"]

code_health_suite-0.8.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "code-health-suite"
+version = "0.8.0"
+description = "16 analysis engines, 28 MCP tools for Python code quality. Zero external dependencies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Neo", email = "nge@users.noreply.github.com" },
+]
+keywords = ["mcp", "code-health", "static-analysis", "complexity", "security", "dead-code", "python"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/neogeweb3/code-health-suite"
+Repository = "https://github.com/neogeweb3/code-health-suite"
+
+[project.scripts]
+code-health-suite = "code_health_suite.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/code_health_suite"]

code_health_suite-0.8.0/src/code_health_suite/__init__.py

@@ -0,0 +1,3 @@
+"""Code Health Suite — 15 analysis engines, 26 MCP tools for Python code quality."""
+
+__version__ = "0.7.0"

code_health_suite-0.8.0/src/code_health_suite/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as `python -m code_health_suite`."""
+from code_health_suite.server import main
+
+main()

code_health_suite-0.8.0/src/code_health_suite/ast_utils.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""ast_utils — Safe AST traversal utilities for Python analysis tools.
+
+Prevents the ast.walk nested scope leakage bug pattern where ast.walk()
+traverses into nested function/class bodies, causing incorrect scope
+attribution in analysis tools.
+
+Known bugs caused by this pattern:
+  - BUG-40 (ai-complexity): compute_cyclomatic counted nested function CC
+  - BUG-41 (ai-dead-code): find_unused_variables attributed inner vars to outer
+
+Usage:
+    from ast_utils import walk_scope
+
+    # Instead of:  for child in ast.walk(function_node): ...
+    # Use:         for child in walk_scope(function_node): ...
+
+    # The boundary nodes (nested def/class) are yielded,
+    # but their children are NOT traversed.
+"""
+from __future__ import annotations
+
+import ast
+from typing import Iterator
+
+
+__version__ = "0.1.0"
+
+# Node types that create a new scope boundary.
+# When encountered during traversal, we yield the node itself
+# (so callers can see it exists) but do NOT descend into its body.
+SCOPE_BOUNDARIES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+def walk_scope(node: ast.AST) -> Iterator[ast.AST]:
+    """Walk AST nodes within the current scope, skipping nested scope bodies.
+
+    Like ``ast.walk()`` but stops at scope boundaries (nested function/class
+    definitions). The boundary node itself IS yielded so callers can detect
+    its presence, but its children are NOT traversed.
+
+    This is the correct traversal for any function-level analysis that should
+    not "leak" into nested definitions — cyclomatic complexity, variable
+    assignment tracking, control-flow analysis, etc.
+
+    Args:
+        node: The root AST node (typically a FunctionDef or Module).
+
+    Yields:
+        Child AST nodes within the same scope.
+
+    Example::
+
+        def outer():           # root node
+            x = 1              # ✓ yielded
+            if cond:           # ✓ yielded
+                y = 2          # ✓ yielded
+            def inner():       # ✓ yielded (boundary node)
+                z = 3          # ✗ NOT yielded (nested scope)
+            class Nested:      # ✓ yielded (boundary node)
+                attr = 4       # ✗ NOT yielded (nested scope)
+    """
+    # DFS using a list-based stack. We push all immediate children of
+    # non-boundary nodes. Boundary nodes are yielded but not expanded.
+    stack = list(ast.iter_child_nodes(node))
+    while stack:
+        child = stack.pop()
+        yield child
+        if not isinstance(child, SCOPE_BOUNDARIES):
+            stack.extend(ast.iter_child_nodes(child))
+
+
+def walk_scope_bfs(node: ast.AST) -> Iterator[ast.AST]:
+    """BFS variant of walk_scope — yields nodes in breadth-first order.
+
+    Same scope-boundary semantics as ``walk_scope()``, but uses BFS instead
+    of DFS. Useful when processing order matters (e.g., you want to see
+    all top-level statements before nested ones).
+    """
+    from collections import deque
+    queue = deque(ast.iter_child_nodes(node))
+    while queue:
+        child = queue.popleft()
+        yield child
+        if not isinstance(child, SCOPE_BOUNDARIES):
+            queue.extend(ast.iter_child_nodes(child))
+
+
+def collect_scope_names(
+    node: ast.AST,
+    *,
+    assignments: bool = True,
+    reads: bool = False,
+) -> dict[str, list[int]]:
+    """Collect variable names within the current scope only.
+
+    Args:
+        node: Root AST node to analyze.
+        assignments: Include assignment targets (Name in Store context).
+        reads: Include name reads (Name in Load context).
+
+    Returns:
+        Dict mapping variable name to list of line numbers.
+    """
+    names: dict[str, list[int]] = {}
+
+    for child in walk_scope(node):
+        # Reads: Name in Load context
+        if reads and isinstance(child, ast.Name) and isinstance(child.ctx, ast.Load):
+            names.setdefault(child.id, []).append(child.lineno)
+
+        # Assignments: extract from specific assignment node types
+        # (NOT from bare Name/Store, which includes annotation-only targets)
+        if assignments:
+            if isinstance(child, ast.Assign):
+                for target in child.targets:
+                    _collect_assign_targets(target, names)
+            elif isinstance(child, ast.AugAssign):
+                if isinstance(child.target, ast.Name):
+                    names.setdefault(child.target.id, []).append(child.lineno)
+            elif isinstance(child, ast.AnnAssign) and child.value is not None:
+                if isinstance(child.target, ast.Name):
+                    names.setdefault(child.target.id, []).append(child.lineno)
+            elif isinstance(child, ast.NamedExpr):
+                # Walrus operator: (x := value)
+                names.setdefault(child.target.id, []).append(child.lineno)
+            elif isinstance(child, ast.For) or isinstance(child, ast.AsyncFor):
+                _collect_assign_targets(child.target, names)
+            elif isinstance(child, (ast.With, ast.AsyncWith)):
+                for item in child.items:
+                    if item.optional_vars is not None:
+                        _collect_assign_targets(item.optional_vars, names)
+            elif isinstance(child, ast.ExceptHandler) and child.name:
+                names.setdefault(child.name, []).append(child.lineno)
+
+    return names
+
+
+def _collect_assign_targets(
+    target: ast.AST, names: dict[str, list[int]]
+) -> None:
+    """Recursively collect Name nodes from assignment targets."""
+    if isinstance(target, ast.Name):
+        names.setdefault(target.id, []).append(target.lineno)
+    elif isinstance(target, (ast.Tuple, ast.List)):
+        for elt in target.elts:
+            _collect_assign_targets(elt, names)
+    elif isinstance(target, ast.Starred):
+        # Handle starred unpacking: a, *rest, z = items
+        _collect_assign_targets(target.value, names)
+
+
+def count_scope_incrementors(
+    node: ast.AST,
+    incrementors: tuple,
+) -> int:
+    """Count occurrences of specific node types within current scope.
+
+    Useful for cyclomatic complexity, where you count decision points
+    only within the function's own scope (not nested functions).
+
+    Args:
+        node: Root AST node.
+        incrementors: Tuple of AST node types to count.
+
+    Returns:
+        Number of matching nodes found in scope.
+    """
+    count = 0
+    for child in walk_scope(node):
+        if isinstance(child, incrementors):
+            count += 1
+    return count
+
+
+def is_scope_boundary(node: ast.AST) -> bool:
+    """Check if a node creates a new scope boundary."""
+    return isinstance(node, SCOPE_BOUNDARIES)

code_health_suite-0.8.0/src/code_health_suite/engines/__init__.py

@@ -0,0 +1 @@
+"""Analysis engines for Code Health Suite."""