@untangle-code/complexity 0.0.0-stage → 0.1.1

package/dist/cognitive.js

@@ -0,0 +1,62 @@
+function contributionKind(node) {
+    if (node.decision)
+        return node.decision.kind;
+    if (node.kind === "recursion_marker")
+        return "recursion";
+    return node.kind;
+}
+function isContributing(node) {
+    return (node.decision != null || node.kind === "logical_sequence" || node.kind === "recursion_marker");
+}
+function walk(node, state, contributions, seenGroups) {
+    if (isContributing(node)) {
+        const groupId = node.decision?.logicalGroupId;
+        const isDuplicateGroupMember = groupId != null && seenGroups.has(groupId);
+        if (groupId != null) {
+            seenGroups.add(groupId);
+        }
+        if (!isDuplicateGroupMember) {
+            const base = 1;
+            const nestingPenalty = node.kind === "recursion_marker" ? 0 : state.depth;
+            contributions.push({
+                line: node.range.startLine,
+                kind: contributionKind(node),
+                base,
+                nestingPenalty,
+                total: base + nestingPenalty,
+            });
+        }
+    }
+    const childDepth = node.nestingBoundary === true ? state.depth + 1 : state.depth;
+    for (const child of node.children) {
+        walk(child, { depth: childDepth }, contributions, seenGroups);
+    }
+}
+/**
+ * @param symbolRoot The `ComplexityIRNode` (kind `"symbol"`) rooting the
+ *   symbol's own subtree; traversal starts at depth 0.
+ * @param algorithm Caller-supplied algorithm id — pass domain's
+ *   `COGNITIVE_ALGORITHM_ID` in production; kept as a plain parameter (not
+ *   hardcoded) so this stays a pure function of its inputs.
+ */
+export function computeCognitive(symbolRoot, algorithm) {
+    const contributions = [];
+    walk(symbolRoot, { depth: 0 }, contributions, new Set());
+    const value = contributions.reduce((sum, c) => sum + c.total, 0);
+    assertCognitiveInvariant(contributions, value);
+    return { value, algorithm, contributions };
+}
+/**
+ * Throws when `sum(contributions[].total) !== total`. `computeCognitive`
+ * cannot actually violate this (value is defined as that very sum), but the
+ * work order asks for an explicit, independently-testable guard — this is
+ * also the function a caller re-assembling a snapshot from stored
+ * contributions should re-run to catch data corruption.
+ */
+export function assertCognitiveInvariant(contributions, total) {
+    const sum = contributions.reduce((s, c) => s + c.total, 0);
+    if (sum !== total) {
+        throw new Error(`cognitive complexity invariant violated: sum(contributions.total)=${sum} does not equal total=${total}`);
+    }
+}
+//# sourceMappingURL=cognitive.js.map

package/dist/cognitive.js.map

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

package/dist/cyclomatic.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CyclomaticCalculator (spec.md §16.2 "Classic", §16.3 "Extended").
+ *
+ * Classic: `M = 1 + decision_points`, one point per `DecisionFact` whose
+ * `countsForClassic` flag is set — the language adapter, not this
+ * calculator, decides which decision kinds are classic decision points
+ * (spec.md §16.2 lists if/else-if/loops/catch/ternary/case/guards).
+ *
+ * Extended: `M = 1 + decision_points`, one point per *independent* decision
+ * group whose `countsForExtended` flag is set. "Independent group" is where
+ * this calculator's own logic lives: `DecisionFact.logicalGroupId` marks
+ * facts that belong to the same short-circuit/pattern-alternative group
+ * (spec.md §16.3); this calculator counts each group once (first occurrence
+ * by source position wins), not once per operator/alternative.
+ */
+import type { ComplexityFacts } from "@untangle-code/domain";
+import type { CyclomaticResult } from "./types.js";
+/**
+ * @param facts Facts already narrowed to the target scope (see `selectSymbolFacts`
+ *   for `scope: "symbol"`; pass a file's unfiltered facts for `scope: "file"`).
+ * @param baseLine Source line the synthetic "base" contribution (the `+1` in
+ *   `M = 1 + decision_points`) is attributed to — typically the scope's own
+ *   first line.
+ * @param algorithmVersion Caller-supplied algorithm/metrics version stamp
+ *   (e.g. domain's `METRICS_VERSION`); this calculator is a pure function of
+ *   its inputs and never invents its own version string.
+ */
+export declare function computeCyclomatic(facts: ComplexityFacts, baseLine: number, algorithmVersion: string): CyclomaticResult;
+//# sourceMappingURL=cyclomatic.d.ts.map

package/dist/cyclomatic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclomatic.d.ts","sourceRoot":"","sources":["../src/cyclomatic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,uBAAuB,CAAC;AAE3E,OAAO,KAAK,EAA0B,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAM3E;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,GACvB,gBAAgB,CAwClB"}

package/dist/cyclomatic.js

@@ -0,0 +1,52 @@
+function sortByPosition(decisions) {
+    return [...decisions].sort((a, b) => a.range.startByte - b.range.startByte);
+}
+/**
+ * @param facts Facts already narrowed to the target scope (see `selectSymbolFacts`
+ *   for `scope: "symbol"`; pass a file's unfiltered facts for `scope: "file"`).
+ * @param baseLine Source line the synthetic "base" contribution (the `+1` in
+ *   `M = 1 + decision_points`) is attributed to — typically the scope's own
+ *   first line.
+ * @param algorithmVersion Caller-supplied algorithm/metrics version stamp
+ *   (e.g. domain's `METRICS_VERSION`); this calculator is a pure function of
+ *   its inputs and never invents its own version string.
+ */
+export function computeCyclomatic(facts, baseLine, algorithmVersion) {
+    const contributions = [
+        {
+            line: baseLine,
+            kind: "base",
+            value: 1,
+            countsForClassic: true,
+            countsForExtended: true,
+            note: "M = 1 + decision points (spec.md §16.2)",
+        },
+    ];
+    const seenGroups = new Set();
+    for (const decision of sortByPosition(facts.decisions)) {
+        if (!decision.countsForClassic && !decision.countsForExtended) {
+            continue;
+        }
+        if (decision.logicalGroupId != null) {
+            if (seenGroups.has(decision.logicalGroupId)) {
+                continue;
+            }
+            seenGroups.add(decision.logicalGroupId);
+        }
+        contributions.push({
+            line: decision.range.startLine,
+            kind: decision.kind,
+            value: 1,
+            countsForClassic: decision.countsForClassic,
+            countsForExtended: decision.countsForExtended,
+        });
+    }
+    const classic = contributions
+        .filter((c) => c.countsForClassic)
+        .reduce((sum, c) => sum + c.value, 0);
+    const extended = contributions
+        .filter((c) => c.countsForExtended)
+        .reduce((sum, c) => sum + c.value, 0);
+    return { classic, extended, contributions, algorithmVersion };
+}
+//# sourceMappingURL=cyclomatic.js.map

package/dist/cyclomatic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclomatic.js","sourceRoot":"","sources":["../src/cyclomatic.ts"],"names":[],"mappings":"AAmBA,SAAS,cAAc,CAAC,SAAkC;IACxD,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAsB,EACtB,QAAgB,EAChB,gBAAwB;IAExB,MAAM,aAAa,GAA6B;QAC9C;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,MAAM;YACZ,KAAK,EAAE,CAAC;YACR,gBAAgB,EAAE,IAAI;YACtB,iBAAiB,EAAE,IAAI;YACvB,IAAI,EAAE,yCAAyC;SAChD;KACF,CAAC;IAEF,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,QAAQ,IAAI,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QACvD,IAAI,CAAC,QAAQ,CAAC,gBAAgB,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YAC9D,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;YACpC,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;gBAC5C,SAAS;YACX,CAAC;YACD,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAC1C,CAAC;QACD,aAAa,CAAC,IAAI,CAAC;YACjB,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS;YAC9B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,KAAK,EAAE,CAAC;YACR,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;YAC3C,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;SAC9C,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,aAAa;SAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC;SACjC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACxC,MAAM,QAAQ,GAAG,aAAa;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC;SAClC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAExC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AAChE,CAAC"}

package/dist/entropy.d.ts

@@ -0,0 +1,5 @@
+/** Shannon entropy in bits over a frequency distribution (spec.md §16.6, §16.8). */
+export declare function shannonEntropy(frequencies: Iterable<number>): number;
+/** Builds a frequency map by counting occurrences of `key(item)` over `items`. */
+export declare function frequenciesOf<T>(items: readonly T[], key: (item: T) => string): Map<string, number>;
+//# sourceMappingURL=entropy.d.ts.map

package/dist/entropy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entropy.d.ts","sourceRoot":"","sources":["../src/entropy.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,CAepE;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GACvB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAOrB"}

package/dist/entropy.js

@@ -0,0 +1,29 @@
+/** Shannon entropy in bits over a frequency distribution (spec.md §16.6, §16.8). */
+export function shannonEntropy(frequencies) {
+    let total = 0;
+    const values = [];
+    for (const f of frequencies) {
+        if (f <= 0)
+            continue;
+        values.push(f);
+        total += f;
+    }
+    if (total === 0)
+        return 0;
+    let entropy = 0;
+    for (const f of values) {
+        const p = f / total;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** Builds a frequency map by counting occurrences of `key(item)` over `items`. */
+export function frequenciesOf(items, key) {
+    const counts = new Map();
+    for (const item of items) {
+        const k = key(item);
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    return counts;
+}
+//# sourceMappingURL=entropy.js.map

package/dist/entropy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entropy.js","sourceRoot":"","sources":["../src/entropy.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,WAA6B;IAC1D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC;YAAE,SAAS;QACrB,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACf,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,OAAO,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAC3B,KAAmB,EACnB,GAAwB;IAExB,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/explain.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Explain path (work order: "einen Explain-Pfad"). Produces a ranked,
+ * human-readable breakdown of a symbol's cyclomatic and cognitive
+ * contributions, largest first.
+ *
+ * Operates on the *stored* `ComplexitySnapshotV1` shape
+ * (`cyclomatic.contributors` is `MetricContribution[]`;
+ * `cognitive.contributors` is the full `CognitiveContributionV1[]` the
+ * snapshot persists per spec.md §16.4), so it works directly on whatever
+ * `assembleComplexitySnapshot` produced or on any snapshot loaded back from
+ * storage.
+ */
+import type { ComplexitySnapshotV1 } from "@untangle-code/domain";
+import type { ExplainEntry } from "./types.js";
+/**
+ * @param snapshot The symbol's complexity snapshot.
+ * @param top Maximum number of entries to return (default 5), largest
+ *   contribution first; ties keep cyclomatic before cognitive, then source
+ *   order.
+ */
+export declare function explainSymbol(snapshot: ComplexitySnapshotV1, top?: number): ExplainEntry[];
+//# sourceMappingURL=explain.d.ts.map

package/dist/explain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAEV,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAgC/C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,SAAI,GAAG,YAAY,EAAE,CAOrF"}

package/dist/explain.js

@@ -0,0 +1,35 @@
+function toCyclomaticEntries(contributions) {
+    return contributions
+        .filter((c) => c.kind !== "base")
+        .map((c) => ({
+        metric: "cyclomatic",
+        kind: c.kind,
+        line: c.line,
+        value: c.value,
+        text: `line ${c.line}: ${c.kind} contributes ${c.value} to cyclomatic complexity${c.note ? ` (${c.note})` : ""}`,
+    }));
+}
+function toCognitiveEntries(contributions) {
+    return contributions.map((c) => ({
+        metric: "cognitive",
+        kind: c.kind,
+        line: c.line,
+        value: c.total,
+        text: `line ${c.line}: ${c.kind} contributes ${c.total} to cognitive complexity (base=${c.base} nestingPenalty=${c.nestingPenalty})${c.note ? ` (${c.note})` : ""}`,
+    }));
+}
+/**
+ * @param snapshot The symbol's complexity snapshot.
+ * @param top Maximum number of entries to return (default 5), largest
+ *   contribution first; ties keep cyclomatic before cognitive, then source
+ *   order.
+ */
+export function explainSymbol(snapshot, top = 5) {
+    const combined = [
+        ...toCyclomaticEntries(snapshot.cyclomatic.contributors),
+        ...toCognitiveEntries(snapshot.cognitive.contributors),
+    ];
+    combined.sort((a, b) => b.value - a.value);
+    return combined.slice(0, top).map((entry, index) => ({ ...entry, rank: index + 1 }));
+}
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../src/explain.ts"],"names":[],"mappings":"AAoBA,SAAS,mBAAmB,CAC1B,aAA4C;IAE5C,OAAO,aAAa;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,MAAM,EAAE,YAAqB;QAC7B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,KAAK,4BACpD,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAC5B,EAAE;KACH,CAAC,CAAC,CAAC;AACR,CAAC;AAED,SAAS,kBAAkB,CACzB,aAAiD;IAEjD,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/B,MAAM,EAAE,WAAoB;QAC5B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,KAAK,kCAAkC,CAAC,CAAC,IAAI,mBAAmB,CAAC,CAAC,cAAc,IAC/H,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAC5B,EAAE;KACH,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,QAA8B,EAAE,GAAG,GAAG,CAAC;IACnE,MAAM,QAAQ,GAAG;QACf,GAAG,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC;QACxD,GAAG,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC;KACvD,CAAC;IACF,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACvF,CAAC"}

package/dist/halstead.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HalsteadCalculator (spec.md §16.7). Formulas exactly as specified,
+ * including the `max(n, 1)` / `max(n2, 1)` guards against log(0)/div-by-0 on
+ * an empty scope.
+ *
+ * Accepts the domain `HalsteadTokens` shape ({operators, operands}); a full
+ * `ComplexityFacts` is also accepted as-is since it structurally satisfies
+ * that shape.
+ */
+import type { HalsteadTokens } from "@untangle-code/domain";
+import type { HalsteadResult } from "./types.js";
+export interface HalsteadOptions {
+    /**
+     * Also compute Time (`effort / 18`, Halstead's Stroud-number heuristic) and
+     * Estimated Bugs (`volume / 3000`) — spec.md §16.7 requires both to be
+     * explicitly labeled as estimates when present, hence the separate
+     * `estimates` field on `HalsteadResult` rather than folding them into
+     * `metrics`.
+     */
+    includeEstimates?: boolean;
+}
+export declare function computeHalstead(tokens: HalsteadTokens, options?: HalsteadOptions, algorithmVersion?: string): HalsteadResult;
+//# sourceMappingURL=halstead.d.ts.map

package/dist/halstead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"halstead.d.ts","sourceRoot":"","sources":["../src/halstead.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAMjD,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,eAAoB,EAC7B,gBAAgB,SAAyB,GACxC,cAAc,CAqBhB"}

package/dist/halstead.js

@@ -0,0 +1,24 @@
+function log2(x) {
+    return Math.log(x) / Math.LN2;
+}
+export function computeHalstead(tokens, options = {}, algorithmVersion = "untangle-halstead-v1") {
+    const N1 = tokens.operators.length;
+    const N2 = tokens.operands.length;
+    const n1 = new Set(tokens.operators.map((t) => t.text)).size;
+    const n2 = new Set(tokens.operands.map((t) => t.text)).size;
+    const n = n1 + n2;
+    const N = N1 + N2;
+    const volume = N * log2(Math.max(n, 1));
+    const difficulty = (n1 / 2) * (N2 / Math.max(n2, 1));
+    const effort = difficulty * volume;
+    const metrics = { n1, n2, N1, N2, n, N, volume, difficulty, effort };
+    const result = { metrics, algorithmVersion };
+    if (options.includeEstimates) {
+        result.estimates = {
+            timeSeconds: effort / 18,
+            estimatedBugs: volume / 3000,
+        };
+    }
+    return result;
+}
+//# sourceMappingURL=halstead.js.map

package/dist/halstead.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"halstead.js","sourceRoot":"","sources":["../src/halstead.ts"],"names":[],"mappings":"AAaA,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AAChC,CAAC;AAaD,MAAM,UAAU,eAAe,CAC7B,MAAsB,EACtB,UAA2B,EAAE,EAC7B,gBAAgB,GAAG,sBAAsB;IAEzC,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,MAAM,EAAE,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5D,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAClB,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAClB,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAEnC,MAAM,OAAO,GAA2B,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAE7F,MAAM,MAAM,GAAmB,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC7D,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC7B,MAAM,CAAC,SAAS,GAAG;YACjB,WAAW,EAAE,MAAM,GAAG,EAAE;YACxB,aAAa,EAAE,MAAM,GAAG,IAAI;SAC7B,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @untangle-code/complexity — the complexity engine (spec.md §16,
+ * architecture.md §6.7, §15). Pure, deterministic calculators over
+ * `ComplexityFacts`/`ComplexityIRNode` from `@untangle-code/domain`; no I/O,
+ * no parser-registry, no embeddings. This module is the ONLY public export
+ * of the package.
+ */
+export { containsRange, rangeKey, selectSymbolFacts, sliceByRange, splitLines, strictlyContainsRange, } from "./scope.js";
+export { classifyLines, scopeLines } from "./text-lines.js";
+export { shannonEntropy, frequenciesOf } from "./entropy.js";
+export { classifyNodeKind, isAsyncNodeKind, isExceptionNodeKind } from "./node-kind-heuristics.js";
+export type { NodeKindClass } from "./node-kind-heuristics.js";
+export { buildSymbolIR } from "./ir/build-ir.js";
+export type { BuildSymbolIROptions } from "./ir/build-ir.js";
+export { computeCyclomatic } from "./cyclomatic.js";
+export { computeCognitive, assertCognitiveInvariant } from "./cognitive.js";
+export { computeStructural } from "./structural.js";
+export { computeTextual } from "./textual.js";
+export { computeSyntactic } from "./syntactic.js";
+export { computeHalstead } from "./halstead.js";
+export type { HalsteadOptions } from "./halstead.js";
+export { computeMaintainability, MAINTAINABILITY_FORMULA } from "./maintainability.js";
+export type { MaintainabilityInput } from "./maintainability.js";
+export { aggregate } from "./aggregator.js";
+export { aggregateScopeTree, assertScopeTreeInvariants, checkAllScopeCoverage, checkScopeCoverage, checkScopeTreeInvariants, checkSelectionCoverage, selectionForReading, selectScopeEntries, SCOPE_INVARIANT_CODES, SCOPE_SUM_READINGS, } from "./scope-aggregate.js";
+export type { ScopeInvariantCode, ScopeInvariantViolationV1, ScopeMetricNodeV1, ScopeSelectionKind, ScopeSelectionV1, ScopeSumReading, ScopeTreeAggregateV1, ScopeTreeOptions, } from "./scope-aggregate.js";
+export { withUniqueScopeIds } from "./scope-identity.js";
+export type { ScopeIdCollisionV1, UniqueScopeIdsResultV1 } from "./scope-identity.js";
+export { computeProseMetrics, compareProseByStructureLoad } from "./prose/metrics.js";
+export type { ProseLinkResolver, ProseMetricsOptions } from "./prose/metrics.js";
+export { explainSymbol } from "./explain.js";
+export { assembleComplexitySnapshot } from "./assemble.js";
+export type { SnapshotContext, SnapshotParts } from "./assemble.js";
+export type { AggregationEntry, AggregationResult, CognitiveResult, CyclomaticContribution, CyclomaticResult, ExplainEntry, HalsteadResult, MaintainabilityResult, MetricsResult, StructuralExternalInput, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EACL,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACnG,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACvF,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,kBAAkB,EAClB,yBAAyB,EACzB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAItF,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AACtF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGpE,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,uBAAuB,GACxB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @untangle-code/complexity — the complexity engine (spec.md §16,
+ * architecture.md §6.7, §15). Pure, deterministic calculators over
+ * `ComplexityFacts`/`ComplexityIRNode` from `@untangle-code/domain`; no I/O,
+ * no parser-registry, no embeddings. This module is the ONLY public export
+ * of the package.
+ */
+// Scoping/text utilities shared across calculators.
+export { containsRange, rangeKey, selectSymbolFacts, sliceByRange, splitLines, strictlyContainsRange, } from "./scope.js";
+export { classifyLines, scopeLines } from "./text-lines.js";
+export { shannonEntropy, frequenciesOf } from "./entropy.js";
+export { classifyNodeKind, isAsyncNodeKind, isExceptionNodeKind } from "./node-kind-heuristics.js";
+// IR producer: ComplexityFacts -> ComplexityIRNode bridge (architecture.md §6.7).
+export { buildSymbolIR } from "./ir/build-ir.js";
+// Calculators (architecture.md §15.2).
+export { computeCyclomatic } from "./cyclomatic.js";
+export { computeCognitive, assertCognitiveInvariant } from "./cognitive.js";
+export { computeStructural } from "./structural.js";
+export { computeTextual } from "./textual.js";
+export { computeSyntactic } from "./syntactic.js";
+export { computeHalstead } from "./halstead.js";
+export { computeMaintainability, MAINTAINABILITY_FORMULA } from "./maintainability.js";
+export { aggregate } from "./aggregator.js";
+// Aggregation ueber den Scope-Baum, ohne Doppelzaehlung (WP-82).
+export { aggregateScopeTree, assertScopeTreeInvariants, checkAllScopeCoverage, checkScopeCoverage, checkScopeTreeInvariants, checkSelectionCoverage, selectionForReading, selectScopeEntries, SCOPE_INVARIANT_CODES, SCOPE_SUM_READINGS, } from "./scope-aggregate.js";
+// Eindeutige Scope-Ids als Voraussetzung der Dedupe ueber metricsScopeId (WP-82).
+export { withUniqueScopeIds } from "./scope-identity.js";
+// Prosa-Metriken als EIGENE Familie (vision.md §1c, WP-217). Ihre Werte sind
+// `ProseNumberV1`-Objekte und koennen deshalb strukturell nie in eine
+// Code-Metrik-Summe geraten.
+export { computeProseMetrics, compareProseByStructureLoad } from "./prose/metrics.js";
+export { explainSymbol } from "./explain.js";
+export { assembleComplexitySnapshot } from "./assemble.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oDAAoD;AACpD,OAAO,EACL,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGnG,kFAAkF;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,uCAAuC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,iEAAiE;AACjE,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAW9B,kFAAkF;AAClF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,6EAA6E;AAC7E,sEAAsE;AACtE,6BAA6B;AAC7B,OAAO,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,oBAAoB,CAAC;AAEtF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC"}

package/dist/ir/build-ir.d.ts

@@ -0,0 +1,105 @@
+/**
+ * IR producer: the bridge `ComplexityFacts` -> `ComplexityIRNode`
+ * (architecture.md §6.7, spec.md §16.4).
+ *
+ * architecture.md §6.7 says "Sprachadapter uebersetzen AST-Nodes in diese
+ * IR", but the `LanguageAdapter` port (domain `analysis.ts`) deliberately
+ * has no IR method — adapters emit flat, language-neutral `ComplexityFacts`.
+ * This module closes that gap INSIDE the complexity package: it rebuilds the
+ * `ComplexityIRNode` tree `computeCognitive` (and the branching metrics of
+ * `computeSyntactic`) require from the byte-ranges the facts already carry,
+ * so no language adapter needs to know the IR shape at all.
+ *
+ * INPUT CONTRACT (facts, as produced by parser-registry's single walk):
+ * - every `DecisionFact`/`NestingFact` range is the source range of the AST
+ *   node that caused it; ranges of distinct facts never partially overlap
+ *   (they are AST node ranges: equal, disjoint, or fully nested);
+ * - an `if`/`loop`/`catch`/`ternary` emits BOTH a `DecisionFact` and a
+ *   `NestingFact` with the identical range (they are merged into one IR
+ *   node here);
+ * - an `else if` is a `DecisionFact` of kind `"else_if"` plus a
+ *   `NestingFact` with `continuation: true`, and its range lies INSIDE the
+ *   range of the `if` it continues (the raw AST "alternate" shape).
+ *
+ * OUTPUT CONTRACT (what `computeCognitive` requires — see cognitive.ts):
+ * - an `if` / `else if` / `else if` chain becomes a FLAT run of sibling IR
+ *   nodes under the parent of the first `if`, NEVER the raw AST's nested
+ *   alternate shape. This is what makes "`else if` erhaelt keinen
+ *   vollstaendigen neuen Nesting-Aufschlag" (spec.md §16.4) fall out of the
+ *   traversal: siblings share the ambient depth. Implemented via the
+ *   attachment rule `finalParent(continuationNode) =
+ *   finalParent(itsContainmentParent)`, which flattens arbitrarily long
+ *   chains while keeping a genuinely nested `if` (inside another `if`'s
+ *   BODY) at its deeper level;
+ * - each branch keeps its own consequent content as `children` (content
+ *   ranges nest inside the branch's own range, so containment placement
+ *   already produces that).
+ *
+ * Documented mapping decisions (Untangle decisions, mirrored in the README):
+ * - nesting constructs map to IR kinds: if->"decision", loop->"loop",
+ *   catch->"catch", ternary->"ternary", switch->"switch", lambda->"lambda";
+ *   all of them are nesting boundaries (`nestingBoundary: true`), matching
+ *   the boundary list documented in cognitive.ts;
+ * - a `case` decision (no nesting fact of its own) becomes a `"case"` node
+ *   that is ALSO a nesting boundary — case bodies are one level deeper than
+ *   the switch head, per cognitive.ts's documented boundary list;
+ * - logical-operator decisions (`logical_and`/`logical_or`/`short_circuit`)
+ *   become non-boundary `"logical_sequence"` nodes carrying their
+ *   `DecisionFact` (grouping happens in the consumers via `logicalGroupId`);
+ * - CONDITION HOISTING: a logical node whose direct IR parent is a
+ *   condition-bearing boundary (`decision`/`loop`/`ternary`/`switch`) is
+ *   hoisted to a sibling placed immediately BEFORE that boundary node. This
+ *   encodes the untangle-cognitive-v1 convention that a guard's condition
+ *   operators score at the guard's own ambient depth (see the golden case in
+ *   cognitive.test.ts), and is exact for `switch` (everything nested in a
+ *   switch body sits inside a `case` node). For `if`/loops/ternaries it is a
+ *   documented approximation: facts carry no condition/body split, so a
+ *   logical group written as a DIRECT body statement of the guard (e.g.
+ *   `if (x) y = a && b;`) is hoisted too and scores one nesting level lower
+ *   than a hypothetical exact split would give. Making this exact needs a
+ *   `conditionRange` on `DecisionFact` (or a `bodyRange` on `NestingFact`)
+ *   from the adapters — tracked as an open issue, not guessed here;
+ * - every descendant symbol scope of the target symbol is included: its
+ *   facts participate in the target's IR, and the scope itself becomes a
+ *   `"lambda"` boundary node when it is function-like (function / method /
+ *   constructor — deduplicated by range against the adapter's own `lambda`
+ *   nesting events) or a transparent non-boundary `"block"` node otherwise
+ *   (class/interface/enum/namespace/type/property). This is the "documented
+ *   nesting context" spec.md §16.4 demands for local functions/lambdas: a
+ *   symbol's cognitive value includes the control flow of the lambdas it
+ *   defines, one nesting level deeper — while those lambdas still get their
+ *   own, separately-scoped snapshot when measured directly;
+ * - recursion (spec.md §16.4 "Rekursion wird markiert und KANN einen
+ *   Beitrag erzeugen"): when the caller supplies the file's `RawCall`s
+ *   (adapters expose them via `extractCalls`, but they are not part of
+ *   `ComplexityFacts`), a call site inside the subtree whose unqualified
+ *   callee name (or `this.`-qualified name, for methods) equals the name of
+ *   its OWN enclosing scope becomes a `"recursion_marker"` node — direct
+ *   self-recursion only; mutual recursion needs the call graph and is out of
+ *   scope here.
+ */
+import type { ComplexityFacts, ComplexityIRNode, RawCall } from "@untangle-code/domain";
+export interface BuildSymbolIROptions {
+    /**
+     * Raw call sites of the same file (from `LanguageAdapter.extractCalls`).
+     * When given, direct self-recursion is marked with `"recursion_marker"`
+     * nodes; when omitted, no recursion contributions are produced (allowed:
+     * spec.md §16.4 makes the recursion contribution optional).
+     */
+    calls?: readonly RawCall[];
+}
+/**
+ * Builds the `ComplexityIRNode` subtree for one symbol scope (kind
+ * `"symbol"`, `nestingBoundary` unset, traversal depth 0 — exactly the root
+ * shape `computeCognitive` expects), or the whole-file tree (kind `"root"`)
+ * when `symbolScopeId` is the file scope's id.
+ *
+ * Returns `undefined` when `symbolScopeId` does not exist in
+ * `facts.symbolScopes` (mirrors `selectSymbolFacts`' stale-id tolerance).
+ *
+ * Pass the UNFILTERED file facts, not `selectSymbolFacts` output: the
+ * builder selects the symbol's own facts AND its descendant scopes' facts
+ * itself (a symbol's lambdas nest into its IR — see the module doc).
+ */
+export declare function buildSymbolIR(facts: ComplexityFacts, symbolScopeId: string, options?: BuildSymbolIROptions): ComplexityIRNode | undefined;
+//# sourceMappingURL=build-ir.d.ts.map

package/dist/ir/build-ir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-ir.d.ts","sourceRoot":"","sources":["../../src/ir/build-ir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,OAAO,KAAK,EACV,eAAe,EACf,gBAAgB,EAGhB,OAAO,EAER,MAAM,uBAAuB,CAAC;AAI/B,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC5B;AAmGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,oBAAyB,GACjC,gBAAgB,GAAG,SAAS,CAiK9B"}