code-qc

name	code-qc
description	Run a structured quality control audit on any codebase. Use when asked to QC, audit, review, or check code quality for a project. Supports Python, TypeScript, GDScript, and general projects. Produces a standardized report with PASS/WARN/FAIL verdict, covering tests, imports, type checking, static analysis, smoke tests, and documentation. Also use when asked to compare QC results over time.

Code QC

Structured quality control audit for codebases. Delegates static analysis to proper tools (ruff, eslint, gdlint) and focuses on what AI adds: semantic understanding, cross-module consistency, and dynamic smoke test generation.

Quick Start

1. Detect project type (read the profile for that language)
2. Load .qc-config.yaml if present (for custom thresholds/exclusions)
3. Run the 8-phase audit (or subset with --quick)
4. Generate report with verdict
5. Save baseline for future comparison

Configuration (.qc-config.yaml)

Optional project-level config for monorepos and custom settings:

# .qc-config.yaml
thresholds:
  test_failure_rate: 0.05    # >5% = FAIL, 0-5% = WARN, 0% = PASS
  lint_errors_max: 0         # Max lint errors before FAIL
  lint_warnings_max: 50      # Max warnings before WARN
  type_errors_max: 0         # Max type errors before FAIL (strict by default)

exclude:
  dirs: [vendor, third_party, generated]
  files: ["*_generated.py", "*.pb.go"]

changed_only: false          # Only check git-changed files (CI mode)
fail_fast: false             # Stop on first failure
quick_mode: false            # Only run Phase 1, 3, 3.5, 6

languages:
  python:
    min_coverage: 80
    ignore_rules: [T201]     # Allow print in this project
  typescript:
    strict_mode: true        # Require tsconfig strict: true
    ignore_rules: []         # eslint rules to ignore
  gdscript:
    godot_version: "4.2"

Execution Modes

Mode	Phases Run	Use Case
Full (default)	All 8 phases	Thorough audit
--quick	1, 3, 3.5, 6	Fast sanity check
--changed-only	All, filtered	CI on pull requests
--fail-fast	All, stops early	Find first issue fast
--fix	3 with autofix	Apply automatic fixes

Phase Overview

#	Phase	What	Tools
1	Test Suite	Run existing tests + coverage	pytest --cov / jest --coverage
2	Import Integrity	Verify all modules load	scripts/import_check.py
3	Static Analysis	Lint with proper tools	ruff / eslint / gdlint
3.5	Type Checking	Static type verification	mypy / tsc --noEmit / (N/A for GDScript)
4	Smoke Tests	Verify business logic works	AI-generated per project
5	UI/Frontend	Verify UI components load	Framework-specific
6	File Consistency	Syntax + git state	scripts/syntax_check.py + git
7	Documentation	Docstrings + docs accuracy	scripts/docstring_check.py

Phase Details

Phase 1: Test Suite

Run the project's test suite with coverage. Auto-detect the test runner:

pytest.ini / pyproject.toml [tool.pytest] → pytest --cov
package.json scripts.test → npm test (or npx vitest --coverage)
Cargo.toml → cargo test
project.godot → (GUT if present, else manual)

Record: total, passed, failed, errors, skipped, duration, coverage %.

Verdict contribution:

• No tests found → SKIP (not FAIL; project may be config-only)
• Failure rate = 0% → PASS
• Failure rate ≤ threshold (default 5%) → WARN
• Failure rate > threshold → FAIL

Coverage reporting (Python):

pytest --cov=<package> --cov-report=term-missing --cov-report=json

Phase 2: Import Integrity (Python/GDScript)

Python: Run scripts/import_check.py against the project root.

GDScript: Verify scene/preload references are valid (see gdscript-profile.md).

Critical vs Optional Import Classification

Use these heuristics to classify import failures:

Pattern	Classification	Rationale
__init__.py, main.py, app.py, cli.py	Critical	Core entry points
Module in src/, lib/, or top-level package	Critical	Core functionality
*_test.py, test_*.py, conftest.py	Optional	Test infrastructure
Modules in examples/, scripts/, tools/	Optional	Auxiliary code
Import error mentions cuml, triton, tensorrt	Optional	Hardware-specific
Import error mentions missing system lib	Optional	Environment-specific
Dependency in [project.optional-dependencies]	Optional	Declared optional

Phase 3: Static Analysis

Do NOT use grep. Use the language's standard linter.

Standard Mode

# Python
ruff check --select E722,T201,B006,F401,F841,UP,I --statistics <project>

# TypeScript  
npx eslint . --format json

# GDScript
gdlint <project>

Fix Mode (--fix)

When --fix is specified, apply automatic corrections:

# Python — safe auto-fixes
ruff check --fix --select E,F,I,UP <project>
ruff format <project>

# TypeScript
npx eslint . --fix

# GDScript
gdformat <project>

Important: After --fix, re-run the check to report remaining issues that couldn't be auto-fixed.

Phase 3.5: Type Checking (NEW)

Run static type analysis before proceeding to runtime checks.

Python:

mypy <package> --ignore-missing-imports --no-error-summary
# or if pyproject.toml has [tool.pyright]:
pyright <package>

TypeScript:

npx tsc --noEmit

GDScript: Godot 4 has built-in static typing but no standalone checker. Estimate type coverage manually:

# Find untyped declarations
grep -rn "var \w\+ =" --include="*.gd" .       # Untyped variables
grep -rn "func \w\+(" --include="*.gd" . | grep -v ":"  # Untyped functions

Use the estimate_type_coverage() function from gdscript-profile.md to calculate coverage per file:

# From gdscript-profile.md
def estimate_type_coverage(gd_file: str) -> float:
    """Count typed vs untyped declarations."""
    # See full implementation in gdscript-profile.md

Also check for @warning_ignore annotations which may hide type issues.

Record: Total errors, categorized by severity.

Phase 4: Smoke Tests (Business Logic)

Test backend/core functionality — NOT UI components (that's Phase 5).

API Discovery Heuristics:

1. Entry points: Look for main(), cli(), app, create_app(), __main__.py
2. Service layer: Find classes/modules named *Service, *Manager, *Handler
3. Public API: Check __all__ exports in __init__.py
4. FastAPI/Flask: Find route decorators (@app.get, @router.post)
5. CLI: Find typer/click @app.command() decorators
6. SDK: Look for client classes, public methods without _ prefix

For each discovered API, generate a minimal test:

def smoke_test_user_service():
    """Test UserService basic CRUD."""
    from myproject.services.user import UserService
    svc = UserService(db=":memory:")
    user = svc.create(name="test")
    assert user.id is not None
    fetched = svc.get(user.id)
    assert fetched.name == "test"
    return "PASS"

Guidelines:

• Import + instantiate + call one method with minimal valid input
• Use in-memory/temp resources (:memory:, tempdir)
• Each test < 5 seconds
• Catch exceptions, report clearly

Phase 5: UI/Frontend Verification

Test UI components separately from business logic.

Framework	Test Method
Gradio	from project.ui import create_ui (no launch())
Streamlit	streamlit run app.py --headless exits cleanly
PyQt/PySide	Set QT_QPA_PLATFORM=offscreen, import widget modules
React	npm run build succeeds
Vue	npm run build succeeds
Godot	Scene files parse without error, required scripts exist
CLI	--help on all subcommands returns 0

Boundary: Phase 4 tests "does the logic work?" Phase 5 tests "does the UI render?"

Phase 6: File Consistency

Run scripts/syntax_check.py — compiles all source files to verify no syntax errors.

Note: Phase 2 (Import Integrity) tests runtime import behavior including initialization code. Phase 6 tests static syntax correctness. Both are needed: a file can have valid syntax but fail to import (e.g., missing dependency), or vice versa (syntax error in a module that's never imported).

Check git state:

git status --short      # Should be clean (or report uncommitted changes)
git diff --check        # No conflict markers

Phase 7: Documentation

Run scripts/docstring_check.py (now checks __init__.py by default).

Also verify:

• README exists and is non-empty
• Key docs (CHANGELOG, CONTRIBUTING) exist if referenced
• No stale TODO markers in docs claiming completion

Verdict Logic

# Calculate test failure rate
failure_rate = test_failures / total_tests

# Default thresholds (override in .qc-config.yaml)
FAIL_THRESHOLD = 0.05  # 5%
WARN_THRESHOLD = 0.00  # 0%
TYPE_ERRORS_MAX = 0    # Default: strict (any type error = FAIL)

# Verdict determination
if any([
    failure_rate > FAIL_THRESHOLD,
    critical_import_failure,
    type_check_errors > thresholds.type_errors_max,  # Configurable threshold
    lint_errors > thresholds.lint_errors_max,
]):
    verdict = "FAIL"
elif any([
    0 < failure_rate <= FAIL_THRESHOLD,
    optional_import_failures > 0,
    lint_warnings > thresholds.lint_warnings_max,
    missing_docstrings > 0,
    smoke_test_failures > 0,
]):
    verdict = "PASS WITH WARNINGS"
else:
    verdict = "PASS"

Baseline Comparison

Save results to .qc-baseline.json:

{
  "timestamp": "2026-02-15T15:00:00Z",
  "commit": "abc123",
  "verdict": "PASS WITH WARNINGS",
  "config": {
    "mode": "full",
    "thresholds": {"test_failure_rate": 0.05}
  },
  "phases": {
    "tests": {"total": 134, "passed": 134, "failed": 0, "coverage": 87.5},
    "imports": {"total": 50,      
        
          
        
      
  

On subsequent runs, report delta:

Tests:      134 → 140 (+6 ✅)
Coverage:   87% → 91% (+4% ✅)
Type errors: 0 → 0 (✅)
Lint warnings: 12 → 5 (-7 ✅)

Report Output

Generate in 3 formats:

1. Markdown (qc-report.md) — full detailed report for humans
2. JSON (.qc-baseline.json) — machine-readable for CI/comparison
3. Summary (chat message) — 10-line digest for Discord/Slack

Summary Format Example

📊 QC Report: my-project @ abc123
Verdict: ✅ PASS WITH WARNINGS

Tests:    134/134 passed (100%) | Coverage: 87%
Types:    0 errors
Lint:     0 errors, 12 warnings
Imports:  50/50 (1 optional failed)
Smoke:    14/14 passed

⚠️ Warnings:
- 3 missing docstrings
- 12 lint warnings (run with --fix)

Language-Specific Profiles

Read the appropriate profile before running:

• Python: references/python-profile.md
• TypeScript: references/typescript-profile.md
• GDScript: references/gdscript-profile.md
• General (any language): references/general-profile.md