@untangle-code/complexity 0.0.0-stage → 0.1.0

package/dist/scope-aggregate.d.ts

@@ -0,0 +1,229 @@
+import type { AggregationEntry } from "./types.js";
+/**
+ * Ein Scope mit beiden Lesarten desselben Metrikwerts.
+ *
+ * Der Aufrufer erzeugt die Werte mit demselben Calculator, nur mit
+ * unterschiedlich zugeschnittenen Facts:
+ * - `inclusiveValue`: Calculator auf `buildSymbolIR(facts, id)` — die
+ *   ungefilterten Datei-Facts, der Builder zieht alle Nachfahren-Scopes mit
+ *   hinein.
+ * - `selfValue`: Calculator auf
+ *   `buildSymbolIR(selectSymbolFacts(facts, id), id)` — nur die eigenen
+ *   Facts des Scopes, ohne Nachfahren.
+ */
+export interface ScopeMetricNodeV1 {
+    /** `metrics_scope_id` nach spec.md §16.10; hier die `symbolScopeId`. */
+    metricsScopeId: string;
+    /** Eltern-Scope; fehlt genau bei einem Wurzel-Scope (typisch: der Datei-Scope). */
+    parentScopeId?: string;
+    /** Wert EINSCHLIESSLICH aller Nachfahren-Scopes. */
+    inclusiveValue: number;
+    /** Wert allein aus den eigenen Facts des Scopes, OHNE Nachfahren. */
+    selfValue: number;
+    /**
+     * True, wenn der Scope eine eigene Ausfuehrungseinheit ist (Funktion,
+     * Methode, Konstruktor, Lambda) — false bei Datei, Klasse, Interface,
+     * Namespace, Typ, Property-Gruppe. Steuert ausschliesslich die Lesart
+     * `"execution_unit"`; die Zuordnung trifft der Aufrufer, weil
+     * `SymbolScopeFact.kind` ein adapterspezifischer String ist und dieses
+     * Paket keine Sprach-Taxonomie kennt.
+     */
+    executionUnit: boolean;
+    /** SLOC des Scopes, fuer den SLOC-gewichteten Mittelwert in `aggregate()`. */
+    sloc?: number;
+}
+/** Die drei definierten Lesarten einer Scope-Summe. */
+export declare const SCOPE_SUM_READINGS: readonly ["top_level", "execution_unit", "self"];
+export type ScopeSumReading = (typeof SCOPE_SUM_READINGS)[number];
+/** Geschlossene Menge der Invariantenverstoesse. Ein Verstoss ist ein Fehler, kein Hinweis. */
+export declare const SCOPE_INVARIANT_CODES: readonly ["duplicate_scope_id", "unknown_parent", "parent_cycle", "negative_value", "self_exceeds_inclusive", "children_exceed_parent", "leaf_self_differs_from_inclusive", "scope_counted_twice", "scope_uncounted"];
+export type ScopeInvariantCode = (typeof SCOPE_INVARIANT_CODES)[number];
+/** Ein Invariantenverstoss mit Pflicht-Detailtext (E4). */
+export interface ScopeInvariantViolationV1 {
+    code: ScopeInvariantCode;
+    metricsScopeId: string;
+    /** Beobachteter Wert (Bedeutung je nach `code`). */
+    observed: number;
+    /** Obergrenze/Erwartungswert, gegen den `observed` geprueft wurde. */
+    limit: number;
+    /** Menschenlesbare Begruendung; nie leer. */
+    detail: string;
+}
+export interface ScopeTreeOptions {
+    /**
+     * Konstanter Sockel, den JEDER gemessene Scope traegt, unabhaengig von
+     * seinem Inhalt. Cognitive: `0` (Default). Cyclomatic classic/extended:
+     * `1`, weil `computeCyclomatic` immer den `M = 1 + decision_points`-Sockel
+     * anlegt — ohne diese Angabe meldet die Eltern/Kind-Pruefung fuer
+     * Cyclomatic Scheinverstoesse, sobald ein Scope mehr als ein Kind hat.
+     * Die Pruefung rechnet mit `wert - perScopeBase`; die ausgewiesenen Summen
+     * bleiben unveraendert.
+     */
+    perScopeBase?: number;
+    /** Toleranz fuer Fliesskomma-Vergleiche. Default 1e-9. */
+    epsilon?: number;
+}
+/** Ergebnis von `aggregateScopeTree`. */
+export interface ScopeTreeAggregateV1 {
+    /** Scopes nach Dedupe ueber `metricsScopeId`. */
+    scopeCount: number;
+    /** Wegen wiederholter `metricsScopeId` verworfene Eingaben (spec.md §16.10). */
+    duplicatesDropped: number;
+    rootCount: number;
+    /** Anzahl der aeussersten Ausfuehrungseinheiten (Basis der Funktions-Lesart). */
+    executionUnitRootCount: number;
+    leafCount: number;
+    /** Lesart `"top_level"`. */
+    topLevelSum: number;
+    /** Lesart `"execution_unit"` — die Vorgabezahl. */
+    executionUnitSum: number;
+    /** Lesart `"self"`. */
+    selfSum: number;
+    /**
+     * NUR DIAGNOSE: Summe der `inclusiveValue` ueber alle Scopes — die naiv
+     * doppelt zaehlende Zahl. Nie als Kennzahl ausgeben.
+     */
+    naiveSum: number;
+    /** `naiveSum - topLevelSum`: der Betrag, den eine naive Summe doppelt zaehlt. */
+    doubleCountedAmount: number;
+    /** NUR DIAGNOSE: Summe ueber die Blatt-Scopes (siehe Modul-Doku). */
+    leafOnlySum: number;
+    /** `selfSum - leafOnlySum`: der Betrag, den eine Blatt-Lesart verschlucken wuerde. */
+    leafOnlyDroppedAmount: number;
+}
+/**
+ * Prueft alle Invarianten des Scope-Baums und liefert JEDEN Verstoss mit
+ * Begruendung. Leere Liste heisst: der Baum traegt eine sinnvolle Summe.
+ *
+ * Geprueft wird:
+ * 1. `duplicate_scope_id` — dieselbe Id mit abweichenden Werten.
+ * 2. `unknown_parent` — `parentScopeId` zeigt auf einen Scope, der nicht in
+ *    der Menge ist. Ihn stillschweigend als Wurzel zu behandeln waere ein
+ *    E4-Verstoss: der Elternwert, gegen den geprueft werden muesste, fehlt.
+ * 3. `parent_cycle` — die Elternkette schliesst sich.
+ * 4. `negative_value` — negative Metrikwerte.
+ * 5. `self_exceeds_inclusive` — der Eigenanteil ist groesser als der Wert
+ *    mit Nachfahren. Der Eigenanteil ist per Definition ein Teil davon.
+ * 6. `children_exceed_parent` — der Eigenanteil eines Scopes plus die Summe
+ *    seiner direkten Kinder darf seinen eigenen Wert nicht ueberschreiten.
+ *
+ *    WAS DIESE PRUEFUNG LEISTET UND WAS NICHT — sie ist eine EINSEITIGE
+ *    Schranke (`self + Summe Kinder <= inclusive`) und darf deshalb nicht als
+ *    Doppelzaehlungspruefung gelesen werden:
+ *    - Sie schlaegt an, wenn der Elternwert ZU KLEIN ist, dem Elternwert
+ *      also Inhalt seiner Kinder FEHLT (oder ein Kindwert zu gross ist).
+ *      Ein Verstoss heisst: der Baum verliert Inhalt, nicht: er zaehlt
+ *      doppelt.
+ *    - Sie schlaegt NICHT an, wenn der Elternwert ZU GROSS ist — genau der
+ *      Fall, in dem ein Kindbeitrag zweimal im Elternwert steckt. Ein
+ *      aufgeblaehter `inclusiveValue` ist aus Werten allein nicht von einem
+ *      Scope zu unterscheiden, der im eigenen Koerper viel Kontrollfluss
+ *      traegt.
+ *
+ *    Die Zusicherung "jeder Beitrag zaehlt genau einmal" leistet
+ *    `checkScopeCoverage` auf der Struktur der jeweiligen Lesart, nicht
+ *    diese Wertschranke.
+ * 7. `leaf_self_differs_from_inclusive` — ein Scope ohne Kinder hat keine
+ *    Nachfahren, sein Eigenanteil MUSS also sein Gesamtwert sein. Weicht er
+ *    ab, hat der Aufrufer die beiden Werte nicht aus demselben Scope
+ *    berechnet.
+ *
+ * NICHT geprueft (und mit Absicht hier benannt statt verschwiegen): ein zu
+ * grosser `inclusiveValue` eines Scopes MIT Kindern. Siehe Punkt 6 und die
+ * Modul-Doku, Abschnitt "Woraus die Doppelzaehlungsfreiheit tatsaechlich
+ * folgt".
+ *
+ * Alle Wertvergleiche laufen auf `wert - perScopeBase` (siehe
+ * `ScopeTreeOptions.perScopeBase`).
+ */
+export declare function checkScopeTreeInvariants(nodes: readonly ScopeMetricNodeV1[], options?: ScopeTreeOptions): ScopeInvariantViolationV1[];
+/**
+ * Wirft bei jedem Invariantenverstoss. Die Meldung nennt Anzahl und die
+ * ersten Verstoesse im Klartext; `context.violations` traegt die volle Liste.
+ *
+ * Geprueft wird in ZWEI Stufen: erst die Wert- und Bauminvarianten
+ * (`checkScopeTreeInvariants`), danach — nur wenn der Baum ueberhaupt
+ * wohlgeformt ist — die strukturelle Zaehlpruefung ueber alle drei Lesarten
+ * (`checkAllScopeCoverage`). Erst beide zusammen tragen die Aussage, dass die
+ * ausgegebenen Summen jeden Scope genau einmal enthalten; die Wertschranke
+ * allein taete es nicht (siehe Punkt 6 oben).
+ */
+export declare function assertScopeTreeInvariants(nodes: readonly ScopeMetricNodeV1[], options?: ScopeTreeOptions): void;
+/**
+ * Liefert genau die Eintraege, die eine Lesart zaehlt — jeder Scope hoechstens
+ * einmal, jeweils mit dem fuer die Lesart richtigen Wert. Das Ergebnis geht
+ * unveraendert in `aggregate()`; damit gelten count/mean/median/p90/p95/max/
+ * Schwellenzaehlung (spec.md §16.10) auf einer doppelzaehlungsfreien Basis.
+ *
+ * Prueft KEINE Invarianten — dafuer ist `checkScopeTreeInvariants` da. Ein
+ * `unknown_parent` wird hier zwangslaeufig wie eine Wurzel behandelt; genau
+ * deshalb meldet die Pruefung ihn als Fehler, statt ihn zu tolerieren.
+ */
+export declare function selectScopeEntries(nodes: readonly ScopeMetricNodeV1[], reading: ScopeSumReading): AggregationEntry[];
+/**
+ * Mit welchem Wert ein ausgewaehlter Scope in seine Lesart eingeht — und
+ * damit auch, WIE WEIT sein Summand reicht: `"inclusive"` deckt den Scope
+ * und alle seine Nachfahren ab, `"self"` nur ihn selbst.
+ */
+export type ScopeSelectionKind = "inclusive" | "self";
+/**
+ * Welche Scopes eine Lesart als Summanden zaehlt und mit welcher Reichweite.
+ * Was nicht in der Abbildung steht, ist kein eigener Summand.
+ */
+export type ScopeSelectionV1 = ReadonlyMap<string, ScopeSelectionKind>;
+/**
+ * Die Auswahl einer Lesart. Einzige Quelle der Wahrheit fuer
+ * `selectScopeEntries` UND `checkScopeCoverage`: die Pruefung soll dieselbe
+ * Auswahl sehen, die auch summiert wird, sonst prueft sie etwas anderes als
+ * das, was ausgegeben wird.
+ */
+export declare function selectionForReading(nodes: readonly ScopeMetricNodeV1[], reading: ScopeSumReading): ScopeSelectionV1;
+/**
+ * Prueft STRUKTURELL, dass eine Lesart jeden Scope genau einmal zaehlt — die
+ * Zusicherung, die `children_exceed_parent` NICHT leisten kann (siehe die
+ * Modul-Doku, Abschnitt "Woraus die Doppelzaehlungsfreiheit tatsaechlich
+ * folgt", und Punkt 6 von `checkScopeTreeInvariants`).
+ *
+ * Fuer jeden Scope wird gezaehlt, wie viele Summanden der Lesart seinen
+ * Beitrag tragen: er selbst, falls er ausgewaehlt ist, plus jeder echte
+ * Vorfahre, der mit `inclusiveValue` ausgewaehlt ist (dessen Summand deckt
+ * den ganzen Teilbaum ab). Genau EINER muss es sein.
+ *
+ * Was die Pruefung NICHT leisten kann: sie sieht die Struktur, nicht die
+ * Werte. Ein `inclusiveValue`, der den Beitrag eines Kindes intern doppelt
+ * enthaelt, ist aus Zahlen allein nicht erkennbar — dafuer haftet der
+ * Aufrufer, der die Werte berechnet hat.
+ */
+export declare function checkScopeCoverage(nodes: readonly ScopeMetricNodeV1[], reading: ScopeSumReading): ScopeInvariantViolationV1[];
+/**
+ * Dieselbe Zaehlpruefung wie `checkScopeCoverage`, aber gegen eine BELIEBIGE
+ * Auswahl. Sie ist der eigentliche Kern; `checkScopeCoverage` ist nur die
+ * Anwendung auf die Auswahl, die eine der drei Lesarten trifft.
+ *
+ * Getrennt exportiert, weil die Zusicherung sonst nicht vorfuehrbar waere:
+ * die Auswahlen der drei Lesarten koennen `scope_counted_twice` per
+ * Konstruktion nicht ausloesen (dort ist ein Scope ausgewaehlt GENAU DANN,
+ * wenn er keinen ausgewaehlten `inclusive`-Vorfahren hat). Eine Pruefung,
+ * deren Alarmfall ueber die oeffentliche Schnittstelle nicht erreichbar ist,
+ * waere eine Behauptung statt einer Pruefung — mit dieser Funktion laesst er
+ * sich zeigen, und der Waechter greift, sobald jemand `selectionFor` aendert.
+ *
+ * @param label Erscheint im Detailtext an der Stelle der Lesart.
+ */
+export declare function checkSelectionCoverage(nodes: readonly ScopeMetricNodeV1[], selection: ScopeSelectionV1, label: string): ScopeInvariantViolationV1[];
+/**
+ * `checkScopeCoverage` fuer ALLE drei Lesarten, Verstoesse deterministisch
+ * nach Lesart und Scope sortiert.
+ */
+export declare function checkAllScopeCoverage(nodes: readonly ScopeMetricNodeV1[]): ScopeInvariantViolationV1[];
+/**
+ * Summiert einen Scope-Baum in allen drei Lesarten, ohne Doppelzaehlung.
+ *
+ * WIRFT bei jedem Invariantenverstoss (`UntangleError`, Code
+ * `ANALYSIS_INCOMPLETE`): eine Summe ueber einen widerspruechlichen Baum ist
+ * keine Zahl mit Bedeutung, und ein Hinweis waere hier zu wenig. Wer die
+ * Verstoesse anzeigen statt abbrechen will, ruft vorher
+ * `checkScopeTreeInvariants` auf.
+ */
+export declare function aggregateScopeTree(nodes: readonly ScopeMetricNodeV1[], options?: ScopeTreeOptions): ScopeTreeAggregateV1;
+//# sourceMappingURL=scope-aggregate.d.ts.map

package/dist/scope-aggregate.d.ts.map

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