@untangle-code/complexity 0.0.0-stage → 0.1.1

package/NOTICE

@@ -0,0 +1,90 @@
+# NOTICE
+
+Copyright (C) 2026 Luke Bölling and contributors.
+
+This attribution covers original Untangle work. Contributors retain copyright in
+their contributions. Third-party packages, grammars and other materials retain
+their own copyright holders, licenses and notices; this line does not replace them.
+
+## License — binding decision
+
+Untangle is licensed under the **GNU Affero General Public License, Version 3
+(AGPL-3.0-only)**. See [`LICENSE`](./LICENSE).
+
+This decision is **final, not provisional**, and was explicitly instructed by
+the project owner. No contributor, agent or tool may change it without a new
+explicit instruction.
+
+The repository-wide license covers Untangle's first-party source code, scripts,
+tests, fixtures, configuration, documentation, website and brand artwork, including
+the logo and 3D yarn illustrations. Every workspace `package.json` declares
+`"license": "AGPL-3.0-only"`. There is no separately licensed enterprise component
+or separate permissive license for documentation or brand assets.
+
+Third-party code, embedded grammars, dependency assets and their notices retain
+their original licenses. Their inclusion does not relicense those works. The
+repository license does not grant trademark rights or change the license of a
+repository analyzed with Untangle. See the repository's `docs/LICENSING.md` for
+scope and verification details.
+
+This resolves the license question left open in `vision.md` §14 and completes
+`product.md` §16, item 2.
+
+## Rationale
+
+- **Network copyleft fits the intended product model.** AGPL §13 sets source
+  availability requirements for modified versions used through a computer network.
+  The current local CLI/stdio-MCP entry and future shared-server modes share the
+  same license.
+- **Local-first analysis has a clear boundary.** Running Untangle against a codebase
+  does not replace that codebase's own license with Untangle's license.
+- **First-party components share one license.** Implemented components and future
+  official plugins use this repository's licensing policy. Planned integrations do
+  not establish implemented or published products.
+
+## Deliberately accepted consequence
+
+The project deliberately chooses AGPL rather than a permissive embedding license.
+Redistribution, modifications and combined works must be assessed against the
+actual terms in `LICENSE`, including applicable Corresponding Source requirements.
+No permissive exception, commercial dual license or special contract-only package
+license is granted or promised by this notice.
+
+## Dependencies
+
+Third-party runtime dependencies are checked against the allowlist in
+`scripts/check-licenses.mjs`. Their licenses and copyright notices remain unchanged
+and traceable through package `THIRD_PARTY_LICENSES.md` files, grammar provenance,
+the lockfile and release SBOM. The allowlist includes MIT / Apache-2.0 / BSD / ISC
+and other explicitly listed licenses; it is not a license grant for dependencies.
+
+The allowlist in `scripts/check-licenses.mjs` applies to **dependencies**, not
+workspace packages. Untangle's own packages carry AGPL-3.0-only and are excluded
+from that check.
+
+## Clean room
+
+Untangle is an independent implementation with its own data models, APIs, tool
+names, tests and sources. Feature ideas may be derived from publicly observable
+behavior and generally known techniques. Third-party source code is not copied,
+including from AGPL projects even where the license would permit it.
+
+## Contribution terms
+
+Pull requests are welcome under the repository's existing AGPL-3.0-only license.
+No separate CLA, copyright assignment or DCO sign-off is required. Contributors
+must have the right to submit their work under those terms. See CONTRIBUTING.md.
+
+## Release decisions
+
+- [x] Copyright attribution: Luke Bölling, with contributors retaining their rights.
+- [x] Contributions use AGPL-3.0-only without an additional CLA or DCO gate.
+
+## Open legal items before public beta
+
+- [ ] Trademark search for the product name `Untangle`.
+- [ ] Registration and legal review of the npm scope `@untangle-code`.
+- [ ] Verify source availability and notices for each released network daemon/server
+  mode (WP-59). The current stdio MCP `untangle_about` already reports the license,
+  source repository and build commit when supplied; metadata alone does not prove
+  that a concrete deployed version's source is available.

package/README.md

@@ -1,3 +1,236 @@
-# Temporary Holding Version
+# @untangle-code/complexity
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Untangle's complexity engine (spec.md §16, architecture.md §6.7, §15): pure deterministic
+calculators over domain `ComplexityFacts`/`ComplexityIRNode`. No I/O, parser-registry, embeddings,
+`Date.now()` or `Math.random()`. Every calculator is a pure function of facts/IR and algorithm/
+metric versions, returning snapshots and explainable contributions.
+
+Normative sources: [`spec.md`](../../spec.md) §16 (takes precedence),
+[`architecture.md`](../../architecture.md) §6.7, §15.
+
+<a id="modulübersicht"></a>
+
+## Modules
+
+| Module | Contents | Normative source |
+|---|---|---|
+| `scope.ts` | `selectSymbolFacts()` narrows file facts to a symbol; `containsRange`/`strictlyContainsRange`, `rangeKey`, `sliceByRange`, `splitLines` | arch §15.1 |
+| `cyclomatic.ts` | `computeCyclomatic()`: classic/extended, independent `logicalGroupId` groups counted once | spec §16.2–§16.3 |
+| `cognitive.ts` | `computeCognitive()`: explicit-depth-stack IR traversal, `untangle-cognitive-v1`; `assertCognitiveInvariant()` | spec §16.4; arch §15.3 |
+| `ir/build-ir.ts` | `buildSymbolIR()`: facts→IR, flat else-if siblings, logical-condition hoisting, lambda nesting, optional recursion marking from `RawCall` | arch §6.7; spec §16.4 |
+| `structural.ts` | `computeStructural()`: all §16.5 metrics; coupling/API metrics only with explicit `StructuralExternalInput` | spec §16.5 |
+| `textual.ts` | `computeTextual()`: all §16.6 metrics including `identifier_entropy`, `magic_literal_count`, TODO/FIXME/HACK | spec §16.6 |
+| `syntactic.ts` | `computeSyntactic()`: all §16.8 metrics; exact branching factors from `nodeKinds` preorder depths, IR root only as fallback | spec §16.8 |
+| `halstead.ts` | `computeHalstead()`: exact formulas including `max(n,1)`/`max(n2,1)` guards; time/bugs labeled estimates | spec §16.7 |
+| `maintainability.ts` | `computeMaintainability()`: exact default formula, clamped [0,100], formula returned as text | spec §16.9 |
+| `aggregator.ts` | `aggregate()`: count/sum/mean/median/max/p90/p95/SLOC-weighted mean/thresholds, deduplication by `metricsScopeId` | spec §16.10 |
+| `scope-aggregate.ts` | `aggregateScopeTree()`, `checkScopeTreeInvariants()`, `checkScopeCoverage()`/`checkSelectionCoverage()`, `assertScopeTreeInvariants()`, `selectScopeEntries()`: scope-TREE aggregation **without double counting**, three readings, value-bound/count checks (WP-82) | spec §16.10 |
+| `scope-identity.ts` | `withUniqueScopeIds()`: converts per-file **nonunique** adapter `symbolScopeId` values to byte-range IDs and reports every collision (WP-82) | spec §16.10; E4 |
+| `explain.ts` | `explainSymbol()`: ordered human-readable explanations of largest contributions | Task |
+| `assemble.ts` | `assembleComplexitySnapshot()`: folds calculator results into domain `ComplexitySnapshotV1` | spec §16; arch §10.5 |
+| `entropy.ts` | Shared `shannonEntropy()`, `frequenciesOf()` | spec §16.6, §16.8 |
+| `node-kind-heuristics.ts` | Best-effort `classifyNodeKind()`, `isAsyncNodeKind()`, `isExceptionNodeKind()` for raw kind strings | Decision 5 |
+| `text-lines.ts` | Shared `classifyLines()`, `scopeLines()` for structural/textual metrics | Decision 3 |
+| `types.ts` | Local calculator result types (`CyclomaticResult`, `CognitiveResult`, `MetricsResult`, `AggregationResult`, `ExplainEntry`, …), **not** domain types | Decision 2 |
+
+Public symbols are re-exported only through `src/index.ts`.
+
+<a id="architekturentscheidung-scope-filterung-liegt-beim-aufrufer"></a>
+
+## Architecture decision: callers own scope filtering
+
+No calculator knows `symbolScopeId`. `selectSymbolFacts(facts, symbolScopeId)` narrows file-wide
+`ComplexityFacts` to one symbol; for `scope: "file"`, callers pass unfiltered facts. Every
+calculator stays easily testable and scope-agnostic; the same code calculates symbol/file metrics.
+
+<a id="entscheidungen"></a>
+
+## Decisions
+
+Reasoned choices left open by spec.md/architecture.md (task rule 9); downstream consumers should
+extend additively rather than redefine contracts locally.
+
+1. **Fact attribution is flat, not recursive.** `SymbolScopeFact.symbolScopeId` denotes exact
+   membership: facts belong to that symbol, not its nested named children, which receive their
+   own `SymbolScopeFact` and metrics. File aggregation instead sums across every file scope.
+
+2. **IR branching chains use flat siblings.** Architecture.md §15.3 does not fix their shape.
+   Every IR producer maps `if`/`else if`/`else` to sibling nodes under one parent, **not** raw AST
+   nested `alternate` structure. Else-if then receives **no** extra nesting penalty relative to
+   its if because both share ambient depth, satisfying spec.md §16.4 without special cases.
+   `ir/build-ir.ts` now implements this itself: `buildSymbolIR()` derives flat siblings from fact
+   byte ranges, reparenting continuation events to their enclosing if's final parent. Language
+   adapters therefore need not know IR shape.
+
+   Since the §16.4 correction, `ComplexitySnapshotV1.cognitive.contributors` uses full
+   `CognitiveContributionV1[]`: every persisted contribution requires structured position, kind,
+   base AND nesting. Former conversion to `MetricContribution` with free-form `note`
+   `base`/`nestingPenalty` violated this and was removed. Snapshots also carry
+   `maintainabilityFormula` because §16.9 requires the actual formula explicitly.
+
+3. **Documentation-comment heuristic.** Facts do not distinguish ordinary/documentation
+   comments. After byte-range slicing, `text-lines.ts` treats prefixes `/**`, `///`, `"""`, `'''`,
+   `##!`, `//!` as documentation.
+
+4. **`instability` uses explicit values only.** Supplied values pass through unchanged. Otherwise
+   it is calculated only with BOTH `afferentCoupling` and `efferentCoupling` as
+   `efferent / (afferent + efferent)`, Martin's instability metric. It is never guessed from one
+   value or defaulted.
+
+5. **Node-kind-dependent counts are best effort:** `parameter_count`/`return_count`/
+   `exit_point_count`/`statement_count`/`expression_count`/`declaration_count`/
+   `async_construct_count`/`exception_construct_count`. `NodeKindFact.kind` is an opaque adapter
+   string, not a domain-normalized taxonomy. `node-kind-heuristics.ts` matches common grammar
+   conventions (`"return_statement"`, `"required_parameter"`, `"throw_statement"`,
+   `"async_function"`, …), a documented versionable heuristic and **candidate for additive domain
+   extension** (see `openIssues`).
+
+6. **`identifier_entropy` is character entropy, not token entropy.** Shannon entropy uses
+   concatenated characters from all identifier occurrences, not frequencies of distinct names.
+   It responds to naming style, such as abbreviations versus descriptive camelCase, rather than
+   being dominated by repeated short frequent names (`i`, `x`).
+
+7. **`ast_branching_factor_avg`/`_max` reconstruct exactly from preorder `nodeKinds` depths.**
+   Adapters emit DFS preorder (the input contract in `syntactic.ts`). Each node's parent is the
+   nearest preceding entry with smaller depth, determining child counts and branching exactly
+   without pointers or guesses. This is real AST branching, not sparse control-flow IR branching;
+   optional IR roots are fallback only for empty `nodeKinds`, such as handwritten IR fixtures.
+
+8. **Percentiles use linear interpolation**, following NumPy `linear`/Excel `PERCENTILE.INC`:
+   `index = p * (n - 1)`, interpolating `sorted[floor(index)]` and `sorted[ceil(index)]`. Median
+   uses the same formula at `p = 0.5`, without a separate even/odd branch.
+
+9. **`magic_literal_count` exclusions:** numbers `{0, 1, -1}`, strings `{"", ''}` using trimmed
+   raw text. Only `number`/`string` literals can be magic, never
+   `boolean`/`null`/`regex`/`template`/`other`.
+
+10. **`comment_lines` counts every touched line fully**, including `code(); // comment` lines.
+    `SourceRange` supplies byte rather than column boundaries; reliably separating code/comment
+    line portions would require extra raw-text heuristics.
+
+11. **Calculators return `{ metrics: Record<string, number>; algorithmVersion: string }`**, except
+    cyclomatic/cognitive, which have dedicated domain-compatible results. This provides a shared
+    API across all seven calculators, even where `ComplexitySnapshotV1` has no per-family version slot.
+
+<a id="öffentliche-api-auszug-siehe-srcindexts"></a>
+
+## Public API (excerpt; see `src/index.ts`)
+
+```ts
+buildSymbolIR(facts: ComplexityFacts, symbolScopeId: string, options?: BuildSymbolIROptions): ComplexityIRNode | undefined
+computeCyclomatic(facts: ComplexityFacts, baseLine: number, algorithmVersion: string): CyclomaticResult
+computeCognitive(symbolRoot: ComplexityIRNode, algorithm: string): CognitiveResult
+computeStructural(facts, sourceText, scopeRange, external?, algorithmVersion?): MetricsResult
+computeTextual(facts, sourceText, scopeRange, algorithmVersion?): MetricsResult
+computeSyntactic(facts, sloc, irRoot?, algorithmVersion?): MetricsResult
+computeHalstead(tokens: HalsteadTokens, options?, algorithmVersion?): HalsteadResult
+computeMaintainability(input: MaintainabilityInput, algorithmVersion?): MaintainabilityResult
+aggregate(entries: AggregationEntry[], thresholds?: number[]): AggregationResult
+aggregateScopeTree(nodes: ScopeMetricNodeV1[], options?: ScopeTreeOptions): ScopeTreeAggregateV1
+checkScopeTreeInvariants(nodes: ScopeMetricNodeV1[], options?: ScopeTreeOptions): ScopeInvariantViolationV1[]
+assertScopeTreeInvariants(nodes: ScopeMetricNodeV1[], options?: ScopeTreeOptions): void
+selectScopeEntries(nodes: ScopeMetricNodeV1[], reading: ScopeSumReading): AggregationEntry[]
+withUniqueScopeIds(facts: ComplexityFacts, calls: readonly RawCall[], idPrefix: string): UniqueScopeIdsResultV1
+explainSymbol(snapshot: ComplexitySnapshotV1, top?: number): ExplainEntry[]
+assembleComplexitySnapshot(context: SnapshotContext, parts: SnapshotParts): ComplexitySnapshotV1
+selectSymbolFacts(facts: ComplexityFacts, symbolScopeId: string): ComplexityFacts
+```
+
+<a id="aggregation-ohne-doppelzählung-wp-82"></a>
+
+## Aggregation without double counting (WP-82)
+
+`aggregate()` deduplicates `metricsScopeId`, handling duplicate input fragments, **not** nested
+scopes. `buildSymbolIR()` deliberately includes every descendant in target IR (spec.md §16.4's
+documented nesting context): a `file` scope carries all class, method and closure control flow.
+Each has its own ID, so naive summation counts source once per enclosing scope. Measured on this
+repository, the naive sum is approximately three times larger.
+
+`scope-aggregate.ts` defines **three readings**, each counting every scope once while differing
+in included nesting context:
+
+| Reading | Counted values | Question answered |
+|---|---|---|
+| `top_level` | Root `inclusiveValue` | Difficulty of reading a file **as one whole**; every enclosing function contributes nesting |
+| `execution_unit` (**default**) | Outermost execution-unit `inclusiveValue` plus ancestors' `selfValue` (file/class/interface) | Difficulty of each **function by itself**; nesting resets at each outermost function, keeping nested closures inside it. The only reading that withstands comparison with an established tool (X8) |
+| `self` | Every scope's `selfValue` | Complexity in each scope's **own body**; lower bound, with differences exactly the nesting penalty |
+
+There is deliberately no **leaf-only reading**: direct control flow in a parent with children
+belongs to no leaf and would disappear, the silent loss E4 forbids. `leafOnlySum` still appears as
+a diagnostic alongside `leafOnlyDroppedAmount`, the omitted amount. The same applies to
+`naiveSum` and `doubleCountedAmount`.
+
+**Invariant checks are mandatory.** `aggregateScopeTree()` **throws** `UntangleError` with
+`ANALYSIS_INCOMPLETE` on any scope violation. Its two stages serve different purposes:
+
+1. **Value bound** (`checkScopeTreeInvariants`):
+   `selfValue(S) + Σ inclusiveValue(direct children) <= inclusiveValue(S)`, plus leaf equality,
+   non-negativity, known parents and no cycles. This **one-sided** bound catches too-small parent
+   values, hence **missing** content. Too-large parents—including double counting—also satisfy
+   it and remain undetected. Values alone cannot distinguish inflation from a scope with much
+   own control flow. This stage therefore does **not** guarantee no double counting; earlier
+   documentation incorrectly claimed that.
+2. **Counting check** (`checkScopeCoverage` per reading, `checkAllScopeCoverage` for all three):
+   every scope contributes to **exactly one** selected summand, not two (`scope_counted_twice`)
+   and not zero (`scope_uncounted`). **This** guarantees the three selection sums. It checks
+   selection structure; internal double counting within a value remains the calculator's concern.
+   `checkSelectionCoverage(nodes, selection, label)` runs the same check on arbitrary selections,
+   making alarm cases demonstrable rather than merely asserted.
+
+Metrics with a per-scope base, such as cyclomatic `M = 1 + decision_points`, use `perScopeBase`
+normalization for checks. Their three sums reverse order because `self` counts the base per scope
+and `top_level` per file.
+
+`duplicatesDropped` is **not** merely operational: repeated `metricsScopeId` with equal values
+is deduplicated without violation, as §16.10 requires for repeated retrieval fragments. In real
+scope trees where each ID must denote one scope, any positive `duplicatesDropped` means lost
+content. `scripts/complexity-report.mjs` aborts on it.
+
+All this requires IDs to identify scopes uniquely. Adapter `symbolScopeId` currently does
+**not**: per-parent ordinals plus qualified names collide for anonymous callbacks under anonymous
+parents, affecting roughly one fifth of scopes here. `withUniqueScopeIds()` rewrites IDs to byte
+ranges and **reports** every collision rather than hiding it. The adapter owns the actual fix.
+
+Run through `scripts/complexity-report.mjs` (`pnpm complexity:report`).
+
+## Tests
+
+105 co-located Vitest cases under `src/**/*.test.ts`. Notable coverage:
+
+- `golden-real-source.test.ts` exercises real TypeScript/JavaScript through real adapters, not
+  handwritten facts/IR. Hand-calculated cognitive values are **17** for TS triple nesting,
+  else-if, `&&`, lambda, and **13** for JS switch/case, `||`, loop, catch and direct recursion.
+  Complete contribution lists, hand-calculated cyclomatic values,
+  `sum(contributions.total) === total`, real-file branching factors and formula/structure
+  assertions verify persisted snapshots.
+- `cognitive.test.ts` has a handwritten golden case (triple nesting, else-if, logical sequence,
+  lambda), total **17**, full contributions, and a corrupted-list test requiring
+  `assertCognitiveInvariant` to throw. `ir/build-ir.test.ts` isolates chain flattening, condition
+  hoisting, lambda context, recursion marking and switch/case modeling.
+- Every calculator has a hand-calculated case: the spec §16.2 eight-point cyclomatic example
+  plus extended grouping; Halstead n1/n2/N1/N2/volume/difficulty/effort; full MI formula;
+  percentiles against reference set 1..10.
+- `sum(contributions) === total` is explicitly tested for cyclomatic and cognitive.
+
+```bash
+pnpm --filter @untangle-code/complexity run typecheck   # tsc --noEmit, including tests
+pnpm --filter @untangle-code/complexity run test         # vitest run
+pnpm --filter @untangle-code/complexity run build         # tsc -p tsconfig.json -> dist/
+```
+
+<a id="lizenz"></a>
+
+## License
+
+
+**AGPL-3.0-only.** This package includes the complete license in [`LICENSE`](./LICENSE), the
+license-choice rationale in [`NOTICE`](./NOTICE), and licenses for all third-party production
+dependencies in [`THIRD_PARTY_LICENSES.md`](./THIRD_PARTY_LICENSES.md). All three ship in the npm
+tarball: AGPL-3.0-only §4 and §5 require recipients to receive the license; a README alone is not
+a copy of the license.
+
+Local use alone does not trigger an obligation. Copyleft obligations apply to redistribution and
+providing a network service (AGPL §13).
+
+Corresponding TypeScript source ships under `src/` in the same tarball; the complete repository
+is available at <https://github.com/lboel/untangle>.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,24 @@
+# Third-party licenses — @untangle-code/complexity
+
+Generated by `pnpm third-party-licenses` from this package's installed
+production dependency tree: transitive `dependencies`, across
+workspace edges, with no `devDependencies` included. The generator reads
+each resolved package's `package.json` in `node_modules`; nothing is maintained by hand
+or estimated.
+
+Do not edit manually: `pnpm third-party-licenses --check` fails on drift,
+and `pnpm check-publishable` rejects packages without a current file.
+
+This file exists because `docs/BUILD_PLAN.md`, risk R6, makes
+per-package `THIRD_PARTY_LICENSES.md` a release gate for npm publication.
+
+Untangle itself is **AGPL-3.0-only** (see `LICENSE` and `NOTICE` in
+this package). The packages below are third-party works; their own
+licenses and copyright notices continue to apply unchanged. Workspace
+packages (`@untangle-code/*`) are not listed here; they belong to the same
+work and use the same AGPL-3.0-only license.
+
+## Result: no third-party dependencies
+
+This package has no production dependencies outside the workspace.
+The list is empty because none exist, not because they were not checked.

package/dist/aggregator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Aggregator (spec.md §16.10). Aggregates one metric's values across many
+ * scopes (a file's symbols, a repo's files, ...).
+ *
+ * Percentile method (Untangle decision, documented per the work order):
+ * linear interpolation between closest ranks, i.e. for a sorted array `s` of
+ * length `n` and percentile `p` in [0, 1], `index = p * (n - 1)`,
+ * `result = s[floor(index)] + (s[ceil(index)] - s[floor(index)]) * frac(index)`.
+ * This is the same convention as NumPy's default `linear` interpolation and
+ * Excel's `PERCENTILE.INC`. `median` uses the same formula at `p = 0.5`, so
+ * it agrees with `p90`/`p95` on the same interpolation rule rather than using
+ * a different odd/even-length special case.
+ *
+ * Deduplication: entries are deduplicated by `metricsScopeId` (first
+ * occurrence wins) before any statistic is computed, per spec.md §16.10
+ * ("Doppelte Retrieval-Fragmente MÜSSEN über metrics_scope_id dedupliziert
+ * werden").
+ */
+import type { AggregationEntry, AggregationResult } from "./types.js";
+/**
+ * @param entries Raw values, one per scope. Duplicate `metricsScopeId`s are
+ *   dropped (first occurrence wins) before aggregating.
+ * @param thresholds Threshold values; `thresholdCounts` counts entries whose
+ *   (deduplicated) value is strictly greater than each threshold, keyed by
+ *   the threshold's own decimal string (e.g. `"10"`, `"15.5"`).
+ */
+export declare function aggregate(entries: readonly AggregationEntry[], thresholds?: readonly number[]): AggregationResult;
+//# sourceMappingURL=aggregator.d.ts.map

package/dist/aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregator.d.ts","sourceRoot":"","sources":["../src/aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiCtE;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,iBAAiB,CA2CnB"}

package/dist/aggregator.js

@@ -0,0 +1,77 @@
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    if (sorted.length === 1)
+        return sorted[0];
+    const index = p * (sorted.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    const lowerValue = sorted[lower];
+    const upperValue = sorted[upper];
+    if (lower === upper)
+        return lowerValue;
+    const fraction = index - lower;
+    return lowerValue + (upperValue - lowerValue) * fraction;
+}
+function dedupeByScopeId(entries) {
+    const seen = new Set();
+    const deduped = [];
+    let duplicatesDropped = 0;
+    for (const entry of entries) {
+        if (seen.has(entry.metricsScopeId)) {
+            duplicatesDropped++;
+            continue;
+        }
+        seen.add(entry.metricsScopeId);
+        deduped.push(entry);
+    }
+    return { deduped, duplicatesDropped };
+}
+/**
+ * @param entries Raw values, one per scope. Duplicate `metricsScopeId`s are
+ *   dropped (first occurrence wins) before aggregating.
+ * @param thresholds Threshold values; `thresholdCounts` counts entries whose
+ *   (deduplicated) value is strictly greater than each threshold, keyed by
+ *   the threshold's own decimal string (e.g. `"10"`, `"15.5"`).
+ */
+export function aggregate(entries, thresholds = []) {
+    const { deduped, duplicatesDropped } = dedupeByScopeId(entries);
+    const values = deduped.map((e) => e.value);
+    const sorted = [...values].sort((a, b) => a - b);
+    const count = sorted.length;
+    const sum = sorted.reduce((s, v) => s + v, 0);
+    const mean = count > 0 ? sum / count : 0;
+    const median = percentile(sorted, 0.5);
+    const max = count > 0 ? sorted[count - 1] : 0;
+    const p90 = percentile(sorted, 0.9);
+    const p95 = percentile(sorted, 0.95);
+    const weighted = deduped.filter((e) => e.sloc !== undefined);
+    let slocWeightedMean;
+    if (weighted.length > 0) {
+        const totalSloc = weighted.reduce((s, e) => s + e.sloc, 0);
+        slocWeightedMean =
+            totalSloc > 0
+                ? weighted.reduce((s, e) => s + e.value * e.sloc, 0) / totalSloc
+                : 0;
+    }
+    const thresholdCounts = {};
+    for (const threshold of thresholds) {
+        thresholdCounts[String(threshold)] = values.filter((v) => v > threshold).length;
+    }
+    const result = {
+        count,
+        sum,
+        mean,
+        median,
+        max,
+        p90,
+        p95,
+        thresholdCounts,
+        duplicatesDropped,
+    };
+    if (slocWeightedMean !== undefined) {
+        result.slocWeightedMean = slocWeightedMean;
+    }
+    return result;
+}
+//# sourceMappingURL=aggregator.js.map

package/dist/aggregator.js.map

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

package/dist/assemble.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Folds calculator outputs into the domain-stored `ComplexitySnapshotV1`
+ * shape (spec.md §16, architecture.md §10.5). Pure function of its inputs —
+ * `measuredAt`/`snapshotId` etc. are supplied by the caller (who owns the
+ * `Clock`/`Random`/identity ports); this package never calls `Date.now()` or
+ * generates ids itself.
+ *
+ * Mapping decisions (README "Entscheidungen" #2):
+ * - `cyclomatic.contributors` takes the calculator's superset contribution
+ *   list as-is (each `CyclomaticContribution` is structurally a
+ *   `MetricContribution` plus the two membership flags, which are dropped —
+ *   TypeScript's structural typing lets extra fields pass through, but they
+ *   are stripped explicitly here so the stored payload never leaks
+ *   calculator-internal fields).
+ * - `cognitive.contributors` stores the calculator's
+ *   `CognitiveContributionV1[]` UNCHANGED: spec.md §16.4 requires every
+ *   persisted contribution to carry source position, kind, base and nesting
+ *   share as structured fields ("jeder Beitrag MUSS Quellposition, Art,
+ *   Basis und Nesting-Anteil enthalten"), so `ComplexitySnapshotV1` keeps
+ *   the full shape instead of flattening `base`/`nestingPenalty` into a
+ *   free-text note.
+ * - `maintainabilityFormula` records the exact formula string the
+ *   maintainability calculator used (spec.md §16.9: "Untangle MUSS die
+ *   verwendete Formel explizit ausgeben").
+ */
+import type { ComplexityScope, ComplexitySnapshotV1, ParseQuality } from "@untangle-code/domain";
+import type { CognitiveResult, CyclomaticResult, MaintainabilityResult } from "./types.js";
+export interface SnapshotContext {
+    snapshotId: string;
+    scope: ComplexityScope;
+    scopeId: string;
+    repoId: string;
+    refId: string;
+    commitSha?: string;
+    metricsVersion: string;
+    /** ISO-8601, obtained by the caller via the `Clock` port. */
+    measuredAt: string;
+    parseQuality: ParseQuality;
+}
+export interface SnapshotParts {
+    cyclomatic: CyclomaticResult;
+    cognitive: CognitiveResult;
+    structural: Record<string, number>;
+    textual: Record<string, number>;
+    syntactic: Record<string, number>;
+    halstead: Record<string, number>;
+    maintainability: MaintainabilityResult;
+}
+export declare function assembleComplexitySnapshot(context: SnapshotContext, parts: SnapshotParts): ComplexitySnapshotV1;
+//# sourceMappingURL=assemble.d.ts.map

package/dist/assemble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAEpB,YAAY,EACb,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,eAAe,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,eAAe,EAAE,qBAAqB,CAAC;CACxC;AAaD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,aAAa,GACnB,oBAAoB,CAqCtB"}

package/dist/assemble.js

@@ -0,0 +1,43 @@
+function toMetricContribution(line, kind, value, note) {
+    const contribution = { line, kind, value };
+    if (note !== undefined)
+        contribution.note = note;
+    return contribution;
+}
+export function assembleComplexitySnapshot(context, parts) {
+    const snapshot = {
+        snapshotId: context.snapshotId,
+        scope: context.scope,
+        scopeId: context.scopeId,
+        repoId: context.repoId,
+        refId: context.refId,
+        metricsVersion: context.metricsVersion,
+        measuredAt: context.measuredAt,
+        parseQuality: context.parseQuality,
+        cyclomatic: {
+            classic: parts.cyclomatic.classic,
+            extended: parts.cyclomatic.extended,
+            contributors: parts.cyclomatic.contributions.map((c) => toMetricContribution(c.line, c.kind, c.value, c.note)),
+        },
+        cognitive: {
+            value: parts.cognitive.value,
+            algorithm: parts.cognitive.algorithm,
+            // Stored structurally, spec.md §16.4 (base/nestingPenalty/total are
+            // required fields of every persisted contribution). Copied so the
+            // snapshot never aliases the calculator's arrays.
+            contributors: parts.cognitive.contributions.map((c) => ({ ...c })),
+        },
+        structural: parts.structural,
+        textual: parts.textual,
+        syntactic: parts.syntactic,
+        halstead: parts.halstead,
+        maintainabilityIndex: parts.maintainability.value,
+        // spec.md §16.9: the formula actually used MUST be output explicitly.
+        maintainabilityFormula: parts.maintainability.formula,
+    };
+    if (context.commitSha !== undefined) {
+        snapshot.commitSha = context.commitSha;
+    }
+    return snapshot;
+}
+//# sourceMappingURL=assemble.js.map

package/dist/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../src/assemble.ts"],"names":[],"mappings":"AAyDA,SAAS,oBAAoB,CAC3B,IAAY,EACZ,IAAY,EACZ,KAAa,EACb,IAAa;IAEb,MAAM,YAAY,GAAuB,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC/D,IAAI,IAAI,KAAK,SAAS;QAAE,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC;IACjD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,OAAwB,EACxB,KAAoB;IAEpB,MAAM,QAAQ,GAAyB;QACrC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,UAAU,EAAE;YACV,OAAO,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO;YACjC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,QAAQ;YACnC,YAAY,EAAE,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACrD,oBAAoB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CACtD;SACF;QACD,SAAS,EAAE;YACT,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,KAAK;YAC5B,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,SAA2D;YACtF,oEAAoE;YACpE,kEAAkE;YAClE,kDAAkD;YAClD,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;SACnE;QACD,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,oBAAoB,EAAE,KAAK,CAAC,eAAe,CAAC,KAAK;QACjD,sEAAsE;QACtE,sBAAsB,EAAE,KAAK,CAAC,eAAe,CAAC,OAAO;KACtD,CAAC;IACF,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACpC,QAAQ,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACzC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/cognitive.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CognitiveCalculator, algorithm id `untangle-cognitive-v1` (spec.md §16.4,
+ * architecture.md §15.3).
+ *
+ * Traverses a `ComplexityIRNode` subtree (rooted at a `"symbol"` node) with
+ * an explicit depth-tracking stack, exactly as architecture.md §15.3
+ * prescribes ("current symbol, nesting depth, logical sequence state,
+ * recursion state"). Every contribution is `base + nestingPenalty = total`,
+ * and `value` is defined as `sum(contributions[].total)` — so the
+ * "sum of contributions equals the total" invariant (required by the work
+ * order) holds *by construction*; `assertCognitiveInvariant` is the
+ * belt-and-suspenders runtime guard the work order also asks for, exercised
+ * both indirectly (every golden test) and directly (a deliberately corrupted
+ * contribution list in cognitive.test.ts).
+ *
+ * REQUIRED INPUT CONTRACT (Untangle decision — architecture.md §15.3 leaves
+ * the exact IR shape for if/else-if/else chains unspecified; see README
+ * "Entscheidungen" #2 for the full rationale): a language adapter/IR builder
+ * feeding this calculator MUST represent an `if` / `else if` / `else` chain
+ * as a flat run of *sibling* IR nodes (one per branch) under the same
+ * parent, each carrying its own consequent block as `children` — never as
+ * the raw AST's nested "alternate" shape. This is what makes "`else if` gets
+ * no full new nesting increment" fall out of the traversal for free: siblings
+ * share the same ambient depth, so an `else if` scores exactly what its
+ * originating `if` scores, never more.
+ *
+ * Nesting rules (this calculator's own, documented decisions):
+ * - A node contributes when it carries a `decision` fact, or is itself kind
+ *   `"logical_sequence"` (a pre-grouped `&&`/`||` run) or `"recursion_marker"`.
+ * - `base` is always 1. `nestingPenalty` is the ambient depth *before*
+ *   entering the node (0 for a top-level construct), except recursion, whose
+ *   penalty is always 0 (recursion is flagged flatly, not nesting-scaled —
+ *   spec.md §16.4 only says it "KANN einen Beitrag erzeugen").
+ * - A node with `nestingBoundary: true` increments depth by exactly 1 for
+ *   its own children (this covers `if`/`else_if`/loops/`catch`/`ternary`/
+ *   `switch`/`case`/lambdas alike — lambdas use this same mechanism for the
+ *   "documented nesting context" spec.md §16.4 asks for). `logical_sequence`
+ *   and `recursion_marker` nodes are not nesting boundaries.
+ * - Decisions that share a `logicalGroupId` (an independent `&&`/`||` group
+ *   spanning multiple facts) contribute once, at the first occurrence
+ *   encountered during traversal — mirrors the cyclomatic-extended grouping
+ *   rule in cyclomatic.ts.
+ */
+import type { CognitiveContributionV1, ComplexityIRNode } from "@untangle-code/domain";
+import type { CognitiveResult } from "./types.js";
+/**
+ * @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 declare function computeCognitive(symbolRoot: ComplexityIRNode, algorithm: string): CognitiveResult;
+/**
+ * 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 declare function assertCognitiveInvariant(contributions: readonly CognitiveContributionV1[], total: number): void;
+//# sourceMappingURL=cognitive.d.ts.map

package/dist/cognitive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cognitive.d.ts","sourceRoot":"","sources":["../src/cognitive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAiDlD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAMjG;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,SAAS,uBAAuB,EAAE,EACjD,KAAK,EAAE,MAAM,GACZ,IAAI,CAON"}