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. 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:

CODEBLOCK0

Execution Modes

Mode	Phases Run	Use Case
Full (default)	All 8 phases	Thorough audit
INLINECODE3

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:

CODEBLOCK1

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):
CODEBLOCK2

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
INLINECODE11, main.py, app.py, INLINECODE14	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

CODEBLOCK3

Fix Mode (--fix)

When --fix is specified, apply automatic corrections:

CODEBLOCK4

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:
CODEBLOCK5

TypeScript:
CODEBLOCK6

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

CODEBLOCK7

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

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. 1. Entry points: Look for main(), cli(), app, create_app(), INLINECODE37
2. Service layer: Find classes/modules named *Service, *Manager, INLINECODE40
3. Public API: Check __all__ exports in INLINECODE42
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:
CODEBLOCK9

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	INLINECODE49 (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:
CODEBLOCK10

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

CODEBLOCK11

Baseline Comparison

Save results to .qc-baseline.json:

CODEBLOCK12

On subsequent runs, report delta:
CODEBLOCK13

Report Output

Generate in 3 formats:

1. 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

CODEBLOCK14

Language-Specific Profiles

Read the appropriate profile before running:

• - Python: INLINECODE62
• TypeScript: INLINECODE63
• GDScript: INLINECODE64
• General (any language): INLINECODE65