@pythonidaer/complexity-report 1.0.2

package/function-hierarchy.js

@@ -0,0 +1,427 @@
+import { getBaseFunctionName } from './function-extraction/index.js';
+
+// escapeHtml will be imported from html-generators.js
+// Called from html-generators.js to avoid circular dependency
+let escapeHtml = null;
+
+/**
+ * Sets the escapeHtml function
+ * Called from html-generators.js to avoid circular dependency
+ * @param {Function} fn - escapeHtml function
+ */
+export function setEscapeHtml(fn) {
+  escapeHtml = fn;
+}
+
+/**
+ * Finds the immediate parent function for a callback
+ * @param {Object} func - Function object
+ * @param {Map} functionBoundaries - Map of function boundaries
+ * @param {Array} sortedFunctions - Sorted array of all functions
+ * @returns {Object|null} Parent function or null
+ */
+function findImmediateParentFunction(func, functionBoundaries, sortedFunctions) {
+  const funcBoundary = functionBoundaries.get(func.line);
+  if (!funcBoundary) {
+    return null;
+  }
+
+  const containingFunctions = Array.from(functionBoundaries.entries())
+    .filter(([fl, boundary]) =>
+      fl !== func.line
+      && boundary.start < funcBoundary.start
+      && boundary.end >= funcBoundary.end
+    )
+    .sort((a, b) => b[1].start - a[1].start);
+
+  if (containingFunctions.length === 0) {
+    return null;
+  }
+
+  const immediateParentLine = containingFunctions[0][0];
+  return sortedFunctions.find((f) => f.line === immediateParentLine) || null;
+}
+
+/**
+ * Returns the rightmost/leaf segment of a display name
+ * (framework-agnostic). Extraction (function-extraction.js) provides
+ * names from AST: method names (filter, sort, flatMap), hook names
+ * (useEffect, useCallback), handler labels (onClick handler), or
+ * variable/function names. We use that as the leaf; no whitelist of
+ * "callback types" is needed.
+ * @param {string} displayName - Full or hierarchical display name
+ * @returns {string} Leaf segment: last parenthetical content, or whole
+ */
+function getLeafName(displayName) {
+  if (!displayName || typeof displayName !== 'string') return displayName || '';
+  const match = displayName.match(/\(([^)]+)\)\s*$/);
+  return match ? match[1] : displayName;
+}
+
+/**
+ * Checks if a name is valid for use in hierarchical display (not a placeholder).
+ * @param {string} name - Leaf or base name
+ * @returns {boolean} True if valid
+ */
+function isValidNameForHierarchy(name) {
+  return name && name !== 'unknown' && name !== 'anonymous';
+}
+
+/**
+ * Checks if a function name indicates it's a cleanup callback
+ * Function names come from AST-based extraction, so this check is framework-agnostic
+ * @param {string} functionName - Function name to check
+ * @returns {boolean} True if it's a cleanup callback
+ */
+function isCleanupCallback(functionName) {
+  if (!functionName) return false;
+  return functionName.includes('return callback') || functionName === 'return';
+}
+
+/**
+ * Builds hierarchical display name using function boundaries
+ * (framework-agnostic). Recursively prepends parent names so nested
+ * functions show as "Parent (leaf)". The leaf name is whatever
+ * function-extraction.js provided from the AST (method name, hook,
+ * handler, variable name). No whitelist of callback types—works with
+ * any framework or API (filter, sort, flatMap, then, useEffect, etc.).
+ * @param {Object} func - Function object
+ * @param {Map} functionBoundaries - Map of function boundaries
+ * @param {Array} sortedFunctions - Sorted array of all functions
+ * @param {Set} visited - Set to track visited (prevents infinite loops)
+ * @returns {string} Full hierarchical display name
+ */
+function fixFunctionNameForCallback(
+  func,
+  functionBoundaries,
+  sortedFunctions,
+  visited = new Set()
+) {
+  const displayName = func.functionName || 'unknown';
+
+  // Prevent infinite loops
+  const funcKey = `${func.file}:${func.line}`;
+  if (visited.has(funcKey)) {
+    return displayName;
+  }
+  visited.add(funcKey);
+
+  if (!functionBoundaries) {
+    return displayName;
+  }
+
+  // Find the actual immediate parent using boundaries
+  const immediateParentFunc = findImmediateParentFunction(
+    func,
+    functionBoundaries,
+    sortedFunctions
+  );
+
+  if (!immediateParentFunc) {
+    // No parent found, return name as-is
+    return displayName;
+  }
+
+  // CRITICAL FIX: Cleanup callbacks should never be parents
+  // A cleanup callback is the return value of a function, so it can't
+  // contain other functions. If the parent is a cleanup callback, skip
+  // hierarchical naming to prevent incorrect nesting
+  if (isCleanupCallback(immediateParentFunc.functionName)) {
+    // Return the name as-is (cleanup callbacks are terminal - they don't have children)
+    return displayName;
+  }
+
+  // Recursively build the parent's hierarchical name
+  const parentHierarchicalName = fixFunctionNameForCallback(
+    immediateParentFunc,
+    functionBoundaries,
+    sortedFunctions,
+    new Set(visited)
+  );
+
+  const parentBaseName = getBaseFunctionName(parentHierarchicalName);
+  if (!isValidNameForHierarchy(parentBaseName)) {
+    return displayName;
+  }
+
+  // Framework-agnostic: use whatever name extraction gave us
+  // (method, hook, handler, variable name). No whitelist—any method
+  // (filter, sort, flatMap, then, etc.) or framework callback works.
+  const leafName = getLeafName(displayName);
+  if (isValidNameForHierarchy(leafName)) {
+    return `${parentHierarchicalName} → ${leafName}`;
+  }
+
+  return displayName;
+}
+
+/**
+ * Gets default column structure (used when not provided)
+ * @returns {Object} Column configuration
+ */
+function getDefaultColumnStructure() {
+  return {
+    groups: [
+      {
+        name: 'Control Flow',
+        columns: [
+          { key: 'if', label: 'if' },
+          { key: 'else if', label: 'else if' },
+          { key: 'for', label: 'for' },
+          { key: 'for...of', label: 'for...of' },
+          { key: 'for...in', label: 'for...in' },
+          { key: 'while', label: 'while' },
+          { key: 'do...while', label: 'do...while' },
+          { key: 'switch', label: 'switch' },
+          { key: 'case', label: 'case' },
+          { key: 'catch', label: 'catch' },
+        ],
+      },
+      {
+        name: 'Expressions',
+        columns: [
+          { key: 'ternary', label: '?:' },
+          { key: '&&', label: '&&' },
+          { key: '||', label: '||' },
+          { key: '??', label: '??' },
+          { key: '?.', label: '?.' },
+        ],
+      },
+      {
+        name: 'Function Parameters',
+        columns: [
+          { key: 'default parameter', label: 'default parameter' },
+        ],
+      },
+    ],
+    baseColumn: { key: 'base', label: 'base' },
+  };
+}
+
+/**
+ * Parses hierarchical display name into segments.
+ * Supports both "Parent → child → grandchild" (arrow) and
+ * "Parent (child) (grandchild)" (paren) formats.
+ * @param {string} displayName - Full hierarchical name
+ * @returns {string[]} Array of segment names
+ */
+function parseHierarchySegments(displayName) {
+  if (!displayName || typeof displayName !== 'string') {
+    return [displayName || ''];
+  }
+  if (displayName.includes(' → ')) {
+    return displayName
+      .split(/\s*→\s*/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+  const parts = displayName.split(/\s*\(\s*/);
+  return parts
+    .map((s) => s.replace(/\s*\)\s*$/, '').trim())
+    .filter(Boolean);
+}
+
+/**
+ * Renders function name for FCB: arrows between segments,
+ * last segment bold (highlights the function for this row).
+ * "Parent (child) (grandchild)" → "Parent → child → grandchild"
+ * with last in .function-name-leaf.
+ * @param {string} displayName - Full hierarchical display name
+ * @returns {string} HTML for the function-name cell content
+ */
+function formatFunctionNameDisplay(displayName) {
+  const segments = parseHierarchySegments(displayName);
+  if (segments.length === 0) return '';
+  const last = escapeHtml(segments[segments.length - 1]);
+  const rest = segments.slice(0, -1).map((s) => escapeHtml(s)).join(' → ');
+  const leafSpan = `<span class="function-name-leaf">${last}</span>`;
+  return rest ? `${rest} → ${leafSpan}` : leafSpan;
+}
+
+/**
+ * Generates HTML for a function table row with individual breakdown
+ * columns
+ * @param {string} displayName - Function display name
+ * @param {number} lineNumber - Start line number (1-based)
+ * @param {number} complexity - Function complexity
+ * @param {Object} breakdownData - Breakdown data object
+ * @param {Object} columnStructure - Column structure configuration
+ * @param {Set} emptyColumns - Set of column keys that are empty
+ * @param {Array} visibleColumns - Array of visible column objects
+ * @param {number} [functionStart] - Function start line
+ * @param {number} [functionEnd] - Function end line
+ * @param {number} [complexityThreshold] - Linter threshold
+ * @returns {string} HTML string for table row
+ */
+function generateFunctionRowHTML(
+  displayName,
+  lineNumber,
+  complexity,
+  breakdownData,
+  columnStructure,
+  emptyColumns,
+  visibleColumns,
+  functionStart,
+  functionEnd,
+  complexityThreshold
+) {
+  const startLine =
+    functionStart !== null && functionStart !== undefined
+      ? functionStart
+      : lineNumber;
+  const endLine =
+    functionEnd !== null && functionEnd !== undefined
+      ? functionEnd
+      : lineNumber;
+  // Generate cells only for visible columns (base = 1 is not shown as
+  // a column; see header "Function (base = 1)")
+  const breakdownCells = visibleColumns.map((col) => {
+    const value = breakdownData[col.key] || 0;
+    // Display "-" instead of 0 for better readability
+    const displayValue = value === 0 ? '-' : value;
+    // Add empty class for styling when value is "-"
+    const emptyClass = value === 0 ? ' breakdown-value-empty' : '';
+    return `<td class="breakdown-value${emptyClass}" data-column-key="${col.key}">${displayValue}</td>`;
+  });
+
+  const isAboveThreshold =
+    typeof complexityThreshold === 'number' &&
+    complexity > complexityThreshold;
+  const complexityCellClass = isAboveThreshold
+    ? 'complexity-value complexity-above-threshold'
+    : 'complexity-value';
+  const functionNameHTML = formatFunctionNameDisplay(displayName);
+  return `        <tr class="breakdown-function-row" data-line="${lineNumber}" data-function-start="${startLine}" data-function-end="${endLine}" role="button" tabindex="0" title="Click to jump to function in code; click again to clear">
+          <td class="function-name">${functionNameHTML}</td>
+          <td class="breakdown-line-value breakdown-line-column" data-line="${lineNumber}">${lineNumber}</td>
+          <td class="${complexityCellClass}"><span class="complexity-number">${complexity}</span></td>
+          ${breakdownCells.join('')}
+        </tr>`;
+}
+
+/**
+ * Formats all functions in scannable, unambiguous format (one per line)
+ * Shows only what ESLint counts for cyclomatic complexity
+ * Groups functions by base name, showing the highest complexity version
+ * @param {Array} functions - Array of function objects
+ * @param {Map} functionBoundaries - Map of functionLine -> { start, end }
+ * @param {Map} functionBreakdowns - Map of functionLine -> breakdown
+ * @param {string} _sourceCode - Source code (unused, kept for API compat)
+ * @param {Object} [columnStructure] - Column structure config
+ * @param {Set} [emptyColumns] - Set of column keys that are empty
+ * @param {boolean} [showAllColumns] - Show all columns including empty
+ * @param {number} [complexityThreshold] - Linter threshold
+ * @returns {string} Formatted HTML string
+ */
+export function formatFunctionHierarchy(
+  functions,
+  functionBoundaries,
+  functionBreakdowns,
+  _sourceCode,
+  columnStructure,
+  emptyColumns,
+  showAllColumns = false,
+  complexityThreshold
+) {
+  if (!escapeHtml) {
+    throw new Error('escapeHtml not set. Call setEscapeHtml() first.');
+  }
+
+  if (functions.length === 0) return '';
+
+  // Use default column structure if not provided
+  // (for backward compatibility with tests)
+  const structure = columnStructure || getDefaultColumnStructure();
+
+  // Use empty set if not provided (for backward compatibility with tests)
+  const emptyCols = emptyColumns || new Set();
+
+  // Build visible columns list based on showAllColumns flag
+  const visibleColumns = structure.groups.flatMap((group) => {
+    if (showAllColumns) {
+      return group.columns;
+    }
+    return group.columns.filter((col) => !emptyCols.has(col.key));
+  });
+
+  // Show each function exactly as ESLint reports it, but deduplicate by line number
+  // This ensures the breakdown matches the inline code annotations
+  const lineToFunction = new Map();
+
+  functions.forEach((func) => {
+    const line = func.line;
+    const existing = lineToFunction.get(line);
+
+    // If multiple functions on same line, keep the highest complexity
+    // (this handles edge cases where ESLint might report multiple)
+    if (
+      !existing ||
+      parseInt(func.complexity, 10) > parseInt(existing.complexity, 10)
+    ) {
+      lineToFunction.set(line, func);
+    }
+  });
+
+  // Show each function separately, but group functions with the same name
+  // and line number. This ensures functions with the same name but
+  // different line numbers are shown separately. This matches what users
+  // see in the code view annotations
+  const functionGroups = new Map();
+
+  Array.from(lineToFunction.values()).forEach((func) => {
+    // Use file + function name + line number as key to ensure uniqueness
+    // This allows multiple functions with the same name (e.g.,
+    // "addEventListener callback" on different lines) to be shown
+    // separately, each with their own breakdown
+    const key = `${func.file}:${func.functionName}:${func.line}`;
+
+    const existing = functionGroups.get(key);
+    if (!existing) {
+      functionGroups.set(key, func);
+    } else {
+      // If somehow we have duplicate key, keep the one with higher complexity
+      if (parseInt(func.complexity, 10) > parseInt(existing.complexity, 10)) {
+        functionGroups.set(key, func);
+      }
+    }
+  });
+
+  // Sort by line number to match code order
+  const sortedFunctions = Array.from(functionGroups.values()).sort(
+    (a, b) => a.line - b.line
+  );
+
+  const lines = [];
+
+  // Format each function on one line with individual breakdown columns
+  sortedFunctions.forEach((func) => {
+    const complexity = parseInt(func.complexity, 10);
+    const breakdown = functionBreakdowns.get(func.line);
+    const breakdownData = breakdown ? breakdown.breakdown : {};
+    const displayName = fixFunctionNameForCallback(
+      func,
+      functionBoundaries,
+      sortedFunctions
+    );
+    const boundary = functionBoundaries
+      ? functionBoundaries.get(func.line)
+      : null;
+    const functionStart = boundary ? boundary.start : null;
+    const functionEnd = boundary ? boundary.end : null;
+    const rowHTML = generateFunctionRowHTML(
+      displayName,
+      func.line,
+      complexity,
+      breakdownData,
+      structure,
+      emptyCols,
+      visibleColumns,
+      functionStart,
+      functionEnd,
+      complexityThreshold
+    );
+    lines.push(rowHTML);
+  });
+
+  return lines.join('\n');
+}

package/html-generators/about.js

@@ -0,0 +1,75 @@
+/**
+ * Generates the standalone "About Cyclomatic Complexity" page (complexity/about.html).
+ * Barebones, Istanbul-style. Examples live on a separate page.
+ * @returns {string} Full HTML document string
+ */
+export function generateAboutPageHTML() {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>About Cyclomatic Complexity</title>
+  <link rel="stylesheet" href="shared.css" />
+  <style>
+    body { padding: 20px; line-height: 1.4; }
+    .back-link { display: inline-block; margin-bottom: 12px; }
+    h1 { margin-top: 1rem; }
+    h2 { font-size: 16px; margin: 2rem 0 6px 0; }
+    .about-subheading { margin-top: 2rem; }
+    .about-last-p { margin-bottom: 2rem; }
+    .summary-two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 2rem; margin: 1rem 0 1rem 0; }
+    @media (max-width: 640px) { .summary-two-col { grid-template-columns: 1fr; } }
+    .summary-col { min-width: 0; }
+  </style>
+</head>
+<body>
+  <a href="index.html" class="back-link">← Back to complexity report</a>
+  <h1>About Cyclomatic Complexity</h1>
+  <p>Cyclomatic complexity measures the number of linearly independent execution paths through a function. It is calculated as a base value of 1 plus the number of decision points. Values above 10 typically indicate code that is harder to test, reason about, and safely modify, and should prompt refactoring. Cyclomatic complexity measures structural branching, not runtime performance or algorithmic efficiency.</p>
+  <h2>About This Report</h2>
+  <p>This complexity report extends <strong>ESLint's <code>complexity</code> rule</strong> and uses your project's chosen variant (<code>classic</code> or <code>modified</code>; see below). The report analyzes whatever files your ESLint config lints—commonly <code>*.ts</code>, <code>*.tsx</code>, and <code>*.js</code>. Single-file component formats (e.g. Vue <code>.vue</code>, Svelte <code>.svelte</code>) are only included if ESLint is configured to lint them. The lists below show examples of which constructs are counted and which are not.</p>
+  <div class="summary-two-col">
+    <div class="summary-col">
+      <h3>Counted</h3>
+      <ul>
+        <li><strong>Callable units</strong> — complexity is measured per function, method, or arrow function</li>
+        <li><strong>Statements</strong> — such as: <code>if</code>, <code>else if</code>, <code>switch</code> (in <code>modified</code>)</li>
+        <li><strong>Clauses</strong> — such as: <code>catch</code>, <code>case</code> (in <code>classic</code>)</li>
+        <li><strong>Loops</strong> — such as: <code>for</code>, <code>for...of</code>, <code>for...in</code>, <code>while</code>, <code>do...while</code></li>
+        <li><strong>Ternary</strong> —<code>? :</code></li>
+        <li><strong>Logical</strong> and — <code>&&</code></li>
+        <li><strong>Logical</strong> or — <code>||</code></li>
+        <li><strong>Optional chaining</strong> — <code>?.</code></li>
+        <li><strong>Nullish coalescing</strong> — <code>??</code></li>
+        <li><strong>Default parameters</strong></li>
+      </ul>
+    </div>
+    <div class="summary-col">
+      <h3>Not counted</h3>
+      <ul>
+        <li><strong>Top-level module code</strong> (code outside of functions); runs once at load and is not a callable unit</li>
+        <li><strong>Sequential statements</strong> (assignments, calls, declarations)</li>
+        <li><code>else</code> — does not introduce a new decision path by itself</li>
+        <li><code>try</code> — does not add complexity by itself; each <code>catch</code> adds one decision path</li>
+        <li>JSX without conditionals</li>
+        <li>Hook calls (only callbacks count)</li>
+        <li>TypeScript types, interfaces, generics</li>
+        <li>Literals, destructuring; arithmetic, strings</li>
+        <li>Property access; method calls</li>
+        <li><strong>Early exits</strong> (<code>return</code>, <code>break</code>, <code>continue</code>) — do not add complexity unless conditional</li>
+        <li><strong>Nesting depth</strong> — nesting itself does not increase cyclomatic complexity; only decision points do, and nested functions are measured independently with their own base complexity.</li>
+      </ul>
+    </div>
+  </div>
+  <h2>Classic vs modified variant</h2>
+  <p>ESLint's <code>complexity</code> rule supports two variants. This report uses the variant from your project's config.</p>
+  <ul>
+    <li><strong>Classic</strong> — Each <code>case</code> adds +1. So a switch with 5 cases adds 5 to complexity.</li>
+    <li><strong>Modified</strong> — The whole <code>switch</code> adds +1 regardless of how many cases. So a switch with 5 cases adds 1 to complexity.</li>
+  </ul>
+  <h2 class="about-subheading">Cyclomatic vs. Cognitive Complexity</h2>
+  <p class="about-last-p">While cyclomatic complexity measures the number of independent execution paths in a function to estimate testing effort and structural risk, cognitive complexity is designed to reflect how difficult code is for a human to read and understand. Cognitive complexity increases with control flow and nesting that disrupts linear reading (such as conditionals, loops, and early exits), but intentionally does not track boolean expressions, default parameters, or short-circuit operators. By focusing on mental load rather than path count, cognitive complexity better highlights code that is technically correct but unnecessarily hard to reason about or maintain.</p>
+</body>
+</html>`;
+}

package/html-generators/file-boundary-builders.js

@@ -0,0 +1,36 @@
+/**
+ * Boundary maps for file page borders
+ */
+import { getIndentChars } from './file-helpers.js';
+
+/**
+ * Builds a map from each line number to the innermost function span containing it.
+ * @param {Map} functionBoundaries - Map of function lines to boundary objects
+ * @param {number} sourceLinesLength - Total number of source lines
+ * @param {string[]} sourceLines - Source lines (1-based index)
+ * @returns {Object} Plain object: line number -> { start, end, indent }
+ */
+export function buildLineToSpan(
+  functionBoundaries,
+  sourceLinesLength,
+  sourceLines
+) {
+  const lineToSpan = {};
+  const boundaries = [...functionBoundaries.values()].map((b) => ({
+    start: b.start,
+    end: b.end,
+  }));
+  for (let L = 1; L <= sourceLinesLength; L += 1) {
+    const containing = boundaries.filter(
+      ({ start, end }) => start <= L && L <= end
+    );
+    if (containing.length === 0) continue;
+    const innermost = containing.reduce((best, cur) =>
+      (cur.end - cur.start) < (best.end - best.start) ? cur : best
+    );
+    const startLine = sourceLines[innermost.start - 1];
+    const indent = typeof startLine === 'string' ? getIndentChars(startLine) : 0;
+    lineToSpan[L] = { start: innermost.start, end: innermost.end, indent };
+  }
+  return lineToSpan;
+}