MaibornWolff
diff --git a/‎.github/workflows/test_visualization.yml‎
Lines changed: 6 additions & 0 deletions b/‎.github/workflows/test_visualization.yml‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎plans/add-metric-explanations-to-threshold-checker.md‎
Lines changed: 123 additions & 0 deletions b/‎plans/add-metric-explanations-to-threshold-checker.md‎
Lines changed: 123 additions & 0 deletions
diff --git a/‎plans/fix-metric-descriptions-not-showing-in-threshold-checker.md‎
Lines changed: 170 additions & 0 deletions b/‎plans/fix-metric-descriptions-not-showing-in-threshold-checker.md‎
Lines changed: 170 additions & 0 deletions
diff --git a/‎plans/fix-pr-4334-review-comments.md‎
Lines changed: 54 additions & 0 deletions b/‎plans/fix-pr-4334-review-comments.md‎
Lines changed: 54 additions & 0 deletions
@@ -45,6 +45,12 @@ jobs:
         npm ci || (echo "npm ci failed, regenerating lock file and retrying..." && npm install --package-lock-only && npm ci)
       working-directory: ${{env.working-directory}}
 
+    - name: Check architecture
+      run: |
+        echo "Checking architecture rules (including circular dependencies)..."
+        npm run lint:architecture || (echo "❌ Architecture violations detected! Check the output above for details." && exit 1)
+      working-directory: ${{env.working-directory}}
+
     - name: Run unit tests
       env:
         NODE_OPTIONS: "--max_old_space_size=4096"
 
@@ -0,0 +1,123 @@
+---
+name: Add AI-Readable Metric Explanations to MetricThresholdChecker
+issue: TBD
+state: complete
+version: 1.0
+---
+
+## Goal
+
+Enhance the MetricThresholdChecker to provide simple, concise explanations for each failed metric, including what the metric means and actionable remediation advice, in an AI-readable format within the existing console output.
+
+## Tasks
+
+### 1. Create MetricMetadata Data Structure
+Create a new data class to hold metric information:
+- Metric name
+- Human-readable description (what the metric measures)
+- Remediation advice (what to do when threshold is violated)
+- Optional: severity level, reference links
+
+### 2. Build MetricCatalog Registry
+Create a hardcoded registry/catalog of common CodeCharta metrics with their metadata:
+- `rloc` (Real Lines of Code): Counts non-empty, non-comment lines
+- `mcc` / `complexity` (McCabe/Cyclomatic Complexity): Measures code branching complexity
+- `parameters` (Parameters per Function): Counts function/method parameters
+- `functions` (Number of Functions): Counts functions/methods in a file
+- `comment_lines` (Comment Lines): Counts lines with comments
+- Include explanations and remediation for each
+
+### 3. Enhance ViolationFormatter Output
+Modify ViolationFormatter to include metric explanations:
+- After displaying violations grouped by metric, add an "Explanation" section
+- For each failed metric, display:
+  - What it means
+  - Why it matters
+  - Recommended actions
+- Keep formatting consistent with existing colored output
+- Ensure text is clear and concise for AI consumption
+
+### 4. Handle Unknown Metrics Gracefully
+Add fallback for metrics not in the catalog:
+- Display generic message when metric metadata is unavailable
+- Suggest checking metric documentation
+- Don't fail or crash when encountering unknown metrics
+
+### 5. Write Tests
+Add unit tests for:
+- MetricMetadata data class
+- MetricCatalog registry (verify all common metrics are present)
+- ViolationFormatter with explanations (test output format)
+- Unknown metric handling
+
+## Steps
+
+- [x] Complete Task 1: Create MetricMetadata data class in ThresholdConfiguration.kt or new file
+- [x] Complete Task 2: Create MetricCatalog object with hardcoded metric explanations
+- [x] Complete Task 3: Modify ViolationFormatter.printResults() to display metric explanations
+- [x] Complete Task 4: Add graceful fallback for unknown metrics in MetricCatalog
+- [x] Complete Task 5: Write comprehensive unit tests for new functionality
+- [x] Verify output is clear and AI-readable by testing with actual violations
+
+## Review Feedback Addressed
+
+(Will be filled during PR review)
+
+## Notes
+
+### Common Metrics to Document
+
+Based on UnifiedParser analysis:
+- **rloc**: Real Lines of Code (excluding empty lines and comments)
+- **complexity** / **mcc**: McCabe/Cyclomatic Complexity (measures control flow)
+- **parameters**: Number of parameters per function
+- **functions**: Number of functions in a file
+- **comment_lines**: Lines containing comments
+
+### Output Format Considerations
+
+The enhanced output should maintain the existing colored table format while adding a clear explanation section. Example structure:
+
+```
+═══════════════════════════════════════════════════════════
+✗ 5 violation(s) found!
+═══════════════════════════════════════════════════════════
+
+Violations:
+
+Metric: rloc (5 violations)
+
+  Path                  Actual Value  Threshold     Exceeds By
+  ────────────────────────────────────────────────────────────
+  src/large_file.kt     523          max: 500       +23
+
+───────────────────────────────────────────────────────────
+
+📊 Metric Explanations:
+
+rloc (Real Lines of Code)
+  What it means: Measures the number of actual code lines, excluding empty
+                 lines and comments. High values indicate large files.
+
+  Why it matters: Large files are harder to maintain, test, and understand.
+
+  Recommended actions:
+    • Split large files into smaller, focused modules
+    • Extract related functions into separate files
+    • Consider using composition over large classes
+    • Target: Keep files under 500 lines when possible
+
+───────────────────────────────────────────────────────────
+```
+
+### Implementation Location
+
+- MetricMetadata: New file `MetricMetadata.kt` in metricthresholdchecker package
+- MetricCatalog: New file `MetricCatalog.kt` or add to MetricMetadata.kt
+- Enhanced output: Modify `ViolationFormatter.kt`
+
+### Future Enhancements (Out of Scope)
+
+- Allow users to provide custom metric explanations via config file
+- Add support for project/folder level metrics (currently only file-level)
+- Generate HTML/JSON output format for better AI parsing
@@ -0,0 +1,170 @@
+---
+name: Fix Metric Descriptions Not Showing in MetricThresholdChecker
+issue: TBD
+state: complete
+version: 1.0
+---
+
+## Goal
+
+Fix the bug where metric descriptions are not displayed in MetricThresholdChecker output, even though the display logic exists in ViolationGroupRenderer.
+
+## Problem Analysis
+
+The MetricThresholdChecker uses ProjectScanner directly (bypassing UnifiedParser) to analyze files. However, ProjectScanner does not add AttributeDescriptors to the ProjectBuilder, so the resulting Project has an empty attributeDescriptors map.
+
+**Current Flow:**
+1. MetricThresholdChecker creates ProjectScanner with a ProjectBuilder
+2. ProjectScanner.traverseInputProject() parses files and adds nodes
+3. ProjectScanner DOES NOT call projectBuilder.addAttributeDescriptions()
+4. project.attributeDescriptors is empty
+5. ViolationGroupRenderer receives empty map, displays no descriptions
+
+**UnifiedParser Flow (working):**
+1. UnifiedParser creates ProjectScanner
+2. UnifiedParser calls projectBuilder.addAttributeDescriptions(getAttributeDescriptors())
+3. Descriptions are available in the project
+
+## Solution
+
+Add the AttributeDescriptors from UnifiedParser to the ProjectBuilder in MetricThresholdChecker after creating the ProjectScanner.
+
+## Tasks
+
+- [ ] Import `getAttributeDescriptors()` from UnifiedParser package in MetricThresholdChecker
+- [ ] Call `projectBuilder.addAttributeDescriptions(getAttributeDescriptors())` before building the project
+- [ ] Test manually that descriptions now appear in violation output
+- [ ] Add integration test to verify descriptions are displayed
+- [ ] Update existing test to use real AttributeDescriptors instead of emptyMap()
+
+## Implementation Steps
+
+### Step 1: Update MetricThresholdChecker.kt
+
+In the `analyzeProject()` method, after creating ProjectScanner but before building:
+
+```kotlin
+private fun analyzeProject(inputPath: File): Project {
+    if (verbose) {
+        error.println("Analyzing project at: ${inputPath.absolutePath}")
+    }
+
+    val projectBuilder = ProjectBuilder()
+    val useGitignore = !bypassGitignore
+
+    val projectScanner = ProjectScanner(
+        inputPath,
+        projectBuilder,
+        excludePatterns,
+        fileExtensions,
+        emptyMap(),
+        useGitignore
+    )
+
+    projectScanner.traverseInputProject(verbose)
+
+    // ADD THIS LINE:
+    projectBuilder.addAttributeDescriptions(
+        de.maibornwolff.codecharta.analysers.parsers.unified.getAttributeDescriptors()
+    )
+
+    if (!projectScanner.foundParsableFiles()) {
+        Logger.warn { "No parsable files found in the given input path" }
+    }
+
+    return projectBuilder.build()
+}
+```
+
+### Step 2: Manual Testing
+
+Create a test config and run against a sample project to verify descriptions appear:
+
+```bash
+cd analysis
+./gradlew installDist
+
+# Create test threshold config
+cat > /tmp/test-thresholds.yml << EOF
+file_metrics:
+  rloc:
+    max: 10
+  complexity:
+    max: 5
+EOF
+
+# Run against MetricThresholdChecker itself (will likely have violations)
+./build/install/codecharta-analysis/bin/ccsh metricthresholdchecker \
+  analysers/tools/MetricThresholdChecker/src \
+  --config /tmp/test-thresholds.yml
+
+# Verify output shows descriptions like:
+# "Number of lines that contain at least one character which is neither..."
+```
+
+### Step 3: Add Integration Test
+
+Add test in MetricThresholdCheckerTest.kt to verify descriptions appear in output:
+
+```kotlin
+@Test
+fun `should display metric descriptions in violation output`() {
+    // Arrange
+    val testFile = File.createTempFile("test", ".kt")
+    testFile.writeText("fun a() {}\n".repeat(100)) // Create file with violations
+
+    val configFile = File.createTempFile("config", ".yml")
+    configFile.writeText("file_metrics:\n  rloc:\n    max: 10\n")
+
+    val output = ByteArrayOutputStream()
+    val error = ByteArrayOutputStream()
+
+    // Act
+    MetricThresholdChecker.mainWithOutputStream(
+        PrintStream(output),
+        PrintStream(error),
+        arrayOf(testFile.absolutePath, "--config", configFile.absolutePath)
+    )
+
+    // Assert
+    val errorOutput = error.toString()
+    assertThat(errorOutput).contains("Metric: rloc")
+    assertThat(errorOutput).contains("Number of lines that contain at least one character")
+
+    // Cleanup
+    testFile.delete()
+    configFile.delete()
+}
+```
+
+### Step 4: Update Existing Tests
+
+Update ViolationFormatterTest tests that pass `emptyMap()` for attributeDescriptors to use realistic test data where appropriate.
+
+## Testing Checklist
+
+- [ ] Manual test shows descriptions appearing in output
+- [ ] Integration test passes
+- [ ] All existing tests still pass
+- [ ] Tested with multiple metrics (rloc, complexity, number_of_functions)
+- [ ] Tested with metrics that don't have descriptions (graceful handling)
+
+## Notes
+
+### Why This Bug Occurred
+
+The original implementation of metric descriptions was done in ViolationGroupRenderer, but the MetricThresholdChecker was added later and uses ProjectScanner directly. The connection between ProjectScanner usage and AttributeDescriptor registration was missed.
+
+### Alternative Solutions Considered
+
+1. **Have ProjectScanner add AttributeDescriptors**: This would require ProjectScanner to know about UnifiedParser's AttributeDescriptors, creating a coupling issue.
+
+2. **Make getAttributeDescriptors() a static utility**: This is the chosen approach - treat AttributeDescriptors as a shared registry that any component can use.
+
+3. **Create a separate MetricDescriptorRegistry**: Over-engineered for current needs.
+
+## Future Enhancements
+
+- Consider centralizing AttributeDescriptor registration in a shared registry
+- Add descriptions for metrics from other parsers/importers
+- Add remediation advice to AttributeDescriptor model
@@ -0,0 +1,54 @@
+# Fix PR #4334 Review Comments
+
+**Status**: `complete`
+
+## Context
+Address 5 review comments from PR #4334 for the MetricThresholdChecker tool:
+1. Refactor TextWrapper.wrap() - too complex
+2. Refactor ViolationGroupRenderer.render() - hard to understand
+3. Use Kotlin template strings in ViolationTableRenderer
+4. Use else branch in ThresholdValidator when statement
+5. Reduce nesting depth in ThresholdValidator.validateFileMetrics()
+
+## Plan
+
+### 1. Refactor TextWrapper.wrap() method
+- [x] Simplify the logic inline (no extraction of helper methods)
+- [x] Reduce conditional complexity
+- [x] Make the flow more linear and easier to follow
+- [x] Ensure all existing tests still pass
+
+### 2. Refactor ViolationGroupRenderer.render() method
+- [x] Extract method for rendering all metric groups
+- [x] Extract method for rendering a single metric group
+- [x] Extract method for adding description if present
+- [x] Make each method have a single responsibility
+- [x] Ensure all existing tests still pass
+
+### 3. Replace string concatenation with template strings in ViolationTableRenderer
+- [x] Replace `+` operator concatenations with Kotlin template strings
+- [x] Update renderHeader() method
+- [x] Update renderRow() method
+- [x] Update renderSeparator() method
+- [x] Fix ktlint violations (line length, formatting)
+- [x] Ensure all existing tests still pass
+
+### 4. Use else branch in ThresholdValidator.validateNode()
+- [x] Replace the comma-separated list of node types (Package, Class, Interface, Method, Unknown, null) with an else clause
+- [x] Ensure all existing tests still pass
+
+### 5. Reduce nesting depth in ThresholdValidator.validateFileMetrics()
+- [x] Use guard clauses to exit early
+- [x] Reduce from 3 levels of nesting to 1-2 levels
+- [x] Ensure all existing tests still pass
+
+### 6. Verify all changes
+- [x] Run unit tests: `./gradlew test` (131 tests passed)
+- [x] Run ktlint check: `./gradlew ktlintCheck` (all checks passed)
+- [x] Functionality remains unchanged
+
+## Success Criteria
+- All review comments addressed
+- All tests passing
+- Code style checks passing
+- Functionality remains unchanged