@pythonidaer/complexity-report 1.0.2

package/decision-points/ternary-multiline.js

@@ -0,0 +1,86 @@
+/**
+ * Multi-line ternary handling and decision point entry building.
+ */
+
+import { getNodeLineRange } from './node-helpers.js';
+
+/**
+ * Returns whether the node is a multi-line ConditionalExpression.
+ * @param {Object} node - AST node
+ * @param {{ startLine: number, endLine: number }} lineRange - Line range
+ * @param {Object|null} columnRange - Column range or null
+ * @returns {boolean}
+ */
+export function isMultiLineTernaryNode(node, lineRange, columnRange) {
+  return lineRange.startLine !== lineRange.endLine &&
+    Boolean(columnRange) &&
+    node.type === 'ConditionalExpression';
+}
+
+/**
+ * Builds line ranges for a multi-line node using AST loc data.
+ * @param {number} startLine - Start line (1-based)
+ * @param {number} endLine - End line (1-based)
+ * @param {Object} nodeLoc - AST node.loc object with start/end
+ * @param {string[]} lines - Source lines
+ * @returns {Array<{ line: number, column: number, endColumn: number }>}
+ */
+export function buildMultiLineTernaryLineRanges(
+  startLine,
+  endLine,
+  nodeLoc,
+  lines
+) {
+  const lineRanges = [];
+  
+  // Only highlight the first line using AST start column to end of line
+  const lineLength = lines[startLine - 1]?.length ?? 0;
+  lineRanges.push({
+    line: startLine,
+    column: nodeLoc.start.column,
+    endColumn: lineLength,
+  });
+  
+  return lineRanges;
+}
+
+/**
+ * Builds one or more decision point entries for a node.
+ * Multi-line nodes get one entry with lines array (one per line).
+ * @param {Object} node - AST node
+ * @param {string} decisionType - Type string
+ * @param {number} functionLine - Function line
+ * @param {number} line - Report line
+ * @param {Object|null} columnRange - Column range or null
+ * @param {string[]} lines - Source code lines
+ * @returns {Array<Object>} Array of decision point objects to push
+ */
+export function buildDecisionPointEntries(
+  node,
+  decisionType,
+  functionLine,
+  line,
+  columnRange,
+  lines
+) {
+  const lineRange = getNodeLineRange(node);
+  
+  // Handle multi-line nodes (ternary, catch, if, etc.)
+  if (lineRange && lineRange.startLine !== lineRange.endLine) {
+    // Multi-line node: create ranges for each line based on AST loc
+    const lineRanges = buildMultiLineTernaryLineRanges(
+      lineRange.startLine,
+      lineRange.endLine,
+      node.loc,
+      lines
+    );
+    return [{ type: decisionType, line, functionLine, name: null, lines: lineRanges }];
+  }
+  
+  // Single-line node: use column range from AST
+  const base = { type: decisionType, line, functionLine, name: null };
+  const withCol = columnRange
+    ? { ...base, column: columnRange.column, endColumn: columnRange.endColumn }
+    : base;
+  return [withCol];
+}

package/export-generators/helpers.js

@@ -0,0 +1,309 @@
+import { getBaseFunctionName } from '../function-extraction/index.js';
+
+/**
+ * Checks if a function name has a callback/nested suffix
+ * (e.g., "functionA (useEffect)" or "functionA → useEffect")
+ * This is used to identify functions that should be deduplicated
+ * @param {string} functionName - Function name to check
+ * @returns {boolean} True if the name has a callback suffix
+ */
+function hasCallbackSuffix(functionName) {
+  if (!functionName) return false;
+  return /\s*\([^)]+\)\s*$/.test(functionName) || /\s*→\s*[^→]+$/.test(functionName);
+}
+
+/**
+ * Finds the immediate parent function for a callback using function boundaries
+ * @param {Object} func - Function object
+ * @param {Map} functionBoundaries - Map of function boundaries (file-specific)
+ * @param {Array} fileFunctions - Functions in the same file
+ * @returns {Object|null} Parent function or null
+ */
+function findImmediateParentFunction(func, functionBoundaries, fileFunctions) {
+  const funcBoundary = functionBoundaries.get(func.line);
+  if (!funcBoundary) {
+    return null;
+  }
+  
+  // Find all functions that contain this function (only within the same file)
+  const containingFunctions = Array.from(functionBoundaries.entries())
+    .filter(([fl, boundary]) => {
+      if (fl === func.line) return false;
+      // Function must be in the same file
+      const funcObj = fileFunctions.find(f => f.line === fl);
+      if (!funcObj) return false;
+      // Function must contain this callback
+      return boundary.start < funcBoundary.start && boundary.end > funcBoundary.end;
+    });
+  
+  if (containingFunctions.length === 0) {
+    return null;
+  }
+  
+  // Find the smallest containing function (immediate parent)
+  // Sort by size (end - start) ascending, then by start descending
+  containingFunctions.sort((a, b) => {
+    const sizeA = a[1].end - a[1].start;
+    const sizeB = b[1].end - b[1].start;
+    if (sizeA !== sizeB) {
+      // Smaller size first (more immediate parent)
+      return sizeA - sizeB;
+    }
+    // If same size, prefer later start (more nested)
+    return b[1].start - a[1].start;
+  });
+  
+  // Get the immediate parent (smallest containing function)
+  const immediateParentLine = containingFunctions[0][0];
+  return fileFunctions.find(f => f.line === immediateParentLine) || null;
+}
+
+/**
+ * Returns the rightmost/leaf segment of a display name.
+ * Framework-agnostic - matches function-hierarchy.js logic.
+ * @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';
+}
+
+/**
+ * Builds a full hierarchical function name by recursively finding parents
+ * Uses file-specific boundaries (like HTML report) for accurate detection
+ * @param {Object} func - Function object
+ * @param {Map} fileBoundaries - Map of function boundaries for this file
+ * @param {Array} fileFunctions - All functions in the same file
+ * @param {Set} visited - Set to track visited (prevents infinite loops)
+ * @returns {string} Full hierarchical name
+ */
+export function buildHierarchicalFunctionName(
+  func,
+  fileBoundaries,
+  fileFunctions,
+  visited = new Set()
+) {
+  let displayName = func.functionName || 'unknown';
+  
+  // Prevent infinite loops
+  const funcKey = `${func.file}:${func.line}`;
+  if (visited.has(funcKey)) {
+    return displayName;
+  }
+  visited.add(funcKey);
+  
+  if (!fileBoundaries || !fileFunctions) {
+    return displayName;
+  }
+  
+  // Find the actual immediate parent using boundaries
+  // (regardless of what the name says)
+  const immediateParentFunc = findImmediateParentFunction(
+    func,
+    fileBoundaries,
+    fileFunctions
+  );
+  
+  if (!immediateParentFunc) {
+    // No parent found, return name as-is
+    return displayName;
+  }
+  
+  const parentHierarchicalName = buildHierarchicalFunctionName(
+    immediateParentFunc,
+    fileBoundaries,
+    fileFunctions,
+    new Set(visited)
+  );
+
+  const parentBaseName = getBaseFunctionName(parentHierarchicalName);
+  if (!isValidNameForHierarchy(parentBaseName)) {
+    return displayName;
+  }
+
+  // Framework-agnostic: use whatever extraction gave us
+  // (method, hook, handler, variable name).
+  const leafName = getLeafName(displayName);
+  if (isValidNameForHierarchy(leafName)) {
+    return `${parentHierarchicalName} → ${leafName}`;
+  }
+
+  return displayName;
+}
+
+/**
+ * Checks if a function is nested within another function
+ * @param {Object} func - Function to check
+ * @param {Object} funcBoundary - Function's boundary
+ * @param {Array} allFunctions - All functions array
+ * @param {Map} functionBoundaries - Map of function boundaries
+ * @returns {boolean} True if function is nested
+ */
+function isFunctionNested(func, funcBoundary, allFunctions, functionBoundaries) {
+  for (const otherFunc of allFunctions) {
+    if (otherFunc.line === func.line) continue;
+    
+    // Only check nesting within the same file
+    if (otherFunc.file !== func.file) continue;
+    
+    const otherBoundary = functionBoundaries.get(otherFunc.line);
+    if (!otherBoundary) continue;
+    
+    // If otherFunc contains this func, it's nested
+    // Use strict < and > to ensure it's actually nested (not overlapping)
+    if (
+      otherBoundary.start < funcBoundary.start &&
+      otherBoundary.end > funcBoundary.end
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Adds a function to top-level list with deduplication (no boundary case)
+ * @param {Object} func - Function object
+ * @param {string} functionName - Function name
+ * @param {Array} topLevel - Top-level functions array
+ * @param {Set} seenBaseNames - Set of seen base names
+ */
+function addTopLevelFunctionNoBoundary(func, functionName, topLevel, seenBaseNames) {
+  const baseName = getBaseFunctionName(functionName);
+  const key = `${func.file}:${baseName}`;
+  
+  // Only deduplicate if this function has a callback suffix
+  // Standalone names like "useCallback callback" or "anonymous" don't have suffixes
+  if (hasCallbackSuffix(functionName)) {
+    // This is a callback variant - only include if we haven't seen the base name
+    if (!seenBaseNames.has(key)) {
+      seenBaseNames.add(key);
+      // Create a new function object with the base name for display
+      topLevel.push({
+        ...func,
+        functionName: baseName,
+      });
+    }
+  } else {
+    // Standalone name - deduplicate by exact name + file to avoid duplicates
+    const exactKey = `${func.file}:${functionName}`;
+    if (!seenBaseNames.has(exactKey)) {
+      seenBaseNames.add(exactKey);
+      // Also mark the base name as seen to prevent callback variants from being added
+      seenBaseNames.add(key);
+      topLevel.push(func);
+    }
+  }
+}
+
+/**
+ * Adds a function to top-level list with deduplication (has boundary case)
+ * @param {Object} func - Function object
+ * @param {string} functionName - Function name
+ * @param {Array} topLevel - Top-level functions array
+ * @param {Set} seenBaseNames - Set of seen base names
+ */
+function addTopLevelFunctionWithBoundary(func, functionName, topLevel, seenBaseNames) {
+  const baseName = getBaseFunctionName(functionName);
+  const key = `${func.file}:${baseName}`;
+  
+  // Only deduplicate if this function has a callback suffix
+  if (hasCallbackSuffix(functionName)) {
+    // This is a callback variant - only include if we haven't seen the base name
+    if (!seenBaseNames.has(key)) {
+      seenBaseNames.add(key);
+      // Create a new function object with the base name for display
+      topLevel.push({
+        ...func,
+        functionName: baseName,
+      });
+    }
+  } else {
+    // Standalone name or base function - deduplicate by exact name + file
+    const exactKey = `${func.file}:${functionName}`;
+    if (!seenBaseNames.has(exactKey)) {
+      seenBaseNames.add(exactKey);
+      // Also mark the base name as seen to prevent callback variants from being added
+      seenBaseNames.add(key);
+      topLevel.push(func);
+    }
+  }
+}
+
+/**
+ * Gets top-level functions only (no nested functions)
+ * Deduplicates by base function name so "functionA" and
+ * "functionA (useEffect callback)" only show "functionA" once.
+ * Standalone names like "useCallback callback" and "anonymous"
+ * are kept as-is.
+ * @param {Array} allFunctions - All functions array
+ * @param {Map} functionBoundaries - Map of function boundaries
+ * @returns {Array} Top-level functions only, deduplicated
+ */
+export function getTopLevelFunctions(allFunctions, functionBoundaries) {
+  const topLevel = [];
+  // Track seen base names to deduplicate
+  const seenBaseNames = new Set();
+  
+  for (const func of allFunctions) {
+    const functionName = func.functionName || 'unknown';
+    const funcBoundary = functionBoundaries.get(func.line);
+    
+    // If no boundary found, assume top-level (boundary detection failed)
+    if (!funcBoundary) {
+      addTopLevelFunctionNoBoundary(func, functionName, topLevel, seenBaseNames);
+      continue;
+    }
+    
+    // Check if this function is contained by any other function
+    const isNested = isFunctionNested(
+      func,
+      funcBoundary,
+      allFunctions,
+      functionBoundaries
+    );
+    
+    if (!isNested) {
+      addTopLevelFunctionWithBoundary(func, functionName, topLevel, seenBaseNames);
+    }
+  }
+  
+  return topLevel;
+}
+
+/**
+ * Groups functions by folder/file structure
+ * @param {Array} functions - Functions to group
+ * @param {Function} getDirectory - Function to get directory from file path
+ * @returns {Map} Map of directory -> file -> functions
+ */
+export function groupFunctionsByFolder(functions, getDirectory) {
+  const folderMap = new Map();
+  
+  for (const func of functions) {
+    const dir = getDirectory(func.file);
+    if (!folderMap.has(dir)) {
+      folderMap.set(dir, new Map());
+    }
+    
+    const fileMap = folderMap.get(dir);
+    if (!fileMap.has(func.file)) {
+      fileMap.set(func.file, []);
+    }
+    
+    fileMap.get(func.file).push(func);
+  }
+  
+  return folderMap;
+}

package/export-generators/index.js

@@ -0,0 +1,143 @@
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import {
+  generateAllFunctionsTXT,
+  generateAllFunctionsLeafOnlyTXT,
+  generateFunctionsByFolderTXT,
+  generateFunctionsByFolderLeafOnlyTXT,
+  generateFileNamesAlphabeticalTXT,
+} from './txt-exports.js';
+import {
+  generateAllFunctionsMD,
+  generateFunctionsByFolderMD,
+  generateFileNamesAlphabeticalMD,
+} from './md-exports.js';
+import { findFunctionBoundaries } from '../function-boundaries/index.js';
+
+/**
+ * Generates all export files (TXT, MD) for complexity report
+ * @param {Array} allFunctions - All functions array
+ * @param {string} projectRoot - Project root directory
+ * @param {string} exportDir - Directory to write export files to
+ * @returns {Object} Object with generated file paths
+ */
+export function generateAllExports(allFunctions, projectRoot, exportDir) {
+  // Create export directory if it doesn't exist
+  try {
+    mkdirSync(exportDir, { recursive: true });
+  } catch {
+    // Directory might already exist, ignore
+  }
+  
+  const generatedFiles = [];
+  
+  // Build file-specific boundaries map (like HTML report does)
+  // Map of filePath -> Map of line -> boundary
+  const fileBoundariesMap = new Map();
+  const fileToFunctions = new Map();
+  
+  // Group functions by file
+  allFunctions.forEach(func => {
+    if (!fileToFunctions.has(func.file)) {
+      fileToFunctions.set(func.file, []);
+    }
+    fileToFunctions.get(func.file).push(func);
+  });
+  
+  // Build boundaries for each file
+  for (const [filePath, functions] of fileToFunctions.entries()) {
+    const fullPath = resolve(projectRoot, filePath);
+    if (!existsSync(fullPath)) continue;
+    
+    try {
+      const sourceCode = readFileSync(fullPath, 'utf-8');
+      const boundaries = findFunctionBoundaries(sourceCode, functions);
+      fileBoundariesMap.set(filePath, boundaries);
+    } catch (error) {
+      console.warn(`Warning: Could not process ${filePath} for export boundaries:`, error.message);
+      // Create empty boundaries map for this file
+      fileBoundariesMap.set(filePath, new Map());
+    }
+  }
+  
+  // Generate all functions (including callbacks) exports
+  const allFunctionsTXT = generateAllFunctionsTXT(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const allFunctionsTXTPath = resolve(exportDir, 'function-names.all.txt');
+  writeFileSync(allFunctionsTXTPath, allFunctionsTXT, 'utf-8');
+  generatedFiles.push(allFunctionsTXTPath);
+  
+  const allFunctionsLeafOnlyTXT = generateAllFunctionsLeafOnlyTXT(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const allFunctionsLeafOnlyTXTPath = resolve(
+    exportDir,
+    'function-names.all-leaf.txt'
+  );
+  writeFileSync(
+    allFunctionsLeafOnlyTXTPath,
+    allFunctionsLeafOnlyTXT,
+    'utf-8'
+  );
+  generatedFiles.push(allFunctionsLeafOnlyTXTPath);
+  
+  const allFunctionsMD = generateAllFunctionsMD(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const allFunctionsMDPath = resolve(exportDir, 'function-names.all.md');
+  writeFileSync(allFunctionsMDPath, allFunctionsMD, 'utf-8');
+  generatedFiles.push(allFunctionsMDPath);
+  
+  // Generate functions by folder exports
+  const byFolderTXT = generateFunctionsByFolderTXT(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const byFolderTXTPath = resolve(exportDir, 'function-names-by-file.txt');
+  writeFileSync(byFolderTXTPath, byFolderTXT, 'utf-8');
+  generatedFiles.push(byFolderTXTPath);
+  
+  const byFolderLeafOnlyTXT = generateFunctionsByFolderLeafOnlyTXT(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const byFolderLeafOnlyTXTPath = resolve(
+    exportDir,
+    'function-names-by-file-leaf.txt'
+  );
+  writeFileSync(byFolderLeafOnlyTXTPath, byFolderLeafOnlyTXT, 'utf-8');
+  generatedFiles.push(byFolderLeafOnlyTXTPath);
+  
+  const byFolderMD = generateFunctionsByFolderMD(
+    allFunctions,
+    fileBoundariesMap,
+    fileToFunctions
+  );
+  const byFolderMDPath = resolve(exportDir, 'function-names-by-file.md');
+  writeFileSync(byFolderMDPath, byFolderMD, 'utf-8');
+  generatedFiles.push(byFolderMDPath);
+  
+  const fileNamesAlphabeticalTXT = generateFileNamesAlphabeticalTXT(fileToFunctions);
+  const fileNamesAlphabeticalTXTPath = resolve(exportDir, 'file-names-alphabetical.txt');
+  writeFileSync(fileNamesAlphabeticalTXTPath, fileNamesAlphabeticalTXT, 'utf-8');
+  generatedFiles.push(fileNamesAlphabeticalTXTPath);
+  
+  const fileNamesAlphabeticalMD = generateFileNamesAlphabeticalMD(fileToFunctions);
+  const fileNamesAlphabeticalMDPath = resolve(exportDir, 'file-names-alphabetical.md');
+  writeFileSync(fileNamesAlphabeticalMDPath, fileNamesAlphabeticalMD, 'utf-8');
+  generatedFiles.push(fileNamesAlphabeticalMDPath);
+  
+  return {
+    generatedFiles,
+    exportDir,
+  };
+}

package/export-generators/md-exports.js

@@ -0,0 +1,160 @@
+import { buildHierarchicalFunctionName, groupFunctionsByFolder } from './helpers.js';
+import { getDirectory } from '../function-extraction/index.js';
+
+/**
+ * Generates Markdown export for all functions including callbacks (alphabetically)
+ * @param {Array} allFunctions - All functions array
+ * @param {Map} fileBoundariesMap - Map of filePath -> Map of line -> boundary
+ * @param {Map} fileToFunctions - Map of filePath -> functions array
+ * @returns {string} Markdown string
+ */
+export function generateAllFunctionsMD(
+  allFunctions,
+  fileBoundariesMap,
+  fileToFunctions
+) {
+  // Build hierarchical names for all functions using file-specific boundaries
+  const functionsWithHierarchy = allFunctions.map(func => {
+    const fileBoundaries = fileBoundariesMap.get(func.file) || new Map();
+    const fileFunctions = fileToFunctions.get(func.file) || [];
+    return {
+      ...func,
+      hierarchicalName: buildHierarchicalFunctionName(
+        func,
+        fileBoundaries,
+        fileFunctions
+      ),
+    };
+  });
+  
+  // Sort alphabetically by hierarchical name
+  functionsWithHierarchy.sort((a, b) => {
+    const nameA = (a.hierarchicalName || 'unknown').toLowerCase();
+    const nameB = (b.hierarchicalName || 'unknown').toLowerCase();
+    return nameA.localeCompare(nameB);
+  });
+  
+  const tableRows = functionsWithHierarchy.map(func => {
+    const name = (func.hierarchicalName || '').replace(/\|/g, '|');
+    const complexity = parseInt(func.complexity, 10);
+    const location = `${func.file}:${func.line}`;
+    return `| ${name} | ${complexity} | ${location} |`;
+  });
+  
+  const lines = [
+    '# All Functions Including Callbacks',
+    '',
+    `**Total:** ${functionsWithHierarchy.length} functions`,
+    `**Generated:** ${new Date().toISOString()}`,
+    '',
+    '## Functions (Alphabetical)',
+    '',
+    '| Function | Complexity | Location |',
+    '| --- | --- | --- |',
+    ...tableRows,
+    '',
+  ];
+  
+  return lines.join('\n');
+}
+
+/**
+ * Generates Markdown export for functions organized by folder/file
+ * @param {Array} allFunctions - All functions array
+ * @param {Map} fileBoundariesMap - Map of filePath -> Map of line -> boundary
+ * @param {Map} fileToFunctions - Map of filePath -> functions array
+ * @returns {string} Markdown string
+ */
+export function generateFunctionsByFolderMD(
+  allFunctions,
+  fileBoundariesMap,
+  fileToFunctions
+) {
+  const folderMap = groupFunctionsByFolder(allFunctions, getDirectory);
+  
+  const lines = [
+    '# Functions by Folder/File',
+    '',
+    `**Total folders:** ${folderMap.size}`,
+    `**Total functions:** ${allFunctions.length}`,
+    `**Generated:** ${new Date().toISOString()}`,
+    '',
+    '## Structure',
+    '',
+  ];
+  
+  // Sort folders alphabetically
+  const sortedFolders = Array.from(folderMap.entries()).sort((a, b) => 
+    a[0].localeCompare(b[0])
+  );
+  
+  for (const [folder, fileMap] of sortedFolders) {
+    const folderDisplay = folder || '(root)';
+    lines.push(`### ${folderDisplay}/`);
+    lines.push('');
+    
+    // Sort files alphabetically
+    const sortedFiles = Array.from(fileMap.entries()).sort((a, b) => 
+      a[0].localeCompare(b[0])
+    );
+    
+    for (const [file, functions] of sortedFiles) {
+      const fileName = file.split('/').pop();
+      lines.push(`#### \`${fileName}\``);
+      lines.push('');
+      
+      // Get file-specific boundaries and functions
+      const fileBoundaries = fileBoundariesMap.get(file) || new Map();
+      const fileFunctions = fileToFunctions.get(file) || [];
+      
+      // Build hierarchical names and sort alphabetically
+      const functionsWithHierarchy = functions.map(func => ({
+        ...func,
+        hierarchicalName: buildHierarchicalFunctionName(
+          func,
+          fileBoundaries,
+          fileFunctions
+        ),
+      })).sort((a, b) => {
+        const nameA = (a.hierarchicalName || 'unknown').toLowerCase();
+        const nameB = (b.hierarchicalName || 'unknown').toLowerCase();
+        return nameA.localeCompare(nameB);
+      });
+      
+      lines.push('| Function | Complexity | Location |');
+      lines.push('| --- | --- | --- |');
+      for (const func of functionsWithHierarchy) {
+        const name = (func.hierarchicalName || '').replace(/\|/g, '|');
+        const complexity = parseInt(func.complexity, 10);
+        lines.push(`| ${name} | ${complexity} | line ${func.line} |`);
+      }
+      lines.push('');
+      lines.push('');
+    }
+  }
+  
+  return lines.join('\n');
+}
+
+/**
+ * Generates Markdown export of all file names (paths) in alphabetical order
+ * @param {Map} fileToFunctions - Map of filePath -> functions array
+ * @returns {string} Markdown string
+ */
+export function generateFileNamesAlphabeticalMD(fileToFunctions) {
+  const sortedFiles = Array.from(fileToFunctions.keys()).sort(
+    (a, b) => a.localeCompare(b)
+  );
+  const lines = [
+    '# File Names (Alphabetical)',
+    '',
+    `**Total files:** ${sortedFiles.length}`,
+    `**Generated:** ${new Date().toISOString()}`,
+    '',
+    '## Files',
+    '',
+    ...sortedFiles.map(file => `- \`${file.replace(/`/g, '\\`')}\``),
+    '',
+  ];
+  return lines.join('\n');
+}