@sigloch/contracts 3.2.0 → 3.3.0

package/dist/se/metric-rules.d.ts

@@ -52,6 +52,40 @@ export interface AllocationCohesion {
  * Validation of this metric — and of MT-01/MT-02, which are thresholded the same way —
  * is deferred (CR-SM-223).
  */
+/** Per-module architecture metrics — the numbers behind MT-01/MT-02 (CR-SM-232). */
+export interface ModuleMetrics {
+    moduleId: string;
+    moduleName: string;
+    /** FUNCs allocated to this module (`FUNC —allocate→ MOD`). */
+    allocatedFuncs: number;
+    /** MT-01 core: coupling. `instability = fanOut / (fanIn + fanOut)`. */
+    fanIn: number;
+    fanOut: number;
+    /** null when fanIn + fanOut === 0 — no signal, no substitute value. */
+    instability: number | null;
+    /** MT-02 core: connected-component count. null below 2 allocated FUNCs (not measurable). */
+    lcom4: number | null;
+    /** The CR-SM-223 measurement, deliberately threshold-free. null where contracts omits it. */
+    cohesion: {
+        internal: number;
+        external: number;
+        ratio: number;
+    } | null;
+}
+/**
+ * Per-module architecture metrics as NUMBERS — one row per MOD, threshold or not
+ * (CR-SM-232).
+ *
+ * MT-01 only ever reported the modules above 70 %, MT-02 only those with ≥ 4
+ * components, and both only inside a prose `message`. For every module below the
+ * threshold there was no value, there was nothing — so a trend ("was 62 %, is 68 %"),
+ * the actual steering signal, was unobtainable. This exports what the rules already
+ * compute; it invents no metric and calibrates no threshold.
+ *
+ * Sorted worst cohesion first (as `allocationCohesion` does — the ranking IS the
+ * signal); modules without a cohesion measurement follow, stable by `moduleId`.
+ */
+export declare function moduleMetrics(graph: OntologyGraph): ModuleMetrics[];
 export declare function allocationCohesion(graph: OntologyGraph): AllocationCohesion[];
 export declare const MT_RULES: readonly [{
     readonly id: "MT-01";

package/dist/se/metric-rules.js

@@ -8,39 +8,18 @@ const INSTABILITY_THRESHOLD = 0.7;
  */
 export function mt01Instability(graph) {
     const violations = [];
-    const mods = graph.elements.filter(e => e.type === 'MOD');
-    for (const mod of mods) {
-        // FUNCs allocated to this module
-        const modFuncIds = new Set(graph.traces
-            .filter(t => t.type === 'allocate' && t.target === mod.id)
-            .map(t => t.source));
-        // Direct MOD-level traces (MOD→MOD io/compose)
-        const directOut = graph.traces.filter(t => t.source === mod.id && (t.type === 'io' || t.type === 'compose') && t.target !== mod.id).length;
-        const directIn = graph.traces.filter(t => t.target === mod.id && (t.type === 'io' || t.type === 'compose' || t.type === 'allocate')).length;
-        // Indirect: traces from module FUNCs to outside elements (and vice versa)
-        let indirectOut = 0;
-        let indirectIn = 0;
-        for (const t of graph.traces) {
-            if (t.type === 'allocate')
-                continue; // allocate itself doesn't count as coupling
-            if (modFuncIds.has(t.source) && !modFuncIds.has(t.target) && t.target !== mod.id) {
-                indirectOut++;
-            }
-            if (modFuncIds.has(t.target) && !modFuncIds.has(t.source) && t.source !== mod.id) {
-                indirectIn++;
-            }
-        }
-        const fanOut = directOut + indirectOut;
-        const fanIn = directIn + indirectIn;
-        if (fanIn + fanOut === 0)
+    // CR-SM-232: EINE Rechnung, zwei Ausgaben. Die fan_in/fan_out-Formel steht in
+    // `measureModules` — hier wird nur noch geschwellt. Sonst stünde die Formel
+    // doppelt im selben File und der Export wäre eine zweite Implementierung.
+    for (const m of measureModules(graph)) {
+        if (m.instability === null)
             continue;
-        const instability = fanOut / (fanIn + fanOut);
-        if (instability > INSTABILITY_THRESHOLD) {
+        if (m.instability > INSTABILITY_THRESHOLD) {
             violations.push({
                 rule_id: 'MT-01',
                 severity: 'warning',
-                element_id: mod.id,
-                message: `${mod.name} has instability ${Math.round(instability * 100)}% (>${INSTABILITY_THRESHOLD * 100}%). fan_in=${fanIn}, fan_out=${fanOut}`,
+                element_id: m.moduleId,
+                message: `${m.moduleName} has instability ${Math.round(m.instability * 100)}% (>${INSTABILITY_THRESHOLD * 100}%). fan_in=${m.fanIn}, fan_out=${m.fanOut}`,
             });
         }
     }
@@ -53,99 +32,16 @@ export function mt01Instability(graph) {
  */
 export function mt02Lcom4(graph) {
     const violations = [];
-    const mods = graph.elements.filter(e => e.type === 'MOD');
-    for (const mod of mods) {
-        // Find all FUNCs allocated to this MOD
-        const allocTraces = graph.traces.filter(t => t.type === 'allocate' && t.target === mod.id);
-        const funcIds = allocTraces.map(t => t.source);
-        if (funcIds.length < 2)
+    // CR-SM-232: die Union-Find-Rechnung steht in `measureModules`; hier nur die Stufen.
+    for (const m of measureModules(graph)) {
+        if (m.lcom4 === null)
             continue;
-        // Build adjacency: two FUNCs are connected if they share a common io/satisfy target
-        const funcTargets = new Map();
-        for (const fid of funcIds) {
-            const targets = new Set();
-            for (const t of graph.traces) {
-                if (t.source === fid && (t.type === 'io' || t.type === 'satisfy')) {
-                    targets.add(t.target);
-                }
-            }
-            funcTargets.set(fid, targets);
+        const message = `${m.moduleName} has LCOM4=${m.lcom4} (${m.allocatedFuncs} FUNCs in ${m.lcom4} disconnected groups)`;
+        if (m.lcom4 >= 4 && m.lcom4 <= 5) {
+            violations.push({ rule_id: 'MT-02', severity: 'info', element_id: m.moduleId, message });
         }
-        // Count connected components via union-find
-        const parent = new Map();
-        for (const fid of funcIds)
-            parent.set(fid, fid);
-        function find(x) {
-            while (parent.get(x) !== x) {
-                x = parent.get(x);
-            }
-            return x;
-        }
-        function union(a, b) {
-            const ra = find(a), rb = find(b);
-            if (ra !== rb)
-                parent.set(ra, rb);
-        }
-        for (let i = 0; i < funcIds.length; i++) {
-            for (let j = i + 1; j < funcIds.length; j++) {
-                const ti = funcTargets.get(funcIds[i]);
-                const tj = funcTargets.get(funcIds[j]);
-                // Check if they share any target
-                for (const t of ti) {
-                    if (tj.has(t)) {
-                        union(funcIds[i], funcIds[j]);
-                        break;
-                    }
-                }
-            }
-        }
-        // CR-165/CR-171: FUNCs sharing the same FLOW (via io in either direction) are connected
-        const funcIdSet = new Set(funcIds);
-        const flowToFuncs = new Map();
-        for (const t of graph.traces) {
-            if (t.type !== 'io')
-                continue;
-            // FLOW→FUNC direction
-            if (funcIdSet.has(t.target)) {
-                const srcEl = graph.elements.find(e => e.id === t.source);
-                if (srcEl?.type === 'FLOW') {
-                    if (!flowToFuncs.has(t.source))
-                        flowToFuncs.set(t.source, new Set());
-                    flowToFuncs.get(t.source).add(t.target);
-                }
-            }
-            // FUNC→FLOW direction (CR-171)
-            if (funcIdSet.has(t.source)) {
-                const tgtEl = graph.elements.find(e => e.id === t.target);
-                if (tgtEl?.type === 'FLOW') {
-                    if (!flowToFuncs.has(t.target))
-                        flowToFuncs.set(t.target, new Set());
-                    flowToFuncs.get(t.target).add(t.source);
-                }
-            }
-        }
-        for (const funcsInFlow of flowToFuncs.values()) {
-            const arr = [...funcsInFlow];
-            for (let i = 1; i < arr.length; i++)
-                union(arr[0], arr[i]);
-        }
-        const roots = new Set(funcIds.map(find));
-        const lcom4 = roots.size;
-        if (lcom4 >= 4 && lcom4 <= 5) {
-            violations.push({
-                rule_id: 'MT-02',
-                severity: 'info',
-                element_id: mod.id,
-                message: `${mod.name} has LCOM4=${lcom4} (${funcIds.length} FUNCs in ${lcom4} disconnected groups)`,
-            });
-        }
-        else if (lcom4 > 5) {
-            violations.push({
-                rule_id: 'MT-02',
-                severity: 'warning',
-                element_id: mod.id,
-                message: `${mod.name} has LCOM4=${lcom4} (${funcIds.length} FUNCs in ${lcom4} disconnected groups)`,
-            });
+        else if (m.lcom4 > 5) {
+            violations.push({ rule_id: 'MT-02', severity: 'warning', element_id: m.moduleId, message });
         }
     }
     return violations;
@@ -204,59 +100,181 @@ function connectionPairs(graph) {
     return pairs;
 }
 /**
- * Allocation cohesion — a **measurement, not a rule** (CR-SM-223, decision 2026-07-29).
- *
- * It used to be MT-03 with an 80 % threshold, and it fired on nearly every module of
- * every real graph: 6 of 7 on graphcode, 4 of 4 on graph-view-edit, 10 of 11 on the
- * family graph. `CR-SM-221` first suspected the edge definition and made it
- * FLOW-transitive — the hit rate did not move. The threshold was the miscalibration:
- * in a flow-routed layered architecture, module interaction crosses boundaries by
- * design, so "80 % of interaction is internal" describes a monolith, not a healthy
- * module.
+ * The one per-module computation (CR-SM-232) — in GRAPH ORDER, unsorted.
  *
- * Rather than fit a cut-off to 11 data points, this reports the number and lets the
- * architect judge. Returned worst-first, so the head of the list is where to look.
- * Modules with fewer than two allocated FUNCs, or with no external connection at all,
- * carry no signal and are omitted.
+ * `mt01Instability` and `mt02Lcom4` consume this and only threshold; `moduleMetrics()`
+ * exports a sorted copy. Keeping the internal list in `graph.elements` order is what
+ * makes the violation ORDER of both rules byte-identical to the pre-CR implementation
+ * — the export's worst-first ranking must not leak into the rule output.
  *
- * Deliberately NOT a `RuleDefinition`: `computeReadiness` counts every violation into
- * its dimension score regardless of severity, so a per-module advisory would depress
- * the `alloc` score permanently. A measurement must not masquerade as a defect.
- *
- * Validation of this metric — and of MT-01/MT-02, which are thresholded the same way —
- * is deferred (CR-SM-223).
+ * Every value that is not measurable is `null`, never 0: a module with one allocated
+ * FUNC has no LCOM4, and a 1 there would be an invented statement about cohesion.
  */
-export function allocationCohesion(graph) {
-    const measurements = [];
+function measureModules(graph) {
     const mods = graph.elements.filter(e => e.type === 'MOD');
     const pairs = [...connectionPairs(graph)].map(p => p.split('|'));
+    const rows = [];
     for (const mod of mods) {
-        const funcIds = new Set(graph.traces.filter(t => t.type === 'allocate' && t.target === mod.id).map(t => t.source));
-        if (funcIds.size < 2)
-            continue;
-        let internal = 0;
-        let external = 0;
-        for (const [a, b] of pairs) {
-            const aIn = funcIds.has(a);
-            const bIn = funcIds.has(b);
-            if (aIn && bIn)
-                internal++;
-            else if (aIn || bIn)
-                external++;
+        const allocated = graph.traces
+            .filter(t => t.type === 'allocate' && t.target === mod.id)
+            .map(t => t.source);
+        const modFuncIds = new Set(allocated);
+        // --- MT-01: fan-in / fan-out (CR-165, indirect via the allocate path) ---
+        const directOut = graph.traces.filter(t => t.source === mod.id && (t.type === 'io' || t.type === 'compose') && t.target !== mod.id).length;
+        const directIn = graph.traces.filter(t => t.target === mod.id && (t.type === 'io' || t.type === 'compose' || t.type === 'allocate')).length;
+        let indirectOut = 0;
+        let indirectIn = 0;
+        for (const t of graph.traces) {
+            if (t.type === 'allocate')
+                continue; // allocate itself doesn't count as coupling
+            if (modFuncIds.has(t.source) && !modFuncIds.has(t.target) && t.target !== mod.id)
+                indirectOut++;
+            if (modFuncIds.has(t.target) && !modFuncIds.has(t.source) && t.source !== mod.id)
+                indirectIn++;
         }
-        // No external connections → nothing to compare against, no signal.
-        if (external === 0)
-            continue;
-        measurements.push({
+        const fanOut = directOut + indirectOut;
+        const fanIn = directIn + indirectIn;
+        const instability = fanIn + fanOut === 0 ? null : fanOut / (fanIn + fanOut);
+        rows.push({
             moduleId: mod.id,
             moduleName: mod.name,
-            internal,
-            external,
-            cohesion: internal / (internal + external),
+            allocatedFuncs: allocated.length,
+            fanIn,
+            fanOut,
+            instability,
+            lcom4: lcom4Of(graph, allocated),
+            cohesion: cohesionOf(pairs, modFuncIds),
         });
     }
-    // Worst first; stable by id so the ranking is deterministic.
-    return measurements.sort((a, b) => a.cohesion - b.cohesion || (a.moduleId < b.moduleId ? -1 : a.moduleId > b.moduleId ? 1 : 0));
+    return rows;
+}
+/** MT-02 core: connected components over the allocated FUNCs. null below 2 FUNCs. */
+function lcom4Of(graph, funcIds) {
+    if (funcIds.length < 2)
+        return null;
+    // Two FUNCs are connected if they share a common io/satisfy target.
+    const funcTargets = new Map();
+    for (const fid of funcIds) {
+        const targets = new Set();
+        for (const t of graph.traces) {
+            if (t.source === fid && (t.type === 'io' || t.type === 'satisfy'))
+                targets.add(t.target);
+        }
+        funcTargets.set(fid, targets);
+    }
+    const parent = new Map();
+    for (const fid of funcIds)
+        parent.set(fid, fid);
+    function find(x) {
+        while (parent.get(x) !== x) {
+            x = parent.get(x);
+        }
+        return x;
+    }
+    function union(a, b) {
+        const ra = find(a), rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    }
+    for (let i = 0; i < funcIds.length; i++) {
+        for (let j = i + 1; j < funcIds.length; j++) {
+            const ti = funcTargets.get(funcIds[i]);
+            const tj = funcTargets.get(funcIds[j]);
+            for (const t of ti) {
+                if (tj.has(t)) {
+                    union(funcIds[i], funcIds[j]);
+                    break;
+                }
+            }
+        }
+    }
+    // CR-165/CR-171: FUNCs sharing the same FLOW (via io in either direction) are connected.
+    const funcIdSet = new Set(funcIds);
+    const flowToFuncs = new Map();
+    for (const t of graph.traces) {
+        if (t.type !== 'io')
+            continue;
+        if (funcIdSet.has(t.target)) {
+            const srcEl = graph.elements.find(e => e.id === t.source);
+            if (srcEl?.type === 'FLOW') {
+                if (!flowToFuncs.has(t.source))
+                    flowToFuncs.set(t.source, new Set());
+                flowToFuncs.get(t.source).add(t.target);
+            }
+        }
+        if (funcIdSet.has(t.source)) {
+            const tgtEl = graph.elements.find(e => e.id === t.target);
+            if (tgtEl?.type === 'FLOW') {
+                if (!flowToFuncs.has(t.target))
+                    flowToFuncs.set(t.target, new Set());
+                flowToFuncs.get(t.target).add(t.source);
+            }
+        }
+    }
+    for (const funcsInFlow of flowToFuncs.values()) {
+        const arr = [...funcsInFlow];
+        for (let i = 1; i < arr.length; i++)
+            union(arr[0], arr[i]);
+    }
+    return new Set(funcIds.map(find)).size;
+}
+/** CR-SM-223 core: internal vs. external connection pairs. null where there is no signal. */
+function cohesionOf(pairs, funcIds) {
+    if (funcIds.size < 2)
+        return null;
+    let internal = 0;
+    let external = 0;
+    for (const [a, b] of pairs) {
+        const aIn = funcIds.has(a);
+        const bIn = funcIds.has(b);
+        if (aIn && bIn)
+            internal++;
+        else if (aIn || bIn)
+            external++;
+    }
+    // No external connections → nothing to compare against, no signal.
+    if (external === 0)
+        return null;
+    return { internal, external, ratio: internal / (internal + external) };
+}
+/**
+ * Per-module architecture metrics as NUMBERS — one row per MOD, threshold or not
+ * (CR-SM-232).
+ *
+ * MT-01 only ever reported the modules above 70 %, MT-02 only those with ≥ 4
+ * components, and both only inside a prose `message`. For every module below the
+ * threshold there was no value, there was nothing — so a trend ("was 62 %, is 68 %"),
+ * the actual steering signal, was unobtainable. This exports what the rules already
+ * compute; it invents no metric and calibrates no threshold.
+ *
+ * Sorted worst cohesion first (as `allocationCohesion` does — the ranking IS the
+ * signal); modules without a cohesion measurement follow, stable by `moduleId`.
+ */
+export function moduleMetrics(graph) {
+    const byId = (a, b) => a.moduleId < b.moduleId ? -1 : a.moduleId > b.moduleId ? 1 : 0;
+    return measureModules(graph).sort((a, b) => {
+        if (a.cohesion && b.cohesion)
+            return a.cohesion.ratio - b.cohesion.ratio || byId(a, b);
+        if (a.cohesion)
+            return -1;
+        if (b.cohesion)
+            return 1;
+        return byId(a, b);
+    });
+}
+export function allocationCohesion(graph) {
+    // CR-SM-232: dieselbe Rechnung wie `moduleMetrics` — hier nur die Projektion auf
+    // die Module MIT Messwert. Zwei Implementierungen derselben Kohäsion wären genau
+    // die Drift, gegen die dieser CR angetreten ist.
+    return moduleMetrics(graph)
+        .filter((m) => m.cohesion !== null)
+        .map((m) => ({
+        moduleId: m.moduleId,
+        moduleName: m.moduleName,
+        internal: m.cohesion.internal,
+        external: m.cohesion.external,
+        cohesion: m.cohesion.ratio,
+    }));
 }
 export const MT_RULES = [
     { id: 'MT-01', name: 'Module instability', severity: 'warning', evaluate: mt01Instability },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",