@untangle-code/complexity 0.0.0-stage → 0.1.1

package/dist/syntactic.js

@@ -0,0 +1,143 @@
+import { frequenciesOf, shannonEntropy } from "./entropy.js";
+import { classifyNodeKind, isAsyncNodeKind, isExceptionNodeKind } from "./node-kind-heuristics.js";
+import { rangeKey } from "./scope.js";
+function mean(values) {
+    if (values.length === 0)
+        return 0;
+    return values.reduce((s, v) => s + v, 0) / values.length;
+}
+/**
+ * Exact per-node child counts from a DFS pre-order depth sequence (see the
+ * module doc): a stack of "open" ancestor indices is maintained; each new
+ * node closes every open node with depth >= its own, and the remaining top
+ * (nearest preceding smaller depth) is its parent. Works on scope-filtered
+ * sequences too — a scope's facts form contiguous pre-order fragments whose
+ * missing outer ancestors simply make their subtree roots forest roots, and
+ * child counts then cover exactly the scope's OWN nodes, consistent with
+ * every other metric computed from scope-narrowed facts.
+ */
+function computeBranchingFromPreorderDepths(nodeKinds) {
+    const childCounts = new Array(nodeKinds.length).fill(0);
+    const openAncestors = [];
+    for (let i = 0; i < nodeKinds.length; i += 1) {
+        const depth = nodeKinds[i].depth;
+        while (openAncestors.length > 0 &&
+            nodeKinds[openAncestors[openAncestors.length - 1]].depth >= depth) {
+            openAncestors.pop();
+        }
+        const parentIndex = openAncestors[openAncestors.length - 1];
+        if (parentIndex !== undefined) {
+            childCounts[parentIndex] = childCounts[parentIndex] + 1;
+        }
+        openAncestors.push(i);
+    }
+    let max = 0;
+    for (const count of childCounts) {
+        if (count > max)
+            max = count;
+    }
+    return { avg: mean(childCounts), max };
+}
+function computeBranching(root) {
+    const branchCounts = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (!node)
+            continue;
+        branchCounts.push(node.children.length);
+        for (const child of node.children)
+            stack.push(child);
+    }
+    return {
+        avg: mean(branchCounts),
+        max: branchCounts.length > 0 ? Math.max(...branchCounts) : 0,
+    };
+}
+/**
+ * @param facts Facts already narrowed to the target scope.
+ * @param sloc The scope's own SLOC, as computed by `computeStructural` —
+ *   passed in rather than recomputed so `ast_nodes_per_sloc` is consistent
+ *   with the structural snapshot instead of a second, possibly divergent,
+ *   line-scan.
+ * @param irRoot Optional IR subtree for the same scope; only used as the
+ *   branching-factor source when `facts.nodeKinds` is empty (the pre-order
+ *   reconstruction over real node-kind facts is exact and takes precedence).
+ */
+export function computeSyntactic(facts, sloc, irRoot, algorithmVersion = "untangle-syntactic-v1") {
+    const depths = facts.nodeKinds.map((n) => n.depth);
+    const astNodeCount = facts.nodeKinds.length;
+    const controlFlowKeys = new Set();
+    for (const d of facts.decisions)
+        controlFlowKeys.add(rangeKey(d.range));
+    for (const n of facts.nestingEvents)
+        controlFlowKeys.add(rangeKey(n.range));
+    const controlFlowNodeCount = controlFlowKeys.size;
+    // Ranged exception constructs (catch clauses) are deduplicated by range,
+    // since adapters may emit both a DecisionFact and a NestingFact for the
+    // same `catch`. Node-kind-only signals (e.g. a bare `throw_statement`,
+    // which carries no dedicated fact type) have no range to dedupe by and are
+    // simply counted in addition.
+    const exceptionRangeKeys = new Set();
+    for (const n of facts.nestingEvents) {
+        if (n.construct === "catch")
+            exceptionRangeKeys.add(rangeKey(n.range));
+    }
+    for (const d of facts.decisions) {
+        if (d.kind === "catch")
+            exceptionRangeKeys.add(rangeKey(d.range));
+    }
+    const throwLikeNodeCount = facts.nodeKinds.filter((n) => isExceptionNodeKind(n.kind) && !n.kind.toLowerCase().includes("catch")).length;
+    const exceptionConstructCount = exceptionRangeKeys.size + throwLikeNodeCount;
+    const nodeKindFrequencies = frequenciesOf(facts.nodeKinds, (n) => n.kind);
+    const metrics = {
+        ast_node_count: astNodeCount,
+        ast_max_depth: depths.length > 0 ? Math.max(...depths) : 0,
+        ast_avg_depth: mean(depths),
+        statement_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "statement").length,
+        expression_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "expression")
+            .length,
+        declaration_count: facts.nodeKinds.filter((n) => classifyNodeKind(n.kind) === "declaration")
+            .length,
+        control_flow_node_count: controlFlowNodeCount,
+        control_flow_density: astNodeCount > 0 ? controlFlowNodeCount / astNodeCount : 0,
+        lambda_count: facts.nestingEvents.filter((n) => n.construct === "lambda").length,
+        async_construct_count: facts.nodeKinds.filter((n) => isAsyncNodeKind(n.kind)).length,
+        exception_construct_count: exceptionConstructCount,
+        pattern_match_count: facts.decisions.filter((d) => d.kind === "pattern_alternative").length,
+        node_kind_entropy: shannonEntropy(nodeKindFrequencies.values()),
+        ast_nodes_per_sloc: astNodeCount / Math.max(sloc, 1),
+        parse_error_node_count: facts.parseDiagnostics.filter((d) => d.kind === "error_node").length,
+        missing_node_count: facts.parseDiagnostics.filter((d) => d.kind === "missing_node").length,
+        // WP-185: DIE ZWEI ZAHLEN OBEN SIND NICHT DIE GANZE WAHRHEIT.
+        //
+        // `ParseDiagnostic.kind` kennt vier Werte (`error_node`, `missing_node`,
+        // `fallback`, `other`). Die beiden Kennzahlen oben zaehlen genau zwei
+        // davon — und ein Adapter, dessen Parser keine tree-sitter-Fehlerknoten
+        // kennt, meldet seine Syntaxfehler als `"other"`. Gemessen am eigenen
+        // Python-Adapter: eine Datei mit `parseQuality: "partial"` und
+        // `ParseResult.errorNodeCount: 5` erzeugt fuenf Diagnosen der Art
+        // `"other"` — und `parse_error_node_count` stand trotzdem auf 0. Zwei
+        // Zeugen desselben Laufs widersprachen einander, und der, der das Haus
+        // verlaesst, war der falsche. Wer 0 liest, schliesst auf einen heilen
+        // Baum; das ist die Sorte stiller Fehlaussage, die E4 verbietet.
+        //
+        // Die beiden vorhandenen Kennzahlen bleiben unveraendert — sie bedeuten
+        // weiterhin genau, was ihr Name sagt. Ergaenzt werden zwei, die den Rest
+        // sichtbar machen, statt ihn unter einer 0 verschwinden zu lassen.
+        parse_diagnostic_count: facts.parseDiagnostics.length,
+        unclassified_parse_error_count: facts.parseDiagnostics.filter((d) => d.severity === "error" && d.kind !== "error_node" && d.kind !== "missing_node").length,
+    };
+    if (facts.nodeKinds.length > 0) {
+        const branching = computeBranchingFromPreorderDepths(facts.nodeKinds);
+        metrics["ast_branching_factor_avg"] = branching.avg;
+        metrics["ast_branching_factor_max"] = branching.max;
+    }
+    else if (irRoot) {
+        const branching = computeBranching(irRoot);
+        metrics["ast_branching_factor_avg"] = branching.avg;
+        metrics["ast_branching_factor_max"] = branching.max;
+    }
+    return { metrics, algorithmVersion };
+}
+//# sourceMappingURL=syntactic.js.map

package/dist/syntactic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntactic.js","sourceRoot":"","sources":["../src/syntactic.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACnG,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,SAAS,IAAI,CAAC,MAAyB;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;AAC3D,CAAC;AAOD;;;;;;;;;GASG;AACH,SAAS,kCAAkC,CAAC,SAAkC;IAC5E,MAAM,WAAW,GAAG,IAAI,KAAK,CAAS,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAI,SAAS,CAAC,CAAC,CAAkB,CAAC,KAAK,CAAC;QACnD,OACE,aAAa,CAAC,MAAM,GAAG,CAAC;YACvB,SAAS,CAAC,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAW,CAAkB,CAAC,KAAK,IAAI,KAAK,EAC7F,CAAC;YACD,aAAa,CAAC,GAAG,EAAE,CAAC;QACtB,CAAC;QACD,MAAM,WAAW,GAAG,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC5D,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,WAAW,CAAC,WAAW,CAAC,GAAI,WAAW,CAAC,WAAW,CAAY,GAAG,CAAC,CAAC;QACtE,CAAC;QACD,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,KAAK,GAAG,GAAG;YAAE,GAAG,GAAG,KAAK,CAAC;IAC/B,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,CAAC;AACzC,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAsB;IAC9C,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,KAAK,GAAuB,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,OAAO;QACL,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC;QACvB,GAAG,EAAE,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsB,EACtB,IAAY,EACZ,MAAyB,EACzB,gBAAgB,GAAG,uBAAuB;IAE1C,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACnD,MAAM,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC;IAE5C,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS;QAAE,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACxE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,aAAa;QAAE,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,MAAM,oBAAoB,GAAG,eAAe,CAAC,IAAI,CAAC;IAElD,yEAAyE;IACzE,wEAAwE;IACxE,uEAAuE;IACvE,2EAA2E;IAC3E,8BAA8B;IAC9B,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACpC,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO;YAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACzE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAChC,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;YAAE,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,kBAAkB,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,CAC/C,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAC9E,CAAC,MAAM,CAAC;IACT,MAAM,uBAAuB,GAAG,kBAAkB,CAAC,IAAI,GAAG,kBAAkB,CAAC;IAE7E,MAAM,mBAAmB,GAAG,aAAa,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAE1E,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,YAAY;QAC5B,aAAa,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC;QAC3B,eAAe,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,WAAW,CAAC,CAAC,MAAM;QAC/F,gBAAgB,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,YAAY,CAAC;aACvF,MAAM;QACT,iBAAiB,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,aAAa,CAAC;aACzF,MAAM;QACT,uBAAuB,EAAE,oBAAoB;QAC7C,oBAAoB,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QAChF,YAAY,EAAE,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,MAAM;QAChF,qBAAqB,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;QACpF,yBAAyB,EAAE,uBAAuB;QAClD,mBAAmB,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,qBAAqB,CAAC,CAAC,MAAM;QAC3F,iBAAiB,EAAE,cAAc,CAAC,mBAAmB,CAAC,MAAM,EAAE,CAAC;QAC/D,kBAAkB,EAAE,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACpD,sBAAsB,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,MAAM;QAC5F,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,cAAc,CAAC,CAAC,MAAM;QAC1F,8DAA8D;QAC9D,EAAE;QACF,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,sEAAsE;QACtE,+DAA+D;QAC/D,kEAAkE;QAClE,sEAAsE;QACtE,uEAAuE;QACvE,sEAAsE;QACtE,iEAAiE;QACjE,EAAE;QACF,wEAAwE;QACxE,yEAAyE;QACzE,mEAAmE;QACnE,sBAAsB,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM;QACrD,8BAA8B,EAAE,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAC3D,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc,CACtF,CAAC,MAAM;KACT,CAAC;IAEF,IAAI,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,kCAAkC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACtE,OAAO,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;QACpD,OAAO,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;IACtD,CAAC;SAAM,IAAI,MAAM,EAAE,CAAC;QAClB,MAAM,SAAS,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC3C,OAAO,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;QACpD,OAAO,CAAC,0BAA0B,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;AACvC,CAAC"}

package/dist/text-lines.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared, pure line/comment classification used by both StructuralCalculator
+ * and TextualCalculator (spec.md §16.5, §16.6). Not a calculator itself —
+ * just the byte/line bookkeeping both of them need, factored out so neither
+ * calculator duplicates it.
+ */
+import type { ComplexityFacts, SourceRange } from "@untangle-code/domain";
+export interface LineClassification {
+    /** Physical line count of the scope (`endLine - startLine + 1`, or 0 for an empty range). */
+    physicalLoc: number;
+    /** Set of absolute physical line numbers touched by any comment range. */
+    commentLines: Set<number>;
+    /** Subset of `commentLines` whose owning comment looks like a doc comment. */
+    docLines: Set<number>;
+    /** Absolute line numbers that are blank (whitespace-only) and not comment lines. */
+    blankLines: Set<number>;
+}
+/**
+ * Classifies every physical line of `scopeRange` within `sourceText` as
+ * blank, comment, and/or doc-comment. `comments` is expected already
+ * narrowed to the scope (e.g. via `selectSymbolFacts`).
+ *
+ * Documented simplification (README "Entscheidungen" #3): a line touched by
+ * *any part* of a comment range counts as a comment line in full, even for a
+ * trailing `code(); // comment` line — `ComplexityFacts` gives byte ranges,
+ * not a column split between code and comment, so a line can't be split
+ * further without raw-text heuristics beyond this package's scope.
+ */
+export declare function classifyLines(sourceText: string, scopeRange: SourceRange, comments: readonly SourceRange[]): LineClassification;
+/** Re-exported for calculators that need to iterate raw scope lines directly. */
+export declare function scopeLines(sourceText: string, scopeRange: SourceRange): string[];
+/** Convenience: comments already narrowed to one scope (see `selectSymbolFacts`). */
+export declare function commentsOf(facts: ComplexityFacts): readonly SourceRange[];
+//# sourceMappingURL=text-lines.d.ts.map

package/dist/text-lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-lines.d.ts","sourceRoot":"","sources":["../src/text-lines.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAY1E,MAAM,WAAW,kBAAkB;IACjC,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,oFAAoF;IACpF,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,WAAW,EACvB,QAAQ,EAAE,SAAS,WAAW,EAAE,GAC/B,kBAAkB,CA+BpB;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,GAAG,MAAM,EAAE,CAMhF;AAED,qFAAqF;AACrF,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,WAAW,EAAE,CAEzE"}

package/dist/text-lines.js

@@ -0,0 +1,60 @@
+import { sliceByRange, splitLines } from "./scope.js";
+/** Leading markers recognized as "doc comment" (Untangle decision — see README "Entscheidungen" #3). */
+const DOC_COMMENT_MARKERS = ["/**", "///", '"""', "'''", "##!", "//!", "/// "];
+function isDocCommentText(commentText) {
+    const trimmed = commentText.trimStart();
+    return DOC_COMMENT_MARKERS.some((marker) => trimmed.startsWith(marker));
+}
+/**
+ * Classifies every physical line of `scopeRange` within `sourceText` as
+ * blank, comment, and/or doc-comment. `comments` is expected already
+ * narrowed to the scope (e.g. via `selectSymbolFacts`).
+ *
+ * Documented simplification (README "Entscheidungen" #3): a line touched by
+ * *any part* of a comment range counts as a comment line in full, even for a
+ * trailing `code(); // comment` line — `ComplexityFacts` gives byte ranges,
+ * not a column split between code and comment, so a line can't be split
+ * further without raw-text heuristics beyond this package's scope.
+ */
+export function classifyLines(sourceText, scopeRange, comments) {
+    const scopeText = sliceByRange(sourceText, scopeRange);
+    const lines = splitLines(scopeText);
+    // A trailing newline at the end of the range produces one extra empty
+    // element from split("\n"); drop it so physicalLoc reflects real lines.
+    const physicalLines = lines.length > 1 && lines[lines.length - 1] === "" && scopeText.endsWith("\n")
+        ? lines.slice(0, -1)
+        : lines;
+    const physicalLoc = physicalLines.length;
+    const commentLines = new Set();
+    const docLines = new Set();
+    for (const range of comments) {
+        const isDoc = isDocCommentText(sliceByRange(sourceText, range));
+        for (let line = range.startLine; line <= range.endLine; line++) {
+            commentLines.add(line);
+            if (isDoc)
+                docLines.add(line);
+        }
+    }
+    const blankLines = new Set();
+    for (let i = 0; i < physicalLines.length; i++) {
+        const lineNo = scopeRange.startLine + i;
+        const text = physicalLines[i] ?? "";
+        if (text.trim().length === 0 && !commentLines.has(lineNo)) {
+            blankLines.add(lineNo);
+        }
+    }
+    return { physicalLoc, commentLines, docLines, blankLines };
+}
+/** Re-exported for calculators that need to iterate raw scope lines directly. */
+export function scopeLines(sourceText, scopeRange) {
+    const scopeText = sliceByRange(sourceText, scopeRange);
+    const lines = splitLines(scopeText);
+    return lines.length > 1 && lines[lines.length - 1] === "" && scopeText.endsWith("\n")
+        ? lines.slice(0, -1)
+        : lines;
+}
+/** Convenience: comments already narrowed to one scope (see `selectSymbolFacts`). */
+export function commentsOf(facts) {
+    return facts.comments;
+}
+//# sourceMappingURL=text-lines.js.map

package/dist/text-lines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-lines.js","sourceRoot":"","sources":["../src/text-lines.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,wGAAwG;AACxG,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAE/E,SAAS,gBAAgB,CAAC,WAAmB;IAC3C,MAAM,OAAO,GAAG,WAAW,CAAC,SAAS,EAAE,CAAC;IACxC,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AAC1E,CAAC;AAaD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,UAAkB,EAClB,UAAuB,EACvB,QAAgC;IAEhC,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACpC,sEAAsE;IACtE,wEAAwE;IACxE,MAAM,aAAa,GACjB,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC5E,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC;IACZ,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC;IAEzC,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,gBAAgB,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;QAChE,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,SAAS,EAAE,IAAI,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;YAC/D,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,KAAK;gBAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,GAAG,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAC7D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,UAAuB;IACpE,MAAM,SAAS,GAAG,YAAY,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC;QACnF,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACpB,CAAC,CAAC,KAAK,CAAC;AACZ,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,OAAO,KAAK,CAAC,QAAQ,CAAC;AACxB,CAAC"}

package/dist/textual.d.ts

@@ -0,0 +1,28 @@
+/**
+ * TextualCalculator (spec.md §16.6).
+ *
+ * `identifier_entropy`: Shannon entropy in bits computed over the multiset of
+ * *characters* across all identifier occurrences in scope (not per-token
+ * entropy over distinct identifier names) — Untangle decision, documented in
+ * README "Entscheidungen" #6: character-level entropy reacts to naming style
+ * (e.g. heavy abbreviation vs. verbose camelCase) rather than being dominated
+ * by how many times short common names like `i`/`x` repeat.
+ *
+ * `magic_literal_count`: counts `number`/`string` literals only (booleans,
+ * `null`, regexes, templates are never "magic" by definition here), excluding
+ * a small, documented allowlist (see `EXCLUDED_NUMERIC_LITERALS`/
+ * `EXCLUDED_STRING_LITERALS` below).
+ *
+ * `todo_count`/`fixme_count`/`hack_count`: case-insensitive whole-word
+ * occurrence counts of `TODO`/`FIXME`/`HACK` inside comment text, sliced from
+ * `sourceText` via each comment's byte range.
+ */
+import type { ComplexityFacts, SourceRange } from "@untangle-code/domain";
+import type { MetricsResult } from "./types.js";
+/**
+ * @param facts Facts already narrowed to the target scope.
+ * @param sourceText Full original file content (UTF-8).
+ * @param scopeRange The scope's own range.
+ */
+export declare function computeTextual(facts: ComplexityFacts, sourceText: string, scopeRange: SourceRange, algorithmVersion?: string): MetricsResult;
+//# sourceMappingURL=textual.d.ts.map

package/dist/textual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textual.d.ts","sourceRoot":"","sources":["../src/textual.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAK1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqBhD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,eAAe,EACtB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,WAAW,EACvB,gBAAgB,SAAwB,GACvC,aAAa,CA+Df"}

package/dist/textual.js

@@ -0,0 +1,75 @@
+import { frequenciesOf, shannonEntropy } from "./entropy.js";
+import { sliceByRange } from "./scope.js";
+import { classifyLines, scopeLines } from "./text-lines.js";
+const EXCLUDED_NUMERIC_LITERALS = new Set(["0", "1", "-1"]);
+const EXCLUDED_STRING_LITERALS = new Set(['""', "''", "``", ""]);
+function isMagicLiteral(literalKind, raw) {
+    const trimmed = raw.trim();
+    if (literalKind === "number")
+        return !EXCLUDED_NUMERIC_LITERALS.has(trimmed);
+    if (literalKind === "string")
+        return !EXCLUDED_STRING_LITERALS.has(trimmed);
+    return false;
+}
+function countWholeWordOccurrences(text, word) {
+    const pattern = new RegExp(`\\b${word}\\b`, "gi");
+    return text.match(pattern)?.length ?? 0;
+}
+function codepointLength(text) {
+    return Array.from(text).length;
+}
+/**
+ * @param facts Facts already narrowed to the target scope.
+ * @param sourceText Full original file content (UTF-8).
+ * @param scopeRange The scope's own range.
+ */
+export function computeTextual(facts, sourceText, scopeRange, algorithmVersion = "untangle-textual-v1") {
+    const scopeText = sliceByRange(sourceText, scopeRange);
+    const { physicalLoc, commentLines, docLines } = classifyLines(sourceText, scopeRange, facts.comments);
+    const lines = scopeLines(sourceText, scopeRange);
+    const lineLengths = lines.map(codepointLength);
+    const avgLineLength = lineLengths.length > 0 ? lineLengths.reduce((s, v) => s + v, 0) / lineLengths.length : 0;
+    const maxLineLength = lineLengths.length > 0 ? Math.max(...lineLengths) : 0;
+    const identifierNames = facts.identifiers.map((id) => id.name);
+    const uniqueIdentifiers = new Set(identifierNames);
+    const identifierLengths = identifierNames.map(codepointLength);
+    const avgIdentifierLength = identifierLengths.length > 0
+        ? identifierLengths.reduce((s, v) => s + v, 0) / identifierLengths.length
+        : 0;
+    const identifierCharFrequencies = frequenciesOf(identifierNames.join("").split(""), (ch) => ch);
+    const magicLiteralCount = facts.literals.filter((lit) => isMagicLiteral(lit.literalKind, lit.raw)).length;
+    let todoCount = 0;
+    let fixmeCount = 0;
+    let hackCount = 0;
+    for (const commentRange of facts.comments) {
+        const text = sliceByRange(sourceText, commentRange);
+        todoCount += countWholeWordOccurrences(text, "todo");
+        fixmeCount += countWholeWordOccurrences(text, "fixme");
+        hackCount += countWholeWordOccurrences(text, "hack");
+    }
+    const operatorTexts = facts.operators.map((t) => t.text);
+    const operandTexts = facts.operands.map((t) => t.text);
+    const metrics = {
+        character_count: codepointLength(scopeText),
+        byte_count: scopeRange.endByte - scopeRange.startByte,
+        token_count: operatorTexts.length + operandTexts.length,
+        avg_line_length: avgLineLength,
+        max_line_length: maxLineLength,
+        comment_ratio: physicalLoc > 0 ? commentLines.size / physicalLoc : 0,
+        doc_ratio: physicalLoc > 0 ? docLines.size / physicalLoc : 0,
+        identifier_count: identifierNames.length,
+        unique_identifier_count: uniqueIdentifiers.size,
+        avg_identifier_length: avgIdentifierLength,
+        identifier_entropy: shannonEntropy(identifierCharFrequencies.values()),
+        magic_literal_count: magicLiteralCount,
+        todo_count: todoCount,
+        fixme_count: fixmeCount,
+        hack_count: hackCount,
+        operator_count: operatorTexts.length,
+        operand_count: operandTexts.length,
+        unique_operator_count: new Set(operatorTexts).size,
+        unique_operand_count: new Set(operandTexts).size,
+    };
+    return { metrics, algorithmVersion };
+}
+//# sourceMappingURL=textual.js.map

package/dist/textual.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Local result contracts for the complexity calculators (spec.md §16,
+ * architecture.md §15.2). These are NOT domain types: domain fixes the
+ * *stored* shapes (`ComplexitySnapshotV1`, `ComplexitySummaryV1`,
+ * `CognitiveContributionV1`, `MetricContribution`); this module fixes the
+ * richer *calculator output* shapes that `assemble.ts` folds into those
+ * stored shapes. See README "Entscheidungen" for the mapping rules.
+ */
+import type { CognitiveContributionV1, MetricContribution } from "@untangle-code/domain";
+/**
+ * One cyclomatic decision contribution. Structurally a `MetricContribution`
+ * (so it can be stored directly in `ComplexitySnapshotV1.cyclomatic.contributors`)
+ * plus the two spec.md §16.2/§16.3 membership flags that tell which of the two
+ * totals (classic/extended) this contribution feeds.
+ */
+export interface CyclomaticContribution extends MetricContribution {
+    countsForClassic: boolean;
+    countsForExtended: boolean;
+}
+/** Output of `computeCyclomatic` (spec.md §16.2, §16.3). */
+export interface CyclomaticResult {
+    classic: number;
+    extended: number;
+    /** Superset list (extended ⊇ classic); filter by the membership flags. */
+    contributions: CyclomaticContribution[];
+    algorithmVersion: string;
+}
+/** Output of `computeCognitive` (spec.md §16.4, algorithm `untangle-cognitive-v1`). */
+export interface CognitiveResult {
+    value: number;
+    algorithm: string;
+    contributions: CognitiveContributionV1[];
+}
+/**
+ * Coupling and API-surface inputs that require whole-repository graph or
+ * export/visibility knowledge the facts-only calculators do not have. Every
+ * field is optional and is only ever included in the output when supplied
+ * here — never guessed or defaulted (per the work order).
+ */
+export interface StructuralExternalInput {
+    fanIn?: number;
+    fanOut?: number;
+    afferentCoupling?: number;
+    efferentCoupling?: number;
+    /** Used as-is when given; otherwise derived from afferent/efferent when both are present. */
+    instability?: number;
+    importInDegree?: number;
+    importOutDegree?: number;
+    inheritanceDepth?: number;
+    publicApiCount?: number;
+}
+/** Envelope every non-cyclomatic/cognitive calculator returns (uniform API, spec.md §16.5–§16.8). */
+export interface MetricsResult {
+    metrics: Record<string, number>;
+    algorithmVersion: string;
+}
+/** Output of `computeHalstead` (spec.md §16.7). */
+export interface HalsteadResult {
+    metrics: Record<string, number>;
+    /** Present only when `options.includeEstimates` is set; explicitly labeled as estimates. */
+    estimates?: {
+        /** Estimated time to implement, in seconds (Halstead's Stroud-number-18 heuristic). */
+        timeSeconds: number;
+        /** Estimated defect count (`volume / 3000`, Halstead's heuristic). */
+        estimatedBugs: number;
+    };
+    algorithmVersion: string;
+}
+/** Output of `computeMaintainability` (spec.md §16.9). */
+export interface MaintainabilityResult {
+    /** Clamped to [0, 100]. */
+    value: number;
+    /** Unclamped `MI_raw` before the `* 100 / 171` rescale, for debugging/explain. */
+    raw: number;
+    /** The exact formula used, as required by the work order. */
+    formula: string;
+    algorithmVersion: string;
+}
+/** One value to aggregate (spec.md §16.10). */
+export interface AggregationEntry {
+    /** Dedupe key — duplicate ids are folded to a single sample (first occurrence wins). */
+    metricsScopeId: string;
+    value: number;
+    /** SLOC of the scope this value came from, for the SLOC-weighted mean. */
+    sloc?: number;
+}
+/** Result of `aggregate()` (spec.md §16.10). */
+export interface AggregationResult {
+    count: number;
+    sum: number;
+    mean: number;
+    median: number;
+    max: number;
+    p90: number;
+    p95: number;
+    /** Undefined when no entry carried an `sloc`. */
+    slocWeightedMean?: number;
+    /** Number of (deduplicated) entries whose value is strictly greater than each configured threshold, keyed by the threshold's decimal string. */
+    thresholdCounts: Record<string, number>;
+    /** Number of raw entries dropped because their `metricsScopeId` repeated an earlier one. */
+    duplicatesDropped: number;
+}
+/** One line of `explainSymbol`'s ranked, human-readable breakdown. */
+export interface ExplainEntry {
+    rank: number;
+    metric: "cyclomatic" | "cognitive";
+    kind: string;
+    line: number;
+    value: number;
+    text: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@untangle-code/complexity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Untangle complexity engine: pure, deterministic calculators for cyclomatic, cognitive, structural, textual, syntactic, Halstead and maintainability metrics, plus aggregation and explainability (spec.md §16).",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/lboel/untangle",
+  "bugs": {
+    "url": "https://github.com/lboel/untangle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lboel/untangle.git",
+    "directory": "packages/complexity"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "!dist/**/test-support.*",
+    "!dist/**/test-support/**",
+    "!dist/**/testing/**",
+    "!dist/**/__tests__/**",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts",
+    "!src/**/test-support.ts",
+    "!src/**/test-support/**",
+    "!src/**/testing/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "dependencies": {
+    "@untangle-code/domain": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7",
+    "@untangle-code/parser-registry": "0.1.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/tsc-build.mjs tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }