@untangle-code/complexity 0.0.0-stage → 0.1.1

package/src/aggregator.ts

@@ -0,0 +1,105 @@
+/**
+ * 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";
+
+function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0] as number;
+  const index = p * (sorted.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  const lowerValue = sorted[lower] as number;
+  const upperValue = sorted[upper] as number;
+  if (lower === upper) return lowerValue;
+  const fraction = index - lower;
+  return lowerValue + (upperValue - lowerValue) * fraction;
+}
+
+function dedupeByScopeId(entries: readonly AggregationEntry[]): {
+  deduped: AggregationEntry[];
+  duplicatesDropped: number;
+} {
+  const seen = new Set<string>();
+  const deduped: AggregationEntry[] = [];
+  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: readonly AggregationEntry[],
+  thresholds: readonly number[] = [],
+): AggregationResult {
+  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] as number) : 0;
+  const p90 = percentile(sorted, 0.9);
+  const p95 = percentile(sorted, 0.95);
+
+  const weighted = deduped.filter((e) => e.sloc !== undefined);
+  let slocWeightedMean: number | undefined;
+  if (weighted.length > 0) {
+    const totalSloc = weighted.reduce((s, e) => s + (e.sloc as number), 0);
+    slocWeightedMean =
+      totalSloc > 0
+        ? weighted.reduce((s, e) => s + e.value * (e.sloc as number), 0) / totalSloc
+        : 0;
+  }
+
+  const thresholdCounts: Record<string, number> = {};
+  for (const threshold of thresholds) {
+    thresholdCounts[String(threshold)] = values.filter((v) => v > threshold).length;
+  }
+
+  const result: AggregationResult = {
+    count,
+    sum,
+    mean,
+    median,
+    max,
+    p90,
+    p95,
+    thresholdCounts,
+    duplicatesDropped,
+  };
+  if (slocWeightedMean !== undefined) {
+    result.slocWeightedMean = slocWeightedMean;
+  }
+  return result;
+}

package/src/assemble.ts

@@ -0,0 +1,109 @@
+/**
+ * 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,
+  MetricContribution,
+  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;
+}
+
+function toMetricContribution(
+  line: number,
+  kind: string,
+  value: number,
+  note?: string,
+): MetricContribution {
+  const contribution: MetricContribution = { line, kind, value };
+  if (note !== undefined) contribution.note = note;
+  return contribution;
+}
+
+export function assembleComplexitySnapshot(
+  context: SnapshotContext,
+  parts: SnapshotParts,
+): ComplexitySnapshotV1 {
+  const snapshot: ComplexitySnapshotV1 = {
+    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 as ComplexitySnapshotV1["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;
+}

package/src/cognitive.ts

@@ -0,0 +1,127 @@
+/**
+ * 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";
+
+interface WalkState {
+  depth: number;
+}
+
+function contributionKind(node: ComplexityIRNode): string {
+  if (node.decision) return node.decision.kind;
+  if (node.kind === "recursion_marker") return "recursion";
+  return node.kind;
+}
+
+function isContributing(node: ComplexityIRNode): boolean {
+  return (
+    node.decision != null || node.kind === "logical_sequence" || node.kind === "recursion_marker"
+  );
+}
+
+function walk(
+  node: ComplexityIRNode,
+  state: WalkState,
+  contributions: CognitiveContributionV1[],
+  seenGroups: Set<string>,
+): void {
+  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: ComplexityIRNode, algorithm: string): CognitiveResult {
+  const contributions: CognitiveContributionV1[] = [];
+  walk(symbolRoot, { depth: 0 }, contributions, new Set<string>());
+  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: readonly CognitiveContributionV1[],
+  total: number,
+): void {
+  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}`,
+    );
+  }
+}

package/src/cyclomatic.ts

@@ -0,0 +1,78 @@
+/**
+ * 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, DecisionFact } from "@untangle-code/domain";
+
+import type { CyclomaticContribution, CyclomaticResult } from "./types.js";
+
+function sortByPosition(decisions: readonly DecisionFact[]): DecisionFact[] {
+  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: ComplexityFacts,
+  baseLine: number,
+  algorithmVersion: string,
+): CyclomaticResult {
+  const contributions: CyclomaticContribution[] = [
+    {
+      line: baseLine,
+      kind: "base",
+      value: 1,
+      countsForClassic: true,
+      countsForExtended: true,
+      note: "M = 1 + decision points (spec.md §16.2)",
+    },
+  ];
+
+  const seenGroups = new Set<string>();
+  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 };
+}

package/src/entropy.ts

@@ -0,0 +1,30 @@
+/** Shannon entropy in bits over a frequency distribution (spec.md §16.6, §16.8). */
+export function shannonEntropy(frequencies: Iterable<number>): number {
+  let total = 0;
+  const values: number[] = [];
+  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<T>(
+  items: readonly T[],
+  key: (item: T) => string,
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    const k = key(item);
+    counts.set(k, (counts.get(k) ?? 0) + 1);
+  }
+  return counts;
+}

package/src/explain.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 {
+  CognitiveContributionV1,
+  ComplexitySnapshotV1,
+  MetricContribution,
+} from "@untangle-code/domain";
+
+import type { ExplainEntry } from "./types.js";
+
+function toCyclomaticEntries(
+  contributions: readonly MetricContribution[],
+): Array<Omit<ExplainEntry, "rank">> {
+  return contributions
+    .filter((c) => c.kind !== "base")
+    .map((c) => ({
+      metric: "cyclomatic" as const,
+      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: readonly CognitiveContributionV1[],
+): Array<Omit<ExplainEntry, "rank">> {
+  return contributions.map((c) => ({
+    metric: "cognitive" as const,
+    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: ComplexitySnapshotV1, top = 5): ExplainEntry[] {
+  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 }));
+}

package/src/halstead.ts

@@ -0,0 +1,54 @@
+/**
+ * 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";
+
+function log2(x: number): number {
+  return Math.log(x) / Math.LN2;
+}
+
+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 function computeHalstead(
+  tokens: HalsteadTokens,
+  options: HalsteadOptions = {},
+  algorithmVersion = "untangle-halstead-v1",
+): HalsteadResult {
+  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: Record<string, number> = { n1, n2, N1, N2, n, N, volume, difficulty, effort };
+
+  const result: HalsteadResult = { metrics, algorithmVersion };
+  if (options.includeEstimates) {
+    result.estimates = {
+      timeSeconds: effort / 18,
+      estimatedBugs: volume / 3000,
+    };
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @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";
+export type { NodeKindClass } from "./node-kind-heuristics.js";
+
+// IR producer: ComplexityFacts -> ComplexityIRNode bridge (architecture.md §6.7).
+export { buildSymbolIR } from "./ir/build-ir.js";
+export type { BuildSymbolIROptions } 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 type { HalsteadOptions } from "./halstead.js";
+export { computeMaintainability, MAINTAINABILITY_FORMULA } from "./maintainability.js";
+export type { MaintainabilityInput } 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";
+export type {
+  ScopeInvariantCode,
+  ScopeInvariantViolationV1,
+  ScopeMetricNodeV1,
+  ScopeSelectionKind,
+  ScopeSelectionV1,
+  ScopeSumReading,
+  ScopeTreeAggregateV1,
+  ScopeTreeOptions,
+} from "./scope-aggregate.js";
+// Eindeutige Scope-Ids als Voraussetzung der Dedupe ueber metricsScopeId (WP-82).
+export { withUniqueScopeIds } from "./scope-identity.js";
+export type { ScopeIdCollisionV1, UniqueScopeIdsResultV1 } 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 type { ProseLinkResolver, ProseMetricsOptions } from "./prose/metrics.js";
+export { explainSymbol } from "./explain.js";
+export { assembleComplexitySnapshot } from "./assemble.js";
+export type { SnapshotContext, SnapshotParts } from "./assemble.js";
+
+// Local result contracts (not domain types — see types.ts docs).
+export type {
+  AggregationEntry,
+  AggregationResult,
+  CognitiveResult,
+  CyclomaticContribution,
+  CyclomaticResult,
+  ExplainEntry,
+  HalsteadResult,
+  MaintainabilityResult,
+  MetricsResult,
+  StructuralExternalInput,
+} from "./types.js";