@untangle-code/complexity 0.0.0-stage → 0.1.1

package/src/text-lines.ts

@@ -0,0 +1,90 @@
+/**
+ * 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";
+
+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: string): boolean {
+  const trimmed = commentText.trimStart();
+  return DOC_COMMENT_MARKERS.some((marker) => trimmed.startsWith(marker));
+}
+
+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 function classifyLines(
+  sourceText: string,
+  scopeRange: SourceRange,
+  comments: readonly SourceRange[],
+): LineClassification {
+  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<number>();
+  const docLines = new Set<number>();
+  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<number>();
+  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: string, scopeRange: SourceRange): string[] {
+  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: ComplexityFacts): readonly SourceRange[] {
+  return facts.comments;
+}

package/src/textual.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 { frequenciesOf, shannonEntropy } from "./entropy.js";
+import { sliceByRange } from "./scope.js";
+import { classifyLines, scopeLines } from "./text-lines.js";
+import type { MetricsResult } from "./types.js";
+
+const EXCLUDED_NUMERIC_LITERALS = new Set(["0", "1", "-1"]);
+const EXCLUDED_STRING_LITERALS = new Set(['""', "''", "``", ""]);
+
+function isMagicLiteral(literalKind: string, raw: string): boolean {
+  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: string, word: string): number {
+  const pattern = new RegExp(`\\b${word}\\b`, "gi");
+  return text.match(pattern)?.length ?? 0;
+}
+
+function codepointLength(text: string): number {
+  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: ComplexityFacts,
+  sourceText: string,
+  scopeRange: SourceRange,
+  algorithmVersion = "untangle-textual-v1",
+): MetricsResult {
+  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: Record<string, number> = {
+    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 };
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+/**
+ * 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;
+}