Feature request

Description

As a developer, I want a CLI tool that validates code metrics against configurable thresholds so that I can enforce code quality standards in CI/CD pipelines and prevent code quality degradation.

Acceptance criteria

• ✅ Tool uses UnifiedParser internally to analyze code without creating intermediate files
• ✅ Supports YAML and JSON configuration files for defining thresholds
• ✅ Validates file-level metrics (rloc, complexity, max_complexity_per_function, etc.)
• ✅ Supports both min and max thresholds for each metric
• ✅ Reports violations with clear, actionable output
• ✅ Sorts violations by severity (worst offenders first)
• ✅ Exits with appropriate codes: 0 (pass), 1 (violations), 2 (errors)
• ✅ Color-coded console output for better readability
• ✅ Supports standard UnifiedParser options (--exclude, --file-extensions, --bypass-gitignore)
• ✅ Interactive mode support via Dialog
• ✅ Comprehensive documentation

Assumptions & Exclusions

• Tool validates only file-level metrics from UnifiedParser
• Function-level data is available as aggregated statistics (max/min/mean/median)
• No custom metric calculation - relies on UnifiedParser's existing metrics
• Configuration file must be provided (no default thresholds)

Implementation Details

Tool Name: metricthresholdchecker

Usage:

ccsh metricthresholdchecker <input-path> --config <config-file> [options]

Configuration Format:

file_metrics:
  rloc:
    max: 500
  max_complexity_per_function:
    max: 10
  number_of_functions:
    max: 20

Example Output:

Metric Threshold Check Results
════════════════════════════════════════════════════════════
✗ 3 violation(s) found!
════════════════════════════════════════════════════════════

Violations:

Metric: rloc (2 violations)

  Path                   Actual Value     Threshold     Exceeds By
  ─────────────────────────────────────────────────────────────────
  src/HugeFile.kt        750              max: 500      +250
  src/LargeFile.kt       550              max: 500      +50

Development notes (Task Breakdown)

• Create MetricThresholdChecker module under analysers/tools/
• Implement ThresholdConfiguration data classes
• Implement ThresholdConfigurationLoader (supports JSON and YAML via Jackson)
• Implement ThresholdValidator to check metrics against thresholds
• Implement ViolationFormatter with sorted output
• Add Dialog support for interactive mode
• Register tool in Ccsh.kt and settings.gradle.kts
• Add Jackson dependencies (databind, dataformat-yaml, module-kotlin)
• Add YAML/YML file extensions to FileExtension enum
• Write comprehensive README with usage examples
• Add CI/CD integration examples (GitHub Actions, GitLab CI, Jenkins)
• Update CHANGELOG.md
• Add GitHub Pages documentation

Notes

Implementation PR: This feature has been implemented in branch feat/add-new-metric-checker-tool

Dependencies Added:

• Jackson 2.18.2 (databind, dataformat-yaml, module-kotlin)

Files Modified:

• analysis/analysers/tools/MetricThresholdChecker/ (new module)
• analysis/ccsh/build.gradle.kts
• analysis/ccsh/src/main/kotlin/de/maibornwolff/codecharta/ccsh/Ccsh.kt
• analysis/gradle/libs.versions.toml
• analysis/model/src/main/kotlin/de/maibornwolff/codecharta/serialization/FileExtension.kt
• analysis/settings.gradle.kts
• analysis/CHANGELOG.md
• gh-pages/_docs/07-filter/05-metric-threshold-checker.md

Documentation: https://maibornwolff.github.io/codecharta/docs/filter/metric-threshold-checker