@sigloch/contracts 0.7.0

package/dist/se/ao-rules.js

@@ -0,0 +1,341 @@
+import { getND02SimilarityMatrix } from './near-duplicate-rules.js';
+const SCHEMA_OVERLAP_THRESHOLD = 0.5;
+/**
+ * AO-D01: Relay Node Detection.
+ * A FUNC is a relay if it (a) satisfies no REQ, (b) has >=2 outgoing io to FUNCs,
+ * and (c) target FUNCs share SCHEMA overlap >= 0.5 (via ND-02 matrix, skipped if unavailable).
+ */
+export function aoD01RelayNode(graph) {
+    const violations = [];
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    const funcIdSet = new Set(funcs.map(f => f.id));
+    for (const func of funcs) {
+        // (a) No satisfy traces (FUNC as source) connecting to any REQ
+        const hasSatisfy = graph.traces.some(t => t.type === 'satisfy' &&
+            t.source === func.id && graph.elements.some(e => e.id === t.target && e.type === 'REQ'));
+        if (hasSatisfy)
+            continue;
+        // (b) >=2 outgoing io traces to other FUNCs
+        const ioTargets = graph.traces
+            .filter(t => t.type === 'io' && t.source === func.id && funcIdSet.has(t.target))
+            .map(t => t.target);
+        if (ioTargets.length < 2)
+            continue;
+        // (c) Target FUNCs share SCHEMA overlap >= 0.5 (skip check if no matrix)
+        if (!passesSchemaOverlap(graph, ioTargets))
+            continue;
+        const el = graph.elements.find(e => e.id === func.id);
+        violations.push({
+            rule_id: 'AO-D01',
+            severity: 'info',
+            element_id: func.id,
+            message: `${func.id}${el?.name ? ' (' + el.name + ')' : ''} is a relay node: no REQ satisfied, ${ioTargets.length} io targets`,
+            fix_hint: 'Consider eliminating relay by connecting consumers directly to producer',
+        });
+    }
+    return violations;
+}
+/** CR-165: Resolve FUNC→SCHEMA via FUNC→FLOW(io) + FLOW→SCHEMA(relation). */
+function funcToSchemas(graph, funcId) {
+    const schemas = new Set();
+    // Find FLOWs connected to this FUNC via io (FUNC→FLOW or FLOW→FUNC)
+    const flowIds = new Set();
+    for (const t of graph.traces) {
+        if (t.type === 'io') {
+            if (t.source === funcId && graph.elements.some(e => e.id === t.target && e.type === 'FLOW')) {
+                flowIds.add(t.target);
+            }
+            if (t.target === funcId && graph.elements.some(e => e.id === t.source && e.type === 'FLOW')) {
+                flowIds.add(t.source);
+            }
+        }
+    }
+    // Find SCHEMAs connected to those FLOWs via relation
+    for (const t of graph.traces) {
+        if (t.type === 'relation' && flowIds.has(t.source) && graph.elements.some(e => e.id === t.target && e.type === 'SCHEMA')) {
+            schemas.add(t.target);
+        }
+    }
+    return schemas;
+}
+/** Check if any pair of target FUNCs shares SCHEMA overlap via FLOW→SCHEMA(relation) + ND-02 matrix. */
+function passesSchemaOverlap(graph, targetFuncIds) {
+    const nd02 = getND02SimilarityMatrix();
+    if (!nd02)
+        return true; // no matrix → skip check, assume pass
+    // For each target FUNC, collect connected SCHEMA ids via FLOW→SCHEMA(relation)
+    const funcSchemasMap = new Map();
+    for (const fid of targetFuncIds) {
+        funcSchemasMap.set(fid, funcToSchemas(graph, fid));
+    }
+    // Check pairwise: any pair of target FUNCs with overlapping SCHEMAs (similarity >= threshold)
+    const { schemaIds, matrix } = nd02;
+    const idxOf = new Map(schemaIds.map((id, i) => [id, i]));
+    for (let i = 0; i < targetFuncIds.length; i++) {
+        for (let j = i + 1; j < targetFuncIds.length; j++) {
+            const si = funcSchemasMap.get(targetFuncIds[i]);
+            const sj = funcSchemasMap.get(targetFuncIds[j]);
+            for (const a of si) {
+                for (const b of sj) {
+                    const ai = idxOf.get(a), bi = idxOf.get(b);
+                    if (ai !== undefined && bi !== undefined && matrix[ai][bi] >= SCHEMA_OVERLAP_THRESHOLD)
+                        return true;
+                    if (a === b)
+                        return true; // same SCHEMA = 100% overlap
+                }
+            }
+        }
+    }
+    return false;
+}
+/**
+ * AO-D03: Duplicate Path Detection.
+ * FUNC A sends io to both B and C, where B and C connect to the same SCHEMA elements.
+ */
+export function aoD03DuplicatePath(graph) {
+    const violations = [];
+    const funcs = graph.elements.filter(e => e.type === 'FUNC');
+    const funcIdSet = new Set(funcs.map(f => f.id));
+    const seen = new Set();
+    // Pre-compute: FUNC → set of SCHEMA targets via FLOW→SCHEMA(relation) (CR-165)
+    const funcToSchemasMap = new Map();
+    for (const f of funcs) {
+        funcToSchemasMap.set(f.id, funcToSchemas(graph, f.id));
+    }
+    for (const a of funcs) {
+        const ioTargets = graph.traces
+            .filter(t => t.type === 'io' && t.source === a.id && funcIdSet.has(t.target))
+            .map(t => t.target);
+        if (ioTargets.length < 2)
+            continue;
+        for (let i = 0; i < ioTargets.length; i++) {
+            for (let j = i + 1; j < ioTargets.length; j++) {
+                const b = ioTargets[i], c = ioTargets[j];
+                const key = [a.id, b, c].sort().join(':');
+                if (seen.has(key))
+                    continue;
+                const sb = funcToSchemasMap.get(b) ?? new Set();
+                const sc = funcToSchemasMap.get(c) ?? new Set();
+                const shared = [...sb].filter(s => sc.has(s));
+                if (shared.length === 0)
+                    continue;
+                seen.add(key);
+                violations.push({
+                    rule_id: 'AO-D03',
+                    severity: 'info',
+                    element_id: a.id,
+                    message: `${a.id} sends io to ${b} and ${c} which share ${shared.length} SCHEMA target(s): ${shared.join(', ')}`,
+                    fix_hint: 'Consider introducing a mediator or unifying the data paths',
+                });
+            }
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// CR-01: Crossing Flow Count (CR-191)
+// For each module pair (A, B): count io paths FUNC_A → FUNC_B
+// ---------------------------------------------------------------------------
+export function cr01CrossingFlowCount(graph) {
+    const violations = [];
+    const mods = graph.elements.filter(e => e.type === 'MOD');
+    // Build MOD → Set<FUNC-id> mapping
+    const modFuncs = new Map();
+    for (const mod of mods) {
+        const funcIds = new Set(graph.traces.filter(t => t.type === 'allocate' && t.target === mod.id).map(t => t.source));
+        modFuncs.set(mod.id, funcIds);
+    }
+    // Count crossings per module pair
+    const pairCounts = new Map();
+    for (const t of graph.traces) {
+        if (t.type !== 'io')
+            continue;
+        let srcMod;
+        let tgtMod;
+        for (const [mid, fids] of modFuncs) {
+            if (fids.has(t.source))
+                srcMod = mid;
+            if (fids.has(t.target))
+                tgtMod = mid;
+        }
+        if (!srcMod || !tgtMod || srcMod === tgtMod)
+            continue;
+        const key = [srcMod, tgtMod].sort().join('::');
+        if (!pairCounts.has(key))
+            pairCounts.set(key, { modA: srcMod, modB: tgtMod, count: 0 });
+        pairCounts.get(key).count++;
+    }
+    for (const { modA, modB, count } of pairCounts.values()) {
+        if (count <= 0)
+            continue;
+        const severity = count > 2 ? 'warning' : 'info';
+        violations.push({
+            rule_id: 'CR-01',
+            severity,
+            element_id: modA,
+            message: `${modA} ↔ ${modB}: ${count} crossing io flow(s)`,
+            fix_hint: count > 2 ? 'Reduce coupling between modules or introduce a mediator' : 'Consider if coupling is intentional',
+        });
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// RT-01: Physical boundary integrity (CR-191)
+// FUNCs must not be allocated directly to physical MODs — use logical sub-modules.
+// ---------------------------------------------------------------------------
+export function rt01PhysicalBoundaryIntegrity(graph) {
+    const physicalMods = graph.elements.filter(e => e.type === 'MOD' && e.attributes?.kind === 'physical');
+    return graph.traces
+        .filter(t => t.type === 'allocate' && physicalMods.some(m => m.id === t.target))
+        .filter(t => graph.elements.some(e => e.id === t.source && e.type === 'FUNC'))
+        .map(t => ({
+        rule_id: 'RT-01',
+        severity: 'error',
+        element_id: t.source,
+        message: `${t.source} allocated directly to physical module ${t.target} — must use logical sub-module`,
+        fix_hint: 'Create a logical MOD inside the physical MOD and allocate the FUNC there',
+    }));
+}
+// ---------------------------------------------------------------------------
+// PH-01: Physical MOD completeness (CR-191)
+// Physical MODs should have at least one logical sub-module via compose trace.
+// ---------------------------------------------------------------------------
+export function ph01PhysicalModCompleteness(graph) {
+    const physicalMods = graph.elements.filter(e => e.type === 'MOD' && e.attributes?.kind === 'physical');
+    return physicalMods
+        .filter(pm => !graph.traces.some(t => t.source === pm.id && t.type === 'compose' &&
+        graph.elements.some(e => e.id === t.target && e.type === 'MOD')))
+        .map(pm => ({
+        rule_id: 'PH-01',
+        severity: 'info',
+        element_id: pm.id,
+        message: `${pm.id} (physical) has no logical sub-modules`,
+        fix_hint: 'Add at least one logical MOD via compose trace',
+        context: { element_type: pm.type, element_name: pm.name },
+    }));
+}
+// ---------------------------------------------------------------------------
+// CA-01: Capability allocation check (CR-191)
+// FUNC @requires must be satisfied by the physical MOD's @capability.
+// ---------------------------------------------------------------------------
+export function ca01CapabilityAllocation(graph) {
+    const violations = [];
+    const funcsWithRequires = graph.elements.filter(e => e.type === 'FUNC' && e.attributes?.requires);
+    for (const func of funcsWithRequires) {
+        const requires = (Array.isArray(func.attributes.requires)
+            ? func.attributes.requires
+            : [func.attributes.requires]);
+        // Find logical MOD via allocate
+        const allocTrace = graph.traces.find(t => t.source === func.id && t.type === 'allocate');
+        if (!allocTrace)
+            continue;
+        const logicalMod = graph.elements.find(e => e.id === allocTrace.target && e.type === 'MOD');
+        if (!logicalMod)
+            continue;
+        // Find physical parent MOD (compose source → logical MOD target)
+        const physParentTrace = graph.traces.find(t => t.type === 'compose' && t.target === logicalMod.id &&
+            graph.elements.some(e => e.id === t.source && e.type === 'MOD' && e.attributes?.kind === 'physical'));
+        if (!physParentTrace)
+            continue;
+        const physMod = graph.elements.find(e => e.id === physParentTrace.source);
+        const capabilities = (Array.isArray(physMod.attributes?.capability)
+            ? physMod.attributes.capability
+            : physMod.attributes?.capability ? [physMod.attributes.capability] : []);
+        const missing = requires.filter(r => !capabilities.includes(r));
+        if (missing.length > 0) {
+            violations.push({
+                rule_id: 'CA-01',
+                severity: 'error',
+                element_id: func.id,
+                message: `${func.id} requires [${missing.join(', ')}] but ${physMod.id} only provides [${capabilities.join(', ')}]`,
+                fix_hint: `Add missing capabilities to ${physMod.id} or move ${func.id} to a capable module`,
+                context: { element_type: func.type, element_name: func.name, parent_module: physMod.id },
+            });
+        }
+    }
+    return violations;
+}
+// ---------------------------------------------------------------------------
+// IO-01: Cross-module IO completeness (CR-192)
+// For each FCHAIN, FUNCs in different MODs must have a FLOW path between them.
+// ---------------------------------------------------------------------------
+export function io01CrossModuleCompleteness(graph) {
+    const violations = [];
+    const fchains = graph.elements.filter(e => e.type === 'FCHAIN');
+    for (const fc of fchains) {
+        // Get FUNCs in this FCHAIN via compose
+        const funcIds = graph.traces
+            .filter(t => t.source === fc.id && t.type === 'compose')
+            .map(t => t.target)
+            .filter(id => graph.elements.some(e => e.id === id && e.type === 'FUNC'));
+        if (funcIds.length < 2)
+            continue;
+        // Map FUNC→MOD via allocate
+        const funcToMod = new Map();
+        for (const fid of funcIds) {
+            const allocTrace = graph.traces.find(t => t.source === fid && t.type === 'allocate');
+            if (allocTrace)
+                funcToMod.set(fid, allocTrace.target);
+        }
+        // For each pair of FUNCs in different MODs, check for FLOW path
+        const checked = new Set();
+        for (const fA of funcIds) {
+            for (const fB of funcIds) {
+                if (fA >= fB)
+                    continue;
+                const modA = funcToMod.get(fA);
+                const modB = funcToMod.get(fB);
+                if (!modA || !modB || modA === modB)
+                    continue;
+                const pairKey = `${fA}:${fB}`;
+                if (checked.has(pairKey))
+                    continue;
+                checked.add(pairKey);
+                // Check if there's a FLOW path: fA→io→FLOW→io→fB or fB→io→FLOW→io→fA
+                const hasFlow = graph.traces.some(t1 => {
+                    if (t1.type !== 'io')
+                        return false;
+                    if (t1.source !== fA && t1.source !== fB)
+                        return false;
+                    const flowId = t1.target;
+                    const flowEl = graph.elements.find(e => e.id === flowId && e.type === 'FLOW');
+                    if (!flowEl)
+                        return false;
+                    const otherFunc = t1.source === fA ? fB : fA;
+                    return graph.traces.some(t2 => t2.type === 'io' &&
+                        ((t2.source === flowId && t2.target === otherFunc) ||
+                            (t2.target === flowId && t2.source === otherFunc)));
+                });
+                if (!hasFlow) {
+                    const elA = graph.elements.find(e => e.id === fA);
+                    const elB = graph.elements.find(e => e.id === fB);
+                    violations.push({
+                        rule_id: 'IO-01',
+                        severity: 'warning',
+                        element_id: fA,
+                        message: `${fA} (${modA}) and ${fB} (${modB}) in FCHAIN ${fc.id} have no IO path — missing FLOW?`,
+                        fix_hint: 'Add a FLOW element with io traces between these cross-module functions',
+                        context: {
+                            element_type: 'FUNC',
+                            element_name: elA?.name ?? fA,
+                            candidate_targets: elB ? [{ id: elB.id, type: elB.type, name: elB.name }] : undefined,
+                        },
+                    });
+                }
+            }
+        }
+    }
+    return violations;
+}
+export const AO_RULES = [
+    { id: 'AO-D01', name: 'RelayNodeDetection', severity: 'info', evaluate: aoD01RelayNode },
+    { id: 'AO-D03', name: 'DuplicatePathDetection', severity: 'info', evaluate: aoD03DuplicatePath },
+    { id: 'CR-01', name: 'CrossingFlowCount', severity: 'warning', evaluate: cr01CrossingFlowCount },
+    { id: 'RT-01', name: 'PhysicalBoundaryIntegrity', severity: 'error', evaluate: rt01PhysicalBoundaryIntegrity },
+    { id: 'PH-01', name: 'PhysicalModCompleteness', severity: 'info', evaluate: ph01PhysicalModCompleteness },
+    { id: 'CA-01', name: 'CapabilityAllocation', severity: 'error', evaluate: ca01CapabilityAllocation },
+    { id: 'IO-01', name: 'CrossModuleIOCompleteness', severity: 'warning', evaluate: io01CrossModuleCompleteness },
+];
+export function evaluateAORules(graph) {
+    return AO_RULES.flatMap(r => r.evaluate(graph));
+}

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

@@ -0,0 +1,64 @@
+/**
+ * RC conformance rules (CR-GC-253) — graph↔code resolution, the RESOLUTION
+ * twins of the presence rules R-20 (codeRef) / R-19 (testRef).
+ *
+ * Rules stay in THIS library (one rule base per onto set — no rule definitions
+ * in executor codebases). They are pure functions over (graph, facts): all
+ * filesystem/parser work happens in the executor (graphcode extracts CodeFacts
+ * from the repo), so this module stays I/O-free and browser-bundlable.
+ *
+ * CodeFacts semantics: `files` is keyed by repo-relative path and MUST contain
+ * an entry for every file referenced by a codeRef/testRef the extractor saw.
+ * A MISSING key is treated like `exists:false` — an extractor gap must surface
+ * loudly as a violation, never as a silent pass.
+ *
+ * @sigloch/contracts/se — single source of truth for SE validation rules.
+ */
+import { z } from 'zod/v4';
+import type { OntologyGraph } from './ontology.js';
+import type { RuleSeverity, RuleViolation } from './rules.js';
+/** Parser facts about one source file (extracted by the executor). */
+export declare const FileFactsSchema: z.ZodObject<{
+    exists: z.ZodBoolean;
+    declaredSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    testCases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    importedSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    parsedSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type FileFacts = z.infer<typeof FileFactsSchema>;
+/** One file→file import edge (repo-relative paths) — the module-drift evidence (CR-212). */
+export declare const ImportEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>;
+export type ImportEdge = z.infer<typeof ImportEdgeSchema>;
+/**
+ * Deterministic, serializable code facts — the data contract between the
+ * facts extractor (graphcode: TS parser today, ast-grep later — CR-GC-254)
+ * and the RC rules. Testable without any filesystem.
+ */
+export declare const CodeFactsSchema: z.ZodObject<{
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        exists: z.ZodBoolean;
+        declaredSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        testCases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        importedSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        parsedSymbols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    importEdges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CodeFacts = z.infer<typeof CodeFactsSchema>;
+/** A conformance rule: pure over (graph, facts) — never touches I/O itself. */
+export interface ConformanceRuleDefinition {
+    id: string;
+    name: string;
+    severity: RuleSeverity;
+    evaluate: (graph: OntologyGraph, facts: CodeFacts) => RuleViolation[];
+}
+/** All RC conformance rules — evaluated by executors that can supply CodeFacts. */
+export declare const CODE_CONFORMANCE_RULES: ConformanceRuleDefinition[];
+/** Run all RC rules against a graph + extracted code facts. */
+export declare function evaluateConformanceRules(graph: OntologyGraph, facts: CodeFacts): RuleViolation[];