@sigloch/contracts 9.1.0 → 10.1.0

package/dist/se/similarity.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CR-SM-286 — die Ähnlichkeitsrechnung von ND-01/ND-02/BQ-04, dort wo die Regeln stehen.
+ *
+ * ## Warum sie hierher gehört
+ *
+ * Bis hierher lebte die Formel als **Prosa** in `near-duplicate-rules.ts` und als **Code** in
+ * `graphcode/src/kernel/measure/nd-similarity.ts`, verbunden durch
+ * `setND01SimilarityMatrix()` / `setND02SimilarityMatrix()`. Zwei Pakete mussten sich über
+ * etwas einig sein, das nur eines von beiden ausführt.
+ *
+ * Die Naht kostete vier Dinge, alle gemessen:
+ *
+ * 1. **Fail-open.** Ohne Injektion gaben ND-01/ND-02 `[]` zurück — bei severity `error` und
+ *    ununterscheidbar von „keine Duplikate". Gemessen: moneyflow trägt 16 ND-01-Befunde, die
+ *    für JEDEN Konsumenten ausserhalb graphcodes unsichtbar waren (`report:silence`, die
+ *    Spike-Skripte, jedes künftige Werkzeug). Die Familie hat für „kann nicht urteilen" eine
+ *    Konvention — `policy.X = null`, `moduleMetrics.instability = null`, beide sagen es
+ *    ausdrücklich; ND fiel statt dessen nach grün.
+ * 2. **Prozessweiter Modulzustand.** `let _nd01Matrix` ist global. graphcode schützte sich mit
+ *    der Klammer `withNDMatrices(og, run)` und einem `finally`-Reset; jeder andere Aufrufer
+ *    nicht. Zwei Graphen nacheinander bewertet — und Graph A urteilt über Graph B.
+ * 3. **AO-D01 verstärkte es.** Die Regel liegt IM Gate-Katalog und übersprang ihre
+ *    Overlap-Prüfung, wenn keine Matrix da war („no matrix → assume pass"): eine Gate-Regel,
+ *    die sich stillschweigend abschwächt.
+ * 4. **BQ-04 ist am selben Muster komplett tot** — `setBQ04SimilarityMatrix()` ruft im ganzen
+ *    Familienbaum niemand (CR-SM-278, heute erneut geprüft).
+ *
+ * Präzedenz aus demselben Repo: CR-SM-276 hat `moduleCrossings` genau deshalb NACH contracts
+ * gelegt — damit zwei Regelköpfe (CR-01, R-04) EINE Definition von „Kreuzung" teilen. Hier ist
+ * es dieselbe Bewegung für drei Regelköpfe und eine Definition von „ähnlich".
+ *
+ * ## Was sich NICHT ändert
+ *
+ * Formeln, Gewichte und die Schwelle 0,85 sind zeichengleich aus graphcodes Implementierung
+ * übernommen. Das ist kein neues Urteil, es ist derselbe Code an der richtigen Stelle.
+ *
+ * Rein und deterministisch: kein Store, kein Transport, kein Filesystem, kein Zufall, keine
+ * Abhängigkeit ausserhalb der Ontologie. Ergebnisse hängen je Graph-Objekt im WeakMap-Cache,
+ * wie `moduleCrossings` — die Matrix ist O(n²) und wird je Voll-Lauf mehrfach gebraucht.
+ */
+import type { OntologyGraph } from './ontology.js';
+/** Wort-Token >= 3 Zeichen, lowercase, Unicode-Buchstaben/Ziffern. */
+export declare function tokens(s: unknown): Set<string>;
+/** Jaccard-Aehnlichkeit; leer/leer = 1 (identisch leer). */
+export declare function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+export interface SimilarityMatrix {
+    /** Element-uids in kanonischer Ordnung — der Index in `matrix`. */
+    readonly ids: readonly string[];
+    /** Symmetrisch, Diagonale 1. */
+    readonly matrix: readonly (readonly number[])[];
+}
+/** FUNC-Aehnlichkeit je Graph (ND-01). */
+export declare const funcSimilarity: (graph: OntologyGraph) => SimilarityMatrix;
+/** SCHEMA-Aehnlichkeit je Graph (ND-02, AO-D01). */
+export declare const schemaSimilarity: (graph: OntologyGraph) => SimilarityMatrix;
+/** Paare ueber der Schwelle, kanonisch geordnet (i < j) — die eine Schleife fuer alle drei Regeln. */
+export declare function pairsAbove(sim: SimilarityMatrix, threshold: number): Array<{
+    a: string;
+    b: string;
+    similarity: number;
+}>;

package/dist/se/similarity.js

@@ -0,0 +1,116 @@
+import { isValidTrace } from './meta-model.js';
+/** Wort-Token >= 3 Zeichen, lowercase, Unicode-Buchstaben/Ziffern. */
+export function tokens(s) {
+    const text = typeof s === 'string' ? s : '';
+    return new Set(text
+        .toLowerCase()
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(w => w.length >= 3));
+}
+/** Jaccard-Aehnlichkeit; leer/leer = 1 (identisch leer). */
+export function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter += 1;
+    const union = a.size + b.size - inter;
+    return union === 0 ? 1 : inter / union;
+}
+/**
+ * Partner-uids eines Elements ueber LEGALE Traces der genannten Typen.
+ *
+ * CR-SM-286: der Legalitaetsfilter ist nicht Kosmetik. Ohne ihn aenderte eine grammatikwidrige
+ * Kante das Urteil: `se-rule-pair-legality.test.ts` (Pruefung A, CR-SM-278) meldete **35**
+ * Faelle, in denen ND-02 erst durch eine injizierte illegale Kante auf SCHEMA anschlug —
+ * `ACTOR -compose-> SCHEMA`, `CR -io-> SCHEMA`, `FLOW -compose-> SCHEMA` und so fort. Eine
+ * Regel, deren Verdikt an einer Kante haengt, die R-18 als `error` ablehnt, urteilt ueber einen
+ * Graphen, den es nicht geben darf.
+ */
+function partners(graph, id, traceTypes) {
+    const byType = new Map(graph.elements.map(e => [e.id, e.type]));
+    const out = new Set();
+    for (const t of graph.traces) {
+        if (!traceTypes.includes(t.type))
+            continue;
+        if (t.source !== id && t.target !== id)
+            continue;
+        const src = byType.get(t.source);
+        const tgt = byType.get(t.target);
+        if (!src || !tgt)
+            continue; // haengende Kante -> R-08, nicht hier
+        if (!isValidTrace({ source: src, target: tgt, type: t.type }))
+            continue;
+        out.add(t.source === id ? t.target : t.source);
+    }
+    return out;
+}
+/** Erstes Wort des Namens als Verb-Naeherung (FUNC-Namen: Verb-Objekt). */
+function firstWord(name) {
+    const text = typeof name === 'string' ? name : '';
+    return text.toLowerCase().split(/[^\p{L}\p{N}]+/u).find(w => w.length > 0) ?? '';
+}
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/** Feld-Menge eines SCHEMA: `attributes.fields` (Array), sonst Beschreibungs-Token. */
+function schemaFields(el) {
+    const fields = el.attributes?.fields;
+    if (Array.isArray(fields) && fields.length > 0) {
+        return new Set(fields.map(f => String(typeof f === 'object' && f !== null ? (f.name ?? JSON.stringify(f)) : f).toLowerCase()));
+    }
+    return tokens(el.description);
+}
+const CACHE = new WeakMap();
+function build(graph) {
+    // ND-01: 0.35*descr_jaccard + 0.25*verb_match + 0.25*io_topology + 0.15*req_overlap
+    const funcs = graph.elements.filter(e => e.type === 'FUNC').sort(byId);
+    const fDescr = funcs.map(f => tokens(f.description));
+    const fVerb = funcs.map(f => firstWord(f.name));
+    const fIo = funcs.map(f => partners(graph, f.id, ['io']));
+    const fReq = funcs.map(f => new Set(graph.traces.filter(t => t.type === 'satisfy' && t.source === f.id).map(t => t.target)));
+    const func = {
+        ids: funcs.map(f => f.id),
+        matrix: funcs.map((_, i) => funcs.map((_, j) => i === j ? 1
+            : 0.35 * jaccard(fDescr[i], fDescr[j])
+                + 0.25 * (fVerb[i] !== '' && fVerb[i] === fVerb[j] ? 1 : 0)
+                + 0.25 * jaccard(fIo[i], fIo[j])
+                + 0.15 * jaccard(fReq[i], fReq[j]))),
+    };
+    // ND-02: 0.50*field_jaccard + 0.30*descr_jaccard + 0.20*usage_overlap
+    const schemas = graph.elements.filter(e => e.type === 'SCHEMA').sort(byId);
+    const sFields = schemas.map(schemaFields);
+    const sDescr = schemas.map(s => tokens(s.description));
+    const sUse = schemas.map(s => partners(graph, s.id, ['relation', 'io', 'compose']));
+    const schema = {
+        ids: schemas.map(s => s.id),
+        matrix: schemas.map((_, i) => schemas.map((_, j) => i === j ? 1
+            : 0.5 * jaccard(sFields[i], sFields[j])
+                + 0.3 * jaccard(sDescr[i], sDescr[j])
+                + 0.2 * jaccard(sUse[i], sUse[j]))),
+    };
+    return { func, schema };
+}
+function similarities(graph) {
+    let s = CACHE.get(graph);
+    if (s === undefined) {
+        s = build(graph);
+        CACHE.set(graph, s);
+    }
+    return s;
+}
+/** FUNC-Aehnlichkeit je Graph (ND-01). */
+export const funcSimilarity = (graph) => similarities(graph).func;
+/** SCHEMA-Aehnlichkeit je Graph (ND-02, AO-D01). */
+export const schemaSimilarity = (graph) => similarities(graph).schema;
+/** Paare ueber der Schwelle, kanonisch geordnet (i < j) — die eine Schleife fuer alle drei Regeln. */
+export function pairsAbove(sim, threshold) {
+    const out = [];
+    for (let i = 0; i < sim.ids.length; i++) {
+        for (let j = i + 1; j < sim.ids.length; j++) {
+            const s = sim.matrix[i][j];
+            if (s >= threshold)
+                out.push({ a: sim.ids[i], b: sim.ids[j], similarity: s });
+        }
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "9.1.0",
+  "version": "10.1.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,7 +29,9 @@
     "check:grammar": "node scripts/check-grammar-version.mjs",
     "grammar:snapshot": "SE_WRITE_GRAMMAR_SNAPSHOT=1 vitest run tests/unit/se-grammar-invariant.test.ts",
     "prepublishOnly": "npm run build && npm run test",
-    "grammar:measure": "SE_MEASURE=1 vitest run tests/unit/se-grammar-measure.test.ts"
+    "grammar:measure": "SE_MEASURE=1 vitest run tests/unit/se-grammar-measure.test.ts",
+    "report:silence": "node scripts/rules-silence-report.mjs",
+    "report:bestand": "node scripts/bestand-report.mjs"
   },
   "dependencies": {
     "zod": "^4.3.6"