circle-ir-ai 2.42.0 → 2.44.0

package/dist/quality/entity-smells.js

@@ -0,0 +1,127 @@
+/**
+ * cognium-ai#198 — per-entity design-smell detection.
+ *
+ * The quality passes historically keyed on **directory-averaged** circle-ir
+ * metrics (avgComplexity, avgCBO, avgLCOM, MI). Averages are refactor-
+ * invariant for design smells: splitting one god-class into three small
+ * classes, or one high-CC method into three simple ones, barely moves the
+ * average because you divide by more entities. Result (#198): across the 18
+ * contrastive quality-regression pairs only 1 discriminated smelly-from-
+ * refactored; 6 patterns produced no signal at all (McCabe CC, god-class,
+ * …), and 10 fired on both twins.
+ *
+ * The circle-ir metric stream already carries the per-entity data the
+ * averages threw away:
+ *   - one `cyclomatic_complexity` entry per method, tagged
+ *     `description: "method: <name>"`;
+ *   - per-type `RFC` / `LCOM` / `CBO` / `DIT` / `NOC` entries, tagged
+ *     `description: "type: <name>"`.
+ *
+ * This module consumes that stream and emits **per-entity** smells with
+ * per-entity thresholds, so a smell fires on the offending method/class and
+ * *not* on its refactored replacements. It is a pure function of the metric
+ * array (no I/O, no circle-ir re-analysis) so it is unit-testable against
+ * synthetic contrastive pairs in isolation.
+ */
+export const DEFAULT_SMELL_THRESHOLDS = {
+    methodComplexity: 10,
+    classRfc: 12,
+};
+/** Parse `"method: foo"` / `"type: Bar"` → `foo` / `Bar`; else undefined. */
+function entityName(description, prefix) {
+    if (!description)
+        return undefined;
+    const m = new RegExp(`^${prefix}:\\s*(.+)$`).exec(description.trim());
+    return m ? m[1].trim() : undefined;
+}
+/**
+ * Detect per-entity smells for a single file's circle-ir metric array.
+ *
+ * - **high-complexity**: any method whose cyclomatic complexity exceeds
+ *   `methodComplexity`. Discriminates because a refactor lowers the *peak*
+ *   method's CC, even when total/average CC is unchanged.
+ * - **god-class**: a type with a large response surface (`RFC ≥ classRfc`).
+ *   RFC drops when the class is split across collaborators, so the smell
+ *   clears on the refactored twin. `LCOM ≥ classLcom` (when available)
+ *   escalates severity but is not required — see {@link SmellThresholds}.
+ */
+export function detectEntitySmells(file, metrics, thresholds = DEFAULT_SMELL_THRESHOLDS) {
+    const smells = [];
+    // -- Per-method cyclomatic complexity -------------------------------------
+    for (const m of metrics) {
+        if (m.name !== 'cyclomatic_complexity')
+            continue;
+        const method = entityName(m.description, 'method');
+        if (!method)
+            continue; // aggregate/module-level entry — skip
+        if (m.value > thresholds.methodComplexity) {
+            smells.push({
+                file,
+                entity: method,
+                entityKind: 'method',
+                smell: 'high-complexity',
+                metric: 'cyclomatic_complexity',
+                value: m.value,
+                threshold: thresholds.methodComplexity,
+            });
+        }
+    }
+    // -- Per-class god-class / low-cohesion -----------------------------------
+    // Group the per-type metrics (RFC, LCOM, …) by their type name.
+    const byType = new Map();
+    for (const m of metrics) {
+        const type = entityName(m.description, 'type');
+        if (!type)
+            continue;
+        let bucket = byType.get(type);
+        if (!bucket) {
+            bucket = new Map();
+            byType.set(type, bucket);
+        }
+        // keep the max if a metric repeats for the same type
+        bucket.set(m.name, Math.max(bucket.get(m.name) ?? -Infinity, m.value));
+    }
+    for (const [type, bucket] of byType) {
+        const rfc = bucket.get('RFC');
+        if (rfc === undefined || rfc < thresholds.classRfc)
+            continue;
+        smells.push({
+            file,
+            entity: type,
+            entityKind: 'class',
+            smell: 'god-class',
+            metric: 'RFC',
+            value: rfc,
+            threshold: thresholds.classRfc,
+        });
+    }
+    return smells;
+}
+/** Map a smell to a stable quality ruleId. */
+export function smellRuleId(smell) {
+    switch (smell.smell) {
+        case 'high-complexity':
+            return 'code-complexity-high-mccabe';
+        case 'god-class':
+            return 'code-complexity-god-class';
+    }
+}
+/** Map a smell to a severity by how far past the threshold it sits. */
+export function smellSeverity(smell) {
+    const ratio = smell.value / smell.threshold;
+    if (ratio >= 2)
+        return 'high';
+    if (ratio >= 1.5)
+        return 'medium';
+    return 'low';
+}
+/** Human-readable message for a smell finding. */
+export function smellMessage(smell) {
+    switch (smell.smell) {
+        case 'high-complexity':
+            return `Method '${smell.entity}' has cyclomatic complexity ${smell.value} (> ${smell.threshold})`;
+        case 'god-class':
+            return `Class '${smell.entity}' has a large response surface (${smell.metric} ${smell.value} ≥ ${smell.threshold}) — god-class / large-class smell`;
+    }
+}
+//# sourceMappingURL=entity-smells.js.map

package/dist/quality/entity-smells.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-smells.js","sourceRoot":"","sources":["../../src/quality/entity-smells.ts"],"names":[],"mappings":"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"}

package/dist/quality/index.d.ts

@@ -12,4 +12,5 @@
 export { type QualityFinding, type QualityPassResult, type QualityTier, type QualityScoreResult, getQualityTier, QUALITY_TIER_COLORS, } from './types.js';
 export { calculateQualityScore, formatQualityReport, DEFAULT_QUALITY_WEIGHTS, type QualityWeights, type QualityScoreOptions, } from './calculator.js';
 export { generateQualityBadge, generateQualityBadgeFromScore, } from './badge.js';
+export { detectEntitySmells, smellRuleId, smellSeverity, smellMessage, DEFAULT_SMELL_THRESHOLDS, type EntitySmell, type SmellKind, type SmellThresholds, type MetricEntryLike, } from './entity-smells.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/quality/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/quality/index.js

@@ -15,4 +15,6 @@ export { getQualityTier, QUALITY_TIER_COLORS, } from './types.js';
 export { calculateQualityScore, formatQualityReport, DEFAULT_QUALITY_WEIGHTS, } from './calculator.js';
 // Badge
 export { generateQualityBadge, generateQualityBadgeFromScore, } from './badge.js';
+// cognium-ai#198 — per-entity design-smell detection
+export { detectEntitySmells, smellRuleId, smellSeverity, smellMessage, DEFAULT_SMELL_THRESHOLDS, } from './entity-smells.js';
 //# sourceMappingURL=index.js.map

package/dist/quality/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,QAAQ;AACR,OAAO,EAKL,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,aAAa;AACb,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,GAGxB,MAAM,iBAAiB,CAAC;AAEzB,QAAQ;AACR,OAAO,EACL,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/quality/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,QAAQ;AACR,OAAO,EAKL,cAAc,EACd,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,aAAa;AACb,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,GAGxB,MAAM,iBAAiB,CAAC;AAEzB,QAAQ;AACR,OAAO,EACL,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,YAAY,CAAC;AAEpB,qDAAqD;AACrD,OAAO,EACL,kBAAkB,EAClB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,wBAAwB,GAKzB,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circle-ir-ai",
-  "version": "2.42.0",
+  "version": "2.44.0",
   "description": "LLM-enhanced SAST analysis built on circle-ir",
   "main": "dist/index.js",
   "module": "dist/index.js",