@sigloch/contracts 0.7.0

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

@@ -0,0 +1,45 @@
+/**
+ * CR-121 P3: Architecture Metrics MT-01..MT-03.
+ * Module-level metrics computed from graph structure.
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleViolation } from './rules.js';
+/**
+ * MT-01: Module Instability (CR-165: indirect via allocate-path).
+ * I = fan_out / (fan_in + fan_out) > 0.7 → warning.
+ * fan_out = traces from FUNCs-in-module pointing to elements OUTSIDE the module.
+ * fan_in = traces from OUTSIDE pointing to FUNCs-in-module.
+ * Direct MOD→MOD io/compose traces also count.
+ */
+export declare function mt01Instability(graph: OntologyGraph): RuleViolation[];
+/**
+ * MT-02: LCOM4 (Lack of Cohesion — component count).
+ * MOD with allocated FUNCs that share no common io/satisfy targets → cohesion problem.
+ * Components > 1 → info.
+ */
+export declare function mt02Lcom4(graph: OntologyGraph): RuleViolation[];
+/**
+ * MT-03: Allocation Cohesion (CR-191: reformulated).
+ * cohesion = internal_flows / (internal_flows + external_flows).
+ * internal_flows = io traces between FUNCs within the same module.
+ * external_flows = io traces crossing module boundary (one end inside, one outside).
+ * If external_flows === 0 → cohesion = 100% → OK.
+ */
+export declare function mt03AllocationCohesion(graph: OntologyGraph): RuleViolation[];
+export declare const MT_RULES: readonly [{
+    readonly id: "MT-01";
+    readonly name: "Module instability";
+    readonly severity: "warning";
+    readonly evaluate: typeof mt01Instability;
+}, {
+    readonly id: "MT-02";
+    readonly name: "Module cohesion (LCOM4)";
+    readonly severity: "info";
+    readonly evaluate: typeof mt02Lcom4;
+}, {
+    readonly id: "MT-03";
+    readonly name: "Allocation cohesion";
+    readonly severity: "info";
+    readonly evaluate: typeof mt03AllocationCohesion;
+}];
+export declare function evaluateMTRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/metric-rules.js

@@ -0,0 +1,208 @@
+const INSTABILITY_THRESHOLD = 0.7;
+/**
+ * MT-01: Module Instability (CR-165: indirect via allocate-path).
+ * I = fan_out / (fan_in + fan_out) > 0.7 → warning.
+ * fan_out = traces from FUNCs-in-module pointing to elements OUTSIDE the module.
+ * fan_in = traces from OUTSIDE pointing to FUNCs-in-module.
+ * Direct MOD→MOD io/compose traces also count.
+ */
+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)
+            continue;
+        const instability = fanOut / (fanIn + fanOut);
+        if (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}`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * MT-02: LCOM4 (Lack of Cohesion — component count).
+ * MOD with allocated FUNCs that share no common io/satisfy targets → cohesion problem.
+ * Components > 1 → info.
+ */
+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)
+            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);
+        }
+        // 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)`,
+            });
+        }
+    }
+    return violations;
+}
+/**
+ * MT-03: Allocation Cohesion (CR-191: reformulated).
+ * cohesion = internal_flows / (internal_flows + external_flows).
+ * internal_flows = io traces between FUNCs within the same module.
+ * external_flows = io traces crossing module boundary (one end inside, one outside).
+ * If external_flows === 0 → cohesion = 100% → OK.
+ */
+export function mt03AllocationCohesion(graph) {
+    const violations = [];
+    const mods = graph.elements.filter(e => e.type === 'MOD');
+    const COHESION_THRESHOLD = 0.8;
+    for (const mod of mods) {
+        const allocTraces = graph.traces.filter(t => t.type === 'allocate' && t.target === mod.id);
+        const funcIds = new Set(allocTraces.map(t => t.source));
+        if (funcIds.size < 2)
+            continue;
+        let internalFlows = 0;
+        let externalFlows = 0;
+        for (const t of graph.traces) {
+            if (t.type !== 'io')
+                continue;
+            const srcIn = funcIds.has(t.source);
+            const tgtIn = funcIds.has(t.target);
+            if (srcIn && tgtIn) {
+                internalFlows++;
+            }
+            else if (srcIn || tgtIn) {
+                externalFlows++;
+            }
+        }
+        // No external flows → cohesion = 100% → OK
+        if (externalFlows === 0)
+            continue;
+        const total = internalFlows + externalFlows;
+        if (total === 0)
+            continue;
+        const cohesion = internalFlows / total;
+        if (cohesion < COHESION_THRESHOLD) {
+            violations.push({
+                rule_id: 'MT-03',
+                severity: 'info',
+                element_id: mod.id,
+                message: `${mod.name} allocation cohesion ${Math.round(cohesion * 100)}% (<${COHESION_THRESHOLD * 100}%). internal=${internalFlows}, external=${externalFlows}`,
+            });
+        }
+    }
+    return violations;
+}
+export const MT_RULES = [
+    { id: 'MT-01', name: 'Module instability', severity: 'warning', evaluate: mt01Instability },
+    { id: 'MT-02', name: 'Module cohesion (LCOM4)', severity: 'info', evaluate: mt02Lcom4 },
+    { id: 'MT-03', name: 'Allocation cohesion', severity: 'info', evaluate: mt03AllocationCohesion },
+];
+export function evaluateMTRules(graph) {
+    return MT_RULES.flatMap(r => r.evaluate(graph));
+}

package/dist/se/near-duplicate-rules.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CR-121 P2: Near-Duplicate Detection for FUNC and SCHEMA elements.
+ * Uses pre-injected similarity matrices (same pattern as BQ-04).
+ */
+import type { OntologyGraph } from './ontology.js';
+import type { RuleViolation } from './rules.js';
+/**
+ * Inject pre-computed similarity matrix for FUNC elements.
+ * Similarity = 0.35 × descr_jaccard + 0.25 × verb_match + 0.25 × io_topology + 0.15 × req_overlap
+ */
+export declare function setND01SimilarityMatrix(data: {
+    funcIds: string[];
+    matrix: number[][];
+} | null): void;
+/** ND-01: FUNC pairs with similarity >= 0.85 → error. */
+export declare function nd01FuncNearDuplicate(graph: OntologyGraph): RuleViolation[];
+/**
+ * Inject pre-computed similarity matrix for SCHEMA elements.
+ * Similarity = 0.50 × field_jaccard + 0.30 × descr_jaccard + 0.20 × usage_overlap
+ */
+export declare function setND02SimilarityMatrix(data: {
+    schemaIds: string[];
+    matrix: number[][];
+} | null): void;
+/** Read-only access to current ND-02 matrix (used by AO-D01 for schema overlap). */
+export declare function getND02SimilarityMatrix(): {
+    schemaIds: string[];
+    matrix: number[][];
+} | null;
+/** ND-02: SCHEMA pairs with similarity >= 0.85 → error. */
+export declare function nd02SchemaNearDuplicate(graph: OntologyGraph): RuleViolation[];
+export declare const ND_RULES: readonly [{
+    readonly id: "ND-01";
+    readonly name: "FuncNearDuplicate";
+    readonly severity: "error";
+    readonly evaluate: typeof nd01FuncNearDuplicate;
+}, {
+    readonly id: "ND-02";
+    readonly name: "SchemaNearDuplicate";
+    readonly severity: "error";
+    readonly evaluate: typeof nd02SchemaNearDuplicate;
+}];
+/** Evaluate all near-duplicate rules. */
+export declare function evaluateNDRules(graph: OntologyGraph): RuleViolation[];

package/dist/se/near-duplicate-rules.js

@@ -0,0 +1,106 @@
+const ND_SIMILARITY_THRESHOLD = 0.85;
+// ---------------------------------------------------------------------------
+// ND-01: FUNC near-duplicates
+// ---------------------------------------------------------------------------
+let _nd01Matrix = null;
+/**
+ * Inject pre-computed similarity matrix for FUNC elements.
+ * Similarity = 0.35 × descr_jaccard + 0.25 × verb_match + 0.25 × io_topology + 0.15 × req_overlap
+ */
+export function setND01SimilarityMatrix(data) {
+    _nd01Matrix = data;
+}
+/** ND-01: FUNC pairs with similarity >= 0.85 → error. */
+export function nd01FuncNearDuplicate(graph) {
+    if (!_nd01Matrix)
+        return [];
+    const { funcIds, matrix } = _nd01Matrix;
+    const violations = [];
+    const seen = new Set();
+    for (let i = 0; i < funcIds.length; i++) {
+        for (let j = i + 1; j < funcIds.length; j++) {
+            const sim = matrix[i][j];
+            if (sim < ND_SIMILARITY_THRESHOLD)
+                continue;
+            const pairKey = `${funcIds[i]}:${funcIds[j]}`;
+            if (seen.has(pairKey))
+                continue;
+            seen.add(pairKey);
+            const pct = Math.round(sim * 100);
+            const elI = graph.elements.find(e => e.id === funcIds[i]);
+            const elJ = graph.elements.find(e => e.id === funcIds[j]);
+            violations.push({
+                rule_id: 'ND-01',
+                severity: 'error',
+                element_id: funcIds[j],
+                message: `${funcIds[j]}${elJ?.name ? ' (' + elJ.name + ')' : ''} is ${pct}% similar to ${funcIds[i]}${elI?.name ? ' (' + elI.name + ')' : ''} — potential duplicate function`,
+                fix_hint: 'Merge into single FUNC or differentiate responsibilities',
+                context: {
+                    element_type: elJ?.type,
+                    element_name: elJ?.name,
+                },
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// ND-02: SCHEMA near-duplicates
+// ---------------------------------------------------------------------------
+let _nd02Matrix = null;
+/**
+ * Inject pre-computed similarity matrix for SCHEMA elements.
+ * Similarity = 0.50 × field_jaccard + 0.30 × descr_jaccard + 0.20 × usage_overlap
+ */
+export function setND02SimilarityMatrix(data) {
+    _nd02Matrix = data;
+}
+/** Read-only access to current ND-02 matrix (used by AO-D01 for schema overlap). */
+export function getND02SimilarityMatrix() {
+    return _nd02Matrix;
+}
+/** ND-02: SCHEMA pairs with similarity >= 0.85 → error. */
+export function nd02SchemaNearDuplicate(graph) {
+    if (!_nd02Matrix)
+        return [];
+    const { schemaIds, matrix } = _nd02Matrix;
+    const violations = [];
+    const seen = new Set();
+    for (let i = 0; i < schemaIds.length; i++) {
+        for (let j = i + 1; j < schemaIds.length; j++) {
+            const sim = matrix[i][j];
+            if (sim < ND_SIMILARITY_THRESHOLD)
+                continue;
+            const pairKey = `${schemaIds[i]}:${schemaIds[j]}`;
+            if (seen.has(pairKey))
+                continue;
+            seen.add(pairKey);
+            const pct = Math.round(sim * 100);
+            const elI = graph.elements.find(e => e.id === schemaIds[i]);
+            const elJ = graph.elements.find(e => e.id === schemaIds[j]);
+            violations.push({
+                rule_id: 'ND-02',
+                severity: 'error',
+                element_id: schemaIds[j],
+                message: `${schemaIds[j]}${elJ?.name ? ' (' + elJ.name + ')' : ''} is ${pct}% similar to ${schemaIds[i]}${elI?.name ? ' (' + elI.name + ')' : ''} — potential duplicate schema`,
+                fix_hint: 'Merge schemas or differentiate field sets',
+                context: {
+                    element_type: elJ?.type,
+                    element_name: elJ?.name,
+                },
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// Aggregate
+// ---------------------------------------------------------------------------
+export const ND_RULES = [
+    { id: 'ND-01', name: 'FuncNearDuplicate', severity: 'error', evaluate: nd01FuncNearDuplicate },
+    { id: 'ND-02', name: 'SchemaNearDuplicate', severity: 'error', evaluate: nd02SchemaNearDuplicate },
+];
+/** Evaluate all near-duplicate rules. */
+export function evaluateNDRules(graph) {
+    return ND_RULES.flatMap(r => r.evaluate(graph));
+}