refactor(metrics): recalibrate structural risk and priority

Author: etechlead

README.md

@@ -1,27 +1,27 @@
 # TokenMap
 
-TokenMap is a desktop app for quickly finding the parts of a local codebase that are large, complex, hotspot-heavy, or likely to be worth refactoring first.
+TokenMap is a desktop app for quickly finding the parts of a local codebase that carry the most structural risk or are most worth refactoring first.
 
 <img src="docs/readme/screenshot.png" alt="TokenMap main window" width="838">
 
 ## Why TokenMap?
 
 - See which folders and files actually dominate a repository.
-- Find complexity and hotspot signals before refactors, cleanup, or architecture work.
+- Find refactor candidates before cleanup, decomposition, or architecture work.
 - Estimate which parts of a codebase will cost the most tokens in LLM workflows.
 
 ## Metrics
 
 - Basic: Tokens, non-empty lines, file size.
-- Derived: Complexity, Hotspots, Refactor Priority.
+- Derived: Structural Risk, Refactor Priority.
 - Syntax-aware metrics currently cover C#, TypeScript, JavaScript, Python, Go, Java, PHP, and Rust.
 
 ## How It Works
 
 - TokenMap scans a local folder into one snapshot.
 - `.gitignore`, global excludes, and folder excludes decide what gets in.
 - Only included files are measured and shown.
-- Metrics are computed locally, and local git history can add extra signals to Refactor Priority.
+- Metrics are computed locally, and local git history can add extra change-pressure signals to Refactor Priority.
 - Fully offline: no code is uploaded or sent to external services.
 
 > [!NOTE]

docs/architecture.md

@@ -39,6 +39,7 @@ This document covers project purpose, canonical ownership, runtime flow, and non
 - `Clever.TokenMap.Metrics` stays below app/infrastructure orchestration and above core models; UI consumes metric abstractions through core contracts.
 - File metrics flow as raw file metrics, then chained derived file metrics, then directory rollup; raw parser objects stay inside the metrics layer.
 - Infrastructure may enrich a snapshot with one optional repo-wide git history pass before per-file metrics so product metrics can consume cached per-file git artifacts without per-file repository walks.
-- `Refactor Priority` is the product-facing composite score for refactoring urgency; git-derived change pressure stays an internal input, not a separate public metric.
+- `Structural Risk` is the product-facing intrinsic quality score; it summarizes file scale, callable burden, and how concentrated that burden is inside the file.
+- `Refactor Priority` is the product-facing composite score for refactoring urgency; it layers recent change and co-change pressure on top of Structural Risk instead of exposing git signals as separate public metrics.
 - Token counting stays behind `ITokenCounter`.
 - The treemap stays one custom-rendered control.

src/Clever.TokenMap.App/Services/RefactorPromptComposer.cs

@@ -46,19 +46,13 @@ public string Compose(ProjectNode node)
             ["{{tokens}}"] = FormatMetricValue(MetricIds.Tokens, metrics),
             ["{{non_empty_lines}}"] = FormatMetricValue(MetricIds.NonEmptyLines, metrics),
             ["{{file_size}}"] = FormatMetricValue(MetricIds.FileSizeBytes, metrics),
-            ["{{complexity}}"] = FormatMetricValue(MetricIds.ComplexityPoints, metrics),
-            ["{{hotspots}}"] = FormatMetricValue(MetricIds.CallableHotspotPoints, metrics),
+            ["{{structural_risk}}"] = FormatMetricValue(MetricIds.ComplexityPoints, metrics),
             ["{{refactor_priority}}"] = FormatMetricValue(MetricIds.RefactorPriorityPoints, metrics),
-            ["{{complexity_breakdown}}"] = BuildFormulaSection(
-                title: "Complexity",
-                ProductMetricFormulas.TryComputeComplexity(metrics, out var complexityBreakdown),
-                complexityBreakdown,
-                unavailableReason: "Complexity is unavailable because the required syntax-derived inputs were not produced for this file."),
-            ["{{hotspots_breakdown}}"] = BuildFormulaSection(
-                title: "Hotspots",
-                ProductMetricFormulas.TryComputeHotspots(metrics, out var hotspotsBreakdown),
-                hotspotsBreakdown,
-                unavailableReason: "Hotspots are unavailable because the required callable-risk inputs were not produced for this file."),
+            ["{{structural_risk_breakdown}}"] = BuildFormulaSection(
+                title: "Structural Risk",
+                ProductMetricFormulas.TryComputeStructuralRisk(metrics, out var structuralRiskBreakdown),
+                structuralRiskBreakdown,
+                unavailableReason: "Structural Risk is unavailable because the required syntax-derived inputs were not produced for this file."),
             ["{{refactor_priority_breakdown}}"] = BuildRefactorPrioritySection(metrics),
         };
 
@@ -103,7 +97,7 @@ private static string BuildRefactorPrioritySection(MetricSet metrics)
         if (!HasGitContext(metrics))
         {
             builder.AppendLine();
-            builder.Append("- Refactor Priority currently reflects intrinsic pressure only because git-derived change-pressure inputs are unavailable.");
+            builder.Append("- Refactor Priority currently matches Structural Risk because git-derived change and co-change inputs are unavailable.");
         }
 
         return builder.ToString();

src/Clever.TokenMap.App/Services/RefactorPromptTemplateCatalog.cs

@@ -10,11 +10,9 @@ public static class RefactorPromptTemplateCatalog
         new("{{tokens}}", "Token count for the file."),
         new("{{non_empty_lines}}", "Non-empty line count."),
         new("{{file_size}}", "File size, formatted for display."),
-        new("{{complexity}}", "Composite complexity score."),
-        new("{{hotspots}}", "Composite hotspot score."),
+        new("{{structural_risk}}", "Structural-risk score for the file."),
         new("{{refactor_priority}}", "Composite refactor-priority score."),
-        new("{{complexity_breakdown}}", "Multi-line explanation for complexity drivers."),
-        new("{{hotspots_breakdown}}", "Multi-line explanation for hotspot drivers."),
+        new("{{structural_risk_breakdown}}", "Multi-line explanation for structural-risk drivers."),
         new("{{refactor_priority_breakdown}}", "Multi-line explanation for refactor-priority drivers."),
     ];
 }

src/Clever.TokenMap.App/ViewModels/FilePreviewExplainabilityViewModel.cs

@@ -27,17 +27,16 @@ private FilePreviewExplainabilityViewModel(IReadOnlyList<MetricExplainabilitySec
         var metrics = node.ComputedMetrics;
         return new FilePreviewExplainabilityViewModel(
         [
-            CreateComplexitySection(metrics),
-            CreateHotspotsSection(metrics),
+            CreateStructuralRiskSection(metrics),
             CreateRefactorPrioritySection(metrics),
         ]);
     }
 
-    private static MetricExplainabilitySectionViewModel CreateComplexitySection(MetricSet metrics)
+    private static MetricExplainabilitySectionViewModel CreateStructuralRiskSection(MetricSet metrics)
     {
         var definition = DefaultMetricCatalog.Instance.GetRequired(MetricIds.ComplexityPoints);
         var metricValue = metrics.GetOrDefault(MetricIds.ComplexityPoints);
-        if (!ProductMetricFormulas.TryComputeComplexity(metrics, out var breakdown))
+        if (!ProductMetricFormulas.TryComputeStructuralRisk(metrics, out var breakdown))
         {
             return MetricExplainabilitySectionViewModel.Unavailable(
                 definition.DisplayName,
@@ -49,29 +48,7 @@ private static MetricExplainabilitySectionViewModel CreateComplexitySection(Metr
             definition.DisplayName,
             MetricValueFormatter.Format(definition.Id, metricValue, CultureInfo.CurrentCulture),
             breakdown.TotalPoints <= 0d
-                ? "Low structural complexity."
-                : $"Driven mainly by {JoinLabels(GetTopContributors(breakdown, 2))}.",
-            note: null,
-            contributors: CreateContributorViewModels(breakdown));
-    }
-
-    private static MetricExplainabilitySectionViewModel CreateHotspotsSection(MetricSet metrics)
-    {
-        var definition = DefaultMetricCatalog.Instance.GetRequired(MetricIds.CallableHotspotPoints);
-        var metricValue = metrics.GetOrDefault(MetricIds.CallableHotspotPoints);
-        if (!ProductMetricFormulas.TryComputeHotspots(metrics, out var breakdown))
-        {
-            return MetricExplainabilitySectionViewModel.Unavailable(
-                definition.DisplayName,
-                MetricValueFormatter.Format(definition.Id, metricValue, CultureInfo.CurrentCulture),
-                "This metric is unavailable for this file.");
-        }
-
-        return MetricExplainabilitySectionViewModel.Available(
-            definition.DisplayName,
-            MetricValueFormatter.Format(definition.Id, metricValue, CultureInfo.CurrentCulture),
-            breakdown.TotalPoints <= 0d
-                ? "No hotspot thresholds are currently triggered."
+                ? "Low structural risk."
                 : $"Driven mainly by {JoinLabels(GetTopContributors(breakdown, 2))}.",
             note: null,
             contributors: CreateContributorViewModels(breakdown));
@@ -95,29 +72,26 @@ private static MetricExplainabilitySectionViewModel CreateRefactorPrioritySectio
             MetricValueFormatter.Format(definition.Id, metricValue, CultureInfo.CurrentCulture),
             hasGitContext
                 ? BuildRefactorPrioritySummary(breakdown)
-                : "Based on intrinsic pressure only.",
+                : "Matches structural risk because git change context is unavailable.",
             note: hasGitContext ? null : "Git context unavailable.",
             contributors: CreateContributorViewModels(breakdown));
     }
 
     private static string BuildRefactorPrioritySummary(MetricFormulaBreakdown breakdown)
     {
-        var dominantCategory = breakdown.Components
-            .GroupBy(component => component.Category, StringComparer.Ordinal)
-            .Select(group => new
-            {
-                Category = group.Key,
-                ContributionPoints = group.Sum(component => component.ContributionPoints),
-            })
-            .OrderByDescending(group => group.ContributionPoints)
-            .FirstOrDefault()
-            ?.Category;
-
-        return dominantCategory switch
+        var changeContribution = breakdown.Components
+            .Where(component => string.Equals(component.Category, "Change pressure", StringComparison.Ordinal))
+            .Sum(component => component.ContributionPoints);
+        var cochangeContribution = breakdown.Components
+            .Where(component => string.Equals(component.Category, "Co-change pressure", StringComparison.Ordinal))
+            .Sum(component => component.ContributionPoints);
+
+        return (changeContribution > 0d, cochangeContribution > 0d) switch
         {
-            "Change pressure" => "Driven mainly by recent change pressure.",
-            "Co-change pressure" => "Driven mainly by co-change pressure.",
-            _ => "Driven mainly by intrinsic pressure.",
+            (true, true) => "Driven mainly by structural risk, amplified by recent change and co-change pressure.",
+            (true, false) => "Driven mainly by structural risk, amplified by recent change pressure.",
+            (false, true) => "Driven mainly by structural risk, amplified by co-change pressure.",
+            _ => "Driven mainly by structural risk.",
         };
     }
 

src/Clever.TokenMap.Core/Metrics/DefaultMetricCatalog.cs

@@ -33,22 +33,13 @@ public sealed class DefaultMetricCatalog : IMetricCatalog
             "File size in bytes and summed directory size."),
         new(
             MetricIds.ComplexityPoints,
-            "Complexity",
-            "Complexity",
+            "Structural Risk",
+            "Risk",
             MetricUnit.Score,
             MetricRollupKind.Sum,
             VisibleByDefault: true,
             SupportsTreemapWeight: true,
-            "Open-ended composite complexity points for files and summed directory rollups."),
-        new(
-            MetricIds.CallableHotspotPoints,
-            "Hotspots",
-            "Hotspots",
-            MetricUnit.Score,
-            MetricRollupKind.Sum,
-            VisibleByDefault: true,
-            SupportsTreemapWeight: true,
-            "Additive callable hotspot points for files and summed directory rollups."),
+            "Continuous intrinsic structural-risk score based on file scale, callable burden, and risk distribution."),
         new(
             MetricIds.RefactorPriorityPoints,
             "Refactor Priority",
@@ -57,7 +48,7 @@ public sealed class DefaultMetricCatalog : IMetricCatalog
             MetricRollupKind.Sum,
             VisibleByDefault: true,
             SupportsTreemapWeight: true,
-            "Open-ended additive refactor priority points for files and summed directory rollups.")
+            "Refactoring priority score that combines structural risk with recent change and co-change pressure.")
     ];
 
     private readonly Dictionary<MetricId, MetricDefinition> _definitionsById =