Skip to content

Code Review

Jump to bottom
Lisa edited this page Mar 20, 2026 · 3 revisions

Unified Code Review

ckb review runs 19 quality checks in a single command and returns a verdict, findings, and suggested reviewers. It replaces the need to wire up individual gates manually.

Architecture

Review Architecture

Quick links: CI-CD-Integration for GitHub Action setup · Quality Gates for individual gate thresholds · Workflow Examples for production templates

Quick Start

# Review current branch against main
ckb review

# Custom base branch
ckb review --base=develop

# Review staged changes only (pre-commit)
ckb review --staged

# Scope to a path prefix or symbol
ckb review internal/query/
ckb review --scope=Engine

# Only run specific checks
ckb review --checks=breaking,secrets,health

# New analyzers
ckb review --checks=dead-code,test-gaps,blast-radius --max-fanout=20

# CI mode (exit 1=fail, 2=warn)
ckb review --ci --format=json

# Markdown for PR comments
ckb review --format=markdown

Checks

ckb review orchestrates 19 checks. All checks run concurrently; tree-sitter calls are serialized via a mutex so git subprocess work overlaps with analysis.

Check What It Does Gate Type
breaking SCIP-based breaking API change detection fail
secrets Credential and secret scanning fail
tests Affected test coverage warn
complexity Cyclomatic/cognitive complexity delta (tree-sitter) warn
health 8-factor weighted code health score (A-F grades) warn
coupling Missing co-changed files from git history warn
hotspots Overlap with volatile/high-churn files info
risk Multi-factor risk score (hotspots, module spread, churn) warn
critical Safety-critical path enforcement fail
traceability Commit-to-ticket linkage (e.g., JIRA-\d+) warn
independence Author != reviewer enforcement (regulated industries) warn
generated Generated file detection and exclusion info
classify Change classification (new/refactor/moved/churn/test/config) info
split Large PR split suggestion with cluster analysis warn
dead-code Unreferenced symbols in changed files (SCIP) warn
test-gaps Untested functions in changed files (tree-sitter) info
blast-radius High fan-out symbol detection; informational when no threshold set (SCIP) warn
comment-drift Numeric constant vs comment mismatch detection info
format-consistency Cross-formatter output consistency validation info

Selecting Checks

# Run all (default)
ckb review

# Only security-related
ckb review --checks=breaking,secrets

# Skip slow checks
ckb review --checks=breaking,secrets,tests,coupling

Output Formats

Format Flag Use Case
Human --format=human Terminal output (default)
JSON --format=json Machine-readable, CI pipelines
Markdown --format=markdown PR comments
GitHub Actions --format=github-actions Inline annotations
SARIF --format=sarif GitHub Code Scanning
CodeClimate --format=codeclimate GitLab Code Quality
Compliance --format=compliance Audit trail (IEC 61508, ISO 26262)

Review Policy

Configure quality gates via CLI flags or .ckb/review.json:

{
  "noBreakingChanges": true,
  "noSecrets": true,
  "requireTests": false,
  "maxRiskScore": 0.7,
  "maxComplexityDelta": 0,
  "failOnLevel": "error",
  "splitThreshold": 50,
  "criticalPaths": ["drivers/**", "protocol/**"],
  "criticalSeverity": "error",
  "generatedPatterns": ["*.pb.go", "*.generated.*"],
  "generatedMarkers": ["Code generated by", "DO NOT EDIT"],
  "maxFanOut": 0,
  "deadCodeMinConfidence": 0.8,
  "testGapMinLines": 5
}

CLI Overrides

ckb review --block-breaking=true --block-secrets=true
ckb review --require-tests --max-risk=0.8
ckb review --max-complexity=10 --max-files=100
ckb review --max-fanout=20                    # blast-radius threshold
ckb review --dead-code-confidence=0.9         # stricter dead code
ckb review --test-gap-lines=10                # only flag larger functions
ckb review --fail-on=warning   # fail on warnings too
ckb review --fail-on=none      # never fail (informational)

Code Health Scoring

The health check computes a 0-100 score per file using 8 weighted factors:

Factor Weight Source
Cyclomatic complexity 20% tree-sitter
Cognitive complexity 15% tree-sitter
File size (LOC) 10% line count
Churn (recent commits) 15% git log
Coupling (co-change count) 10% git log
Bus factor (contributor count) 10% git blame
Age (last modified) 10% git log
Coverage 10% reserved

Grades: A (90+), B (70-89), C (50-69), D (30-49), F (<30)

Health is computed for both the base and head versions. Findings are generated when a file degrades by more than 10 points.

Change Classification

The classify check categorizes each file in the changeset:

Category Heuristic
new File doesn't exist at base
moved >80% content similarity with a deleted file
refactoring Balanced add/remove ratio, same module
churn High-frequency changes in git history
test Test file patterns
config Config file extensions/paths
generated Matches generated patterns/markers
modified Default — none of the above

The review effort estimate uses classification to adjust time: generated files are skipped, tests review faster, new code gets full review time.

PR Split Suggestion

When a PR exceeds splitThreshold files (default: 50), the split check analyzes the changeset and suggests independent clusters using:

  1. Module affinity — files in the same module group together
  2. Coupling data — files with high co-change correlation group together
  3. Connected components — BFS on the adjacency graph finds independent clusters

Each cluster reports file count, additions/deletions, languages, and whether it can be merged independently.

Traceability & Compliance

For regulated industries (IEC 61508, DO-178C, ISO 26262):

# Require ticket references in commits
ckb review --require-trace --trace-patterns="JIRA-\d+,GH-\d+"

# Require independent reviewer (author != reviewer)
ckb review --require-independent --min-reviewers=2

# Safety-critical path enforcement
ckb review --critical-paths="drivers/**,protocol/**"

# Full compliance output
ckb review --format=compliance

Finding Baselines

Track finding trends across releases:

# Save current findings as a baseline
ckb review baseline save --tag=v1.0

# List saved baselines
ckb review baseline list

# Compare two baselines
ckb review baseline diff v1.0 v2.0

Baseline diffs classify each finding as new, unchanged, or resolved.

GitHub Action

CKB provides a composite action at action/ckb-review:

- uses: SimplyLiz/CodeMCP/action/ckb-review@main
  with:
    fail-on: 'error'         # or 'warning' / 'none'
    comment: 'true'          # post PR comment
    sarif: 'true'            # upload to Code Scanning
    checks: ''               # all checks (or comma-separated subset)
    critical-paths: 'drivers/**'
    require-trace: 'false'
    trace-patterns: ''
    require-independent: 'false'
    max-fanout: '0'          # blast-radius threshold (0 = disabled)
    dead-code-confidence: '0.8'
    test-gap-lines: '5'

Outputs: verdict (pass/warn/fail), score (0-100), findings (count)

For a complete workflow example, see the pr-review.yml template or Workflow Examples#pr-review.

MCP Tool

The reviewPR MCP tool exposes the same engine to AI assistants:

{
  "tool": "reviewPR",
  "arguments": {
    "baseBranch": "main",
    "checks": ["breaking", "secrets", "health"],
    "failOnLevel": "error",
    "criticalPaths": ["drivers/**"]
  }
}

Returns the full review response: verdict, score, checks, findings, health report, split suggestion, change breakdown, reviewers, and review effort estimate.

Score Calculation

The review score starts at 100 and deducts points per finding:

Severity Points
error -10
warning -3
info -1

Each check is capped at 20 points maximum deduction to prevent a single noisy check (e.g., coupling) from flooring the score.

Verdict logic:

  • fail — any check with status fail and failOnLevel includes it
  • warn — any check with status warn
  • pass — all checks pass

Clone this wiki locally