@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/build-docs-incremental.js

@@ -7,11 +7,17 @@
  * significantly speeding up the build process.
  */
 
-import { execSync } from 'child_process';
-import { existsSync, statSync, readFileSync, writeFileSync, readdirSync, mkdirSync, rmSync, cpSync, utimesSync } from 'fs';
-import { join, dirname, relative } from 'path';
+import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
+import { existsSync } from 'fs';
+
+// Import modules
+import { scanDirectory, getLatestSourceModTime, getLatestDocModTime } from './build-docs/file-utils.js';
+import { shouldSkipDueToCleanGitState, getGitStatus } from './build-docs/git-utils.js';
+import { getSourceFileHashes, hasSourceChanged, hashesMatch, getExistingDocHashes } from './build-docs/hash-utils.js';
+import { loadCache, saveCache, primeCacheFromExistingDocs } from './build-docs/cache-utils.js';
+import { shouldRunTypeDoc, needsRebuild } from './build-docs/build-decision.js';
+import { runTypeDoc } from './build-docs/typedoc-runner.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -27,900 +33,13 @@ const DOCS_RELEVANT_PATHS = [
   'packages/core/typedoc.json'
 ];
 
-/**
- * Recursively scan directory for files matching pattern
- */
-function scanDirectory(dir, extensions, ignorePatterns = []) {
-  const files = [];
-  
-  function scan(currentDir) {
-    if (!existsSync(currentDir)) {
-      return;
-    }
-    
-    try {
-      const items = readdirSync(currentDir, { withFileTypes: true });
-      
-      for (const item of items) {
-        const fullPath = join(currentDir, item.name);
-        
-        // Skip ignored patterns
-        const shouldIgnore = ignorePatterns.some(pattern => {
-          const relativePath = fullPath.replace(SRC_DIR + '/', '');
-          return pattern.test(relativePath);
-        });
-        
-        if (shouldIgnore) {
-          continue;
-        }
-        
-        if (item.isDirectory() && !item.name.startsWith('.') && item.name !== 'node_modules') {
-          scan(fullPath);
-        } else if (item.isFile()) {
-          const ext = item.name.substring(item.name.lastIndexOf('.'));
-          if (extensions.includes(ext)) {
-            files.push(fullPath);
-          }
-        }
-      }
-    } catch (err) {
-      // Skip directories we can't read
-    }
-  }
-  
-  scan(dir);
-  return files;
-}
-
-/**
- * Determine if we're inside a git repository
- */
-function isGitRepository() {
-  try {
-    execSync('git rev-parse --is-inside-work-tree', {
-      cwd: REPO_ROOT,
-      stdio: 'pipe'
-    });
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Check if git reports any relevant source changes
- */
-function hasGitTrackedSourceChanges() {
-  if (!isGitRepository()) {
-    return true; // Without git context, err on the side of rebuilding
-  }
-
-  try {
-    const status = execSync(`git status --porcelain -- ${DOCS_RELEVANT_PATHS.join(' ')}`.trim(), {
-      cwd: REPO_ROOT,
-      encoding: 'utf-8',
-      stdio: 'pipe'
-    }).trim();
-
-    return status.length > 0;
-  } catch (err) {
-    console.log('⚠️  Unable to determine git status for docs generation, running TypeDoc to be safe.');
-    return true;
-  }
-}
-
-/**
- * If we don't have a cache yet but the repo is clean and docs exist, we can skip
- */
-function shouldSkipDueToCleanGitState() {
-  if (!existsSync(DOCS_DIR)) {
-    return false;
-  }
-
-  const existingDocs = scanDirectory(DOCS_DIR, ['.md']);
-  if (existingDocs.length === 0) {
-    return false;
-  }
-
-  if (hasGitTrackedSourceChanges()) {
-    return false;
-  }
-
-  console.log('✅ Git working tree is clean for documentation-related sources.');
-  console.log('   Assuming checked-in docs are up to date, skipping TypeDoc run.');
-  return true;
-}
-
-/**
- * Prime the docs cache using the currently checked-in documentation.
- * This lets future runs rely on hash comparisons even if git status is dirty.
- */
-function primeCacheFromExistingDocs() {
-  const currentDocHashes = getExistingDocHashes();
-  const currentSourceHashes = getSourceFileHashes();
-
-  const docHashesObj = {};
-  for (const [relativePath, hash] of currentDocHashes.entries()) {
-    docHashesObj[relativePath] = hash;
-  }
-
-  const sourceHashesObj = {};
-  for (const [relativePath, hash] of currentSourceHashes.entries()) {
-    sourceHashesObj[relativePath] = hash;
-  }
-
-  const cache = {
-    lastBuildTime: Date.now(),
-    sourceModTime: getLatestSourceModTime(),
-    docModTime: getLatestDocModTime(),
-    fileHashes: docHashesObj,
-    sourceFileHashes: sourceHashesObj
-  };
-
-  saveCache(cache);
-}
-
-/**
- * Get the most recent modification time of all source files
- */
-function getLatestSourceModTime() {
-  const ignorePatterns = [
-    /\.test\.(ts|tsx)$/,
-    /\.spec\.(ts|tsx)$/,
-    /__tests__/,
-    /\/test\//,
-    /\/tests\//
-  ];
-  
-  const sourceFiles = scanDirectory(SRC_DIR, ['.ts', '.tsx'], ignorePatterns);
-
-  let latestTime = 0;
-  for (const filePath of sourceFiles) {
-    try {
-      const stats = statSync(filePath);
-      if (stats.mtimeMs > latestTime) {
-        latestTime = stats.mtimeMs;
-      }
-    } catch (err) {
-      // File might have been deleted, skip it
-    }
-  }
-
-  return latestTime;
-}
-
-/**
- * Get the most recent modification time of generated docs
- */
-function getLatestDocModTime() {
-  if (!existsSync(DOCS_DIR)) {
-    return 0;
-  }
-
-  const docFiles = scanDirectory(DOCS_DIR, ['.md']);
-
-  if (docFiles.length === 0) {
-    return 0;
-  }
-
-  let latestTime = 0;
-  for (const filePath of docFiles) {
-    try {
-      const stats = statSync(filePath);
-      if (stats.mtimeMs > latestTime) {
-        latestTime = stats.mtimeMs;
-      }
-    } catch (err) {
-      // File might have been deleted, skip it
-    }
-  }
-
-  return latestTime;
-}
-
-/**
- * Get hashes of all source files
- */
-function getSourceFileHashes() {
-  const ignorePatterns = [
-    /\.test\.(ts|tsx)$/,
-    /\.spec\.(ts|tsx)$/,
-    /__tests__/,
-    /\/test\//,
-    /\/tests\//
-  ];
-  
-  const sourceFiles = scanDirectory(SRC_DIR, ['.ts', '.tsx'], ignorePatterns);
-  const hashes = new Map();
-  
-  for (const filePath of sourceFiles) {
-    try {
-      const content = readFileSync(filePath, 'utf-8');
-      const hash = createHash('md5').update(content).digest('hex');
-      const relativePath = relative(SRC_DIR, filePath);
-      hashes.set(relativePath, hash);
-    } catch (err) {
-      // Skip files we can't read
-    }
-  }
-  
-  return hashes;
-}
-
-/**
- * Check if source files have changed by comparing hashes
- */
-function hasSourceChanged(currentHashes, cachedHashes) {
-  if (!cachedHashes || Object.keys(cachedHashes).length === 0) {
-    return true; // No cache, assume changed
-  }
-  
-  // Check if any file changed
-  for (const [relativePath, currentHash] of currentHashes.entries()) {
-    const cachedHash = cachedHashes[relativePath];
-    if (cachedHash !== currentHash) {
-      return true;
-    }
-  }
-  
-  // Check if any files were added or removed
-  if (currentHashes.size !== Object.keys(cachedHashes).length) {
-    return true;
-  }
-  
-  return false;
-}
-
-/**
- * Check if doc file hashes match cached hashes
- */
-function hashesMatch(currentHashes, cachedHashes) {
-  if (!cachedHashes || Object.keys(cachedHashes).length === 0) {
-    return false; // No cache, assume mismatch
-  }
-  
-  if (currentHashes.size !== Object.keys(cachedHashes).length) {
-    return false; // Different number of files
-  }
-  
-  for (const [relativePath, currentHash] of currentHashes.entries()) {
-    const cachedHash = cachedHashes[relativePath];
-    if (cachedHash !== currentHash) {
-      return false;
-    }
-  }
-  
-  return true;
-}
-
-/**
- * Load the cache file
- */
-function loadCache() {
-  if (!existsSync(CACHE_FILE)) {
-    return {
-      lastBuildTime: 0,
-      sourceModTime: 0,
-      docModTime: 0,
-      fileHashes: {},
-      sourceFileHashes: {}
-    };
-  }
-
-  try {
-    const content = readFileSync(CACHE_FILE, 'utf-8');
-    const cache = JSON.parse(content);
-    // Ensure fileHashes exists for backward compatibility
-    if (!cache.fileHashes) {
-      cache.fileHashes = {};
-    }
-    if (!cache.sourceFileHashes) {
-      cache.sourceFileHashes = {};
-    }
-    return cache;
-  } catch (err) {
-    return {
-      lastBuildTime: 0,
-      sourceModTime: 0,
-      docModTime: 0,
-      fileHashes: {},
-      sourceFileHashes: {}
-    };
-  }
-}
-
-/**
- * Save the cache file
- */
-function saveCache(cache) {
-  // Ensure fileHashes is always present
-  if (!cache.fileHashes) {
-    cache.fileHashes = {};
-  }
-  if (!cache.sourceFileHashes) {
-    cache.sourceFileHashes = {};
-  }
-  writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2), 'utf-8');
-}
-
-/**
- * Aggressive pre-check: Should we run TypeDoc at all?
- * This checks source file hashes BEFORE running TypeDoc to avoid unnecessary runs
- */
-function shouldRunTypeDoc() {
-  const cache = loadCache();
-
-  // If no cache, must run
-  if (cache.lastBuildTime === 0) {
-    if (shouldSkipDueToCleanGitState()) {
-      console.log('⏭️  Skipping TypeDoc - no cache yet but git shows no relevant source changes.');
-      console.log('   Reason: Using checked-in docs since source tree matches HEAD');
-      console.log('   Action: Priming docs cache from checked-in files for future runs');
-      primeCacheFromExistingDocs();
-      return false;
-    }
-    console.log('📝 No cache found, running TypeDoc...');
-    console.log('   Reason: First run - no cache exists');
-    return true;
-  }
-  
-  // If docs don't exist, must run
-  if (!existsSync(DOCS_DIR)) {
-    console.log('📝 Documentation directory not found, running TypeDoc...');
-    console.log('   Reason: Documentation directory missing');
-    return true;
-  }
-  
-  // Check source file hashes - most reliable check
-  console.log('🔍 Checking source file hashes...');
-  const currentSourceHashes = getSourceFileHashes();
-  const cachedSourceHashes = cache.sourceFileHashes || {};
-  
-  console.log(`   Current source files: ${currentSourceHashes.size}`);
-  console.log(`   Cached source files: ${Object.keys(cachedSourceHashes).length}`);
-  
-  if (hasSourceChanged(currentSourceHashes, cachedSourceHashes)) {
-    // Find which files changed
-    const changedFiles = [];
-    for (const [relativePath, currentHash] of currentSourceHashes.entries()) {
-      const cachedHash = cachedSourceHashes[relativePath];
-      if (cachedHash !== currentHash) {
-        changedFiles.push(relativePath);
-      }
-    }
-    console.log('📝 Source files have changed (hash comparison), running TypeDoc...');
-    if (changedFiles.length > 0 && changedFiles.length <= 10) {
-      console.log(`   Changed files: ${changedFiles.slice(0, 5).join(', ')}${changedFiles.length > 5 ? ` ... and ${changedFiles.length - 5} more` : ''}`);
-    } else if (changedFiles.length > 10) {
-      console.log(`   Changed files: ${changedFiles.length} files modified`);
-    }
-    return true;
-  }
-  
-  // Source hasn't changed - check if docs match cache
-  console.log('🔍 Checking documentation file hashes...');
-  const currentDocHashes = getExistingDocHashes();
-  const cachedDocHashes = cache.fileHashes || {};
-  
-  console.log(`   Current doc files: ${currentDocHashes.size}`);
-  console.log(`   Cached doc files: ${Object.keys(cachedDocHashes).length}`);
-  
-  if (hashesMatch(currentDocHashes, cachedDocHashes)) {
-    console.log('✅ Source unchanged and docs match cache - skipping TypeDoc entirely');
-    console.log('   Reason: No source changes detected and documentation is up to date');
-    return false; // Skip TypeDoc!
-  }
-
-  // Docs don't match cache but source unchanged - refresh cache snapshot instead of regenerating
-  const mismatchedFiles = [];
-  for (const [relativePath, currentHash] of currentDocHashes.entries()) {
-    const cachedHash = cachedDocHashes[relativePath];
-    if (cachedHash !== currentHash) {
-      mismatchedFiles.push(relativePath);
-    }
-  }
-  console.log('⚠️  Source unchanged but docs don\'t match cache - refreshing cache from disk');
-  console.log(`   Mismatched files: ${mismatchedFiles.length} files don't match cache`);
-  if (mismatchedFiles.length <= 5) {
-    console.log(`   Files: ${mismatchedFiles.join(', ')}`);
-  }
-  primeCacheFromExistingDocs();
-  return false;
-}
-
-/**
- * Check if any source files have changed since last build
- */
-function needsRebuild() {
-  const cache = loadCache();
-  const currentSourceModTime = getLatestSourceModTime();
-  const currentDocModTime = getLatestDocModTime();
-
-  // If docs don't exist, we need to build
-  if (!existsSync(DOCS_DIR) || currentDocModTime === 0) {
-    console.log('📝 Documentation directory not found or empty, building...');
-    return true;
-  }
-
-  // Check if typedoc.json has changed
-  const typedocConfigPath = join(PACKAGE_ROOT, 'typedoc.json');
-  if (existsSync(typedocConfigPath)) {
-    const configStats = statSync(typedocConfigPath);
-    if (cache.lastBuildTime > 0 && configStats.mtimeMs > cache.lastBuildTime) {
-      console.log('📝 TypeDoc configuration has changed, rebuilding...');
-      return true;
-    }
-    if (currentDocModTime > 0 && configStats.mtimeMs > currentDocModTime) {
-      console.log('📝 TypeDoc configuration is newer than docs, rebuilding...');
-      return true;
-    }
-  }
-
-  // Check entry point file (what TypeDoc actually uses)
-  const entryPointPath = join(PACKAGE_ROOT, 'src', 'index.ts');
-  if (existsSync(entryPointPath)) {
-    const entryStats = statSync(entryPointPath);
-    if (cache.lastBuildTime > 0 && entryStats.mtimeMs > cache.lastBuildTime) {
-      console.log('📝 Entry point file has changed, rebuilding...');
-      return true;
-    }
-    if (currentDocModTime > 0 && entryStats.mtimeMs > currentDocModTime) {
-      console.log('📝 Entry point file is newer than docs, rebuilding...');
-      return true;
-    }
-  }
-
-  // If source files are newer than docs, we need to rebuild
-  if (currentSourceModTime > currentDocModTime) {
-    console.log('📝 Source files are newer than documentation, rebuilding...');
-    return true;
-  }
-
-  // If cache indicates a rebuild is needed (e.g., after a clean)
-  // Only check cache if we have a valid cache entry
-  if (cache.lastBuildTime > 0) {
-    // Check if source files have changed since last build
-    const sourceChanged = currentSourceModTime > cache.sourceModTime;
-    
-    // Check if docs are newer than the last build time (meaning they were just built)
-    const docsJustBuilt = currentDocModTime > cache.lastBuildTime - 1000; // 1 second tolerance
-    
-    if (sourceChanged) {
-      console.log('📝 Source files have changed since last build, rebuilding...');
-      return true;
-    }
-    
-    // If docs were just built (within last second), skip rebuild to avoid double-building
-    if (docsJustBuilt) {
-      console.log('✅ Documentation was just built, skipping rebuild to avoid double-build');
-      return false;
-    }
-    
-    // Check file-level hashes if available
-    if (cache.fileHashes && Object.keys(cache.fileHashes).length > 0) {
-      const currentHashes = getExistingDocHashes();
-      let filesChanged = false;
-      
-      // Check if any file hashes changed
-      for (const [relativePath, cachedHash] of Object.entries(cache.fileHashes)) {
-        const currentHash = currentHashes.get(relativePath);
-        if (currentHash !== cachedHash) {
-          filesChanged = true;
-          break;
-        }
-      }
-      
-      // Check if any new files were added
-      if (!filesChanged && currentHashes.size !== Object.keys(cache.fileHashes).length) {
-        filesChanged = true;
-      }
-      
-      if (!filesChanged && !sourceChanged) {
-        console.log('✅ Documentation is up to date (file hashes match cache), skipping rebuild');
-        return false;
-      }
-    }
-    
-    // If cache exists and source hasn't changed, we're good
-    console.log('✅ Documentation is up to date (cache valid), skipping rebuild');
-    return false;
-  }
-
-  // No cache exists - compare source vs docs directly
-  if (currentSourceModTime <= currentDocModTime) {
-    console.log('✅ Documentation is up to date, skipping rebuild');
-    return false;
-  }
-
-  // Fallback: rebuild if we can't determine
-  console.log('📝 Unable to determine if rebuild needed, rebuilding to be safe...');
-  return true;
-}
-
-/**
- * Get current package version from package.json
- */
-function getPackageVersion() {
-  try {
-    const packageJsonPath = join(PACKAGE_ROOT, 'package.json');
-    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
-    return packageJson.version || '';
-  } catch (err) {
-    return '';
-  }
-}
-
-/**
- * Sort markdown list items for deterministic comparison
- */
-function sortMarkdownListItems(text) {
-  // Match markdown list sections (lines starting with - or *)
-  const lines = text.split('\n');
-  const sortedLines = [];
-  let currentList = [];
-  let inList = false;
-  
-  for (const line of lines) {
-    const isListItem = /^\s*[-*]\s+/.test(line);
-    
-    if (isListItem) {
-      if (!inList && currentList.length > 0) {
-        // Flush previous non-list content
-        sortedLines.push(...currentList);
-        currentList = [];
-      }
-      inList = true;
-      currentList.push(line);
-    } else {
-      if (inList && currentList.length > 0) {
-        // Sort and flush list
-        currentList.sort();
-        sortedLines.push(...currentList);
-        currentList = [];
-      }
-      inList = false;
-      currentList.push(line);
-    }
-  }
-  
-  // Flush remaining content
-  if (currentList.length > 0) {
-    if (inList) {
-      currentList.sort();
-    }
-    sortedLines.push(...currentList);
-  }
-  
-  return sortedLines.join('\n');
-}
-
-/**
- * Normalize markdown link references for deterministic comparison
- */
-function normalizeMarkdownLinks(text) {
-  // Extract and sort link references [id]: url "title"
-  const linkRefPattern = /^\[([^\]]+)\]:\s*(.+)$/gm;
-  const links = [];
-  let match;
-  
-  while ((match = linkRefPattern.exec(text)) !== null) {
-    links.push(match[0]);
-  }
-  
-  if (links.length > 0) {
-    // Sort links by ID
-    links.sort();
-    // Replace all link references with sorted version
-    let normalized = text.replace(linkRefPattern, 'LINKREF');
-    // Append sorted links at the end
-    normalized = normalized.replace(/LINKREF/g, () => links.shift() || 'LINKREF');
-    return normalized;
-  }
-  
-  return text;
-}
-
-/**
- * Normalize "Defined in" links emitted by TypeDoc so that branch/remote differences
- * don't cause hash mismatches between environments.
- */
-function normalizeDefinedInLinks(text) {
-  const definedInPattern = /\[(packages\/core\/[^\]]+?:\d+)\]\((https?:\/\/[^(]+?#L\d+)\)/g;
-  return text.replace(definedInPattern, (_match, displayText) => displayText);
-}
-
-/**
- * Normalize content for comparison (remove trailing whitespace, normalize line endings, version numbers, timestamps)
- */
-function normalizeContent(content) {
-  let normalized = content
-    .replace(/\r\n/g, '\n')  // Normalize line endings
-    .replace(/\r/g, '\n')     // Handle old Mac line endings
-    .replace(/[ \t]+$/gm, '')  // Remove trailing spaces/tabs
-    .replace(/\n{3,}/g, '\n\n'); // Normalize multiple blank lines
-  
-  // Remove version numbers from TypeDoc-generated content
-  // TypeDoc includes version like "@jmruthers/pace-core@0.5.158"
-  // We normalize this to "@jmruthers/pace-core@VERSION" so version changes don't trigger updates
-  // This allows docs to remain unchanged when only the version number changes
-  normalized = normalized.replace(/@jmruthers\/pace-core@[\d.]+/g, '@jmruthers/pace-core@VERSION');
-  normalized = normalized.replace(/version\s+[\d.]+/gi, 'version VERSION');
-  // Also handle any other version patterns that might appear
-  normalized = normalized.replace(/\b[\d]+\.[\d]+\.[\d]+/g, 'VERSION');
-  
-  // Remove timestamps and dates that might be generated dynamically
-  normalized = normalized.replace(/\d{4}-\d{2}-\d{2}/g, 'DATE'); // YYYY-MM-DD
-  normalized = normalized.replace(/\d{2}\/\d{2}\/\d{4}/g, 'DATE'); // MM/DD/YYYY
-  normalized = normalized.replace(/\d{2}:\d{2}:\d{2}/g, 'TIME'); // HH:MM:SS
-  normalized = normalized.replace(/Generated\s+on[^\n]*/gi, 'Generated on DATE');
-  normalized = normalized.replace(/Last\s+updated[^\n]*/gi, 'Last updated DATE');
-  normalized = normalized.replace(/Updated\s+[^\n]*/gi, 'Updated DATE');
-  
-  // Remove any git commit hashes or SHAs that might appear
-  normalized = normalized.replace(/\b[0-9a-f]{7,40}\b/gi, 'HASH');
-  
-  // Remove any ISO timestamps
-  normalized = normalized.replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}[.\d]*Z?/g, 'TIMESTAMP');
-  
-  // Normalize whitespace more aggressively
-  normalized = normalized.replace(/[ \t]+/g, ' '); // Multiple spaces/tabs to single space
-  normalized = normalized.replace(/ \n/g, '\n'); // Remove trailing spaces before newlines
-  
-  // Sort markdown lists for deterministic comparison
-  normalized = sortMarkdownListItems(normalized);
-
-  // Normalize markdown link references
-  normalized = normalizeMarkdownLinks(normalized);
-
-  // Normalize "Defined in" GitHub links
-  normalized = normalizeDefinedInLinks(normalized);
-
-  return normalized.trim();
-}
-
-/**
- * Get file content hash for comparison
- */
-function getFileHash(filePath) {
-  if (!existsSync(filePath)) {
-    return null;
-  }
-  try {
-    const content = readFileSync(filePath, 'utf-8');
-    const normalized = normalizeContent(content);
-    return createHash('md5').update(normalized).digest('hex');
-  } catch (err) {
-    return null;
-  }
-}
-
-/**
- * Get hashes of all existing doc files
- */
-function getExistingDocHashes() {
-  const hashes = new Map();
-  if (!existsSync(DOCS_DIR)) {
-    return hashes;
-  }
-  
-  const docFiles = scanDirectory(DOCS_DIR, ['.md']);
-  for (const filePath of docFiles) {
-    const relativePath = relative(DOCS_DIR, filePath);
-    const hash = getFileHash(filePath);
-    if (hash) {
-      hashes.set(relativePath, hash);
-    }
-  }
-  
-  return hashes;
-}
-
-/**
- * Get git status of docs directory
- */
-function getGitStatus(directory) {
-  try {
-    const result = execSync(`git status --porcelain ${directory}`, {
-      cwd: PACKAGE_ROOT,
-      encoding: 'utf-8',
-      stdio: 'pipe'
-    });
-    return result.trim().split('\n').filter(line => line.trim());
-  } catch (err) {
-    // Not a git repo or git not available
-    return [];
-  }
-}
-
-/**
- * Run TypeDoc to generate documentation, but only update files that actually changed
- */
-function runTypeDoc(dryRun = false) {
-  if (dryRun) {
-    console.log('🔍 DRY-RUN MODE: Showing what would be updated without actually updating');
-  }
-  console.log('🔨 Running TypeDoc to generate documentation...');
-  console.log(`📝 Incremental build script v2.0 - Only updating files with actual content changes`);
-  
-  // Get hashes of existing files before generation
-  // Version numbers are normalized out during hash calculation
-  const existingHashes = getExistingDocHashes();
-  const totalExistingFiles = existingHashes.size;
-  console.log(`📋 Found ${totalExistingFiles} existing documentation files to compare against`);
-  
-  // Create temp directory for new docs
-  const tempDocsDir = join(PACKAGE_ROOT, '.docs-temp');
-  
-  try {
-    // Backup current docs if they exist
-    const backupDir = join(PACKAGE_ROOT, '.docs-backup');
-    if (existsSync(DOCS_DIR)) {
-      if (existsSync(backupDir)) {
-        rmSync(backupDir, { recursive: true, force: true });
-      }
-      cpSync(DOCS_DIR, backupDir, { recursive: true });
-    }
-    
-    // Run TypeDoc to temp directory first
-    const tempTypedocConfig = {
-      ...JSON.parse(readFileSync(join(PACKAGE_ROOT, 'typedoc.json'), 'utf-8')),
-      out: '.docs-temp'
-    };
-    const tempConfigPath = join(PACKAGE_ROOT, '.typedoc-temp.json');
-    writeFileSync(tempConfigPath, JSON.stringify(tempTypedocConfig, null, 2));
-    
-    execSync(`npx typedoc --options ${tempConfigPath}`, {
-      cwd: PACKAGE_ROOT,
-      stdio: 'inherit'
-    });
-    
-    // Compare and only copy changed files
-    let updatedCount = 0;
-    let unchangedCount = 0;
-    
-    if (existsSync(tempDocsDir)) {
-      const newDocFiles = scanDirectory(tempDocsDir, ['.md']);
-      
-      // Ensure docs directory exists
-      if (!existsSync(DOCS_DIR)) {
-        mkdirSync(DOCS_DIR, { recursive: true });
-      }
-      
-      const updatedFiles = [];
-      
-      for (const newFilePath of newDocFiles) {
-        const relativePath = relative(tempDocsDir, newFilePath);
-        const targetPath = join(DOCS_DIR, relativePath);
-        const newHash = getFileHash(newFilePath);
-        const oldHash = existingHashes.get(relativePath);
-        
-        // CRITICAL: Only copy if normalized content hash changed
-        // If hash matches, do NOT write the file at all to prevent git from seeing it as modified
-        if (newHash !== oldHash) {
-          // Double-check: read existing file and compare normalized content
-          if (existsSync(targetPath)) {
-            const existingContent = readFileSync(targetPath, 'utf-8');
-            const existingNormalized = normalizeContent(existingContent);
-            const newContent = readFileSync(newFilePath, 'utf-8');
-            const newNormalized = normalizeContent(newContent);
-            
-            // If normalized content is identical, skip write even if hash differs
-            // (this handles edge cases where hash calculation might differ)
-            if (existingNormalized === newNormalized) {
-              unchangedCount++;
-              continue;
-            }
-          }
-          
-          // Ensure directory exists
-          const targetDir = dirname(targetPath);
-          if (!existsSync(targetDir)) {
-            mkdirSync(targetDir, { recursive: true });
-          }
-          
-          // Copy file only if content actually changed
-          if (!dryRun) {
-            const content = readFileSync(newFilePath, 'utf-8');
-            writeFileSync(targetPath, content, 'utf-8');
-          }
-          
-          updatedCount++;
-          updatedFiles.push(relativePath);
-        } else {
-          // Content is identical - DO NOT TOUCH THE FILE AT ALL
-          // This prevents git from seeing it as modified
-          // We don't restore timestamps or do anything - just leave it alone
-          unchangedCount++;
-        }
-      }
-      
-      // Log which files were updated if any (only if debug mode or significant changes)
-      if (updatedCount > 0) {
-        if (process.env.DEBUG_DOCS || updatedCount <= 10) {
-          console.log(`\n📝 Files updated (${updatedCount}):`);
-          updatedFiles.slice(0, 10).forEach(file => console.log(`   - ${file}`));
-          if (updatedFiles.length > 10) {
-            console.log(`   ... and ${updatedFiles.length - 10} more`);
-          }
-        } else {
-          console.log(`\n📝 ${updatedCount} files were updated (use DEBUG_DOCS=1 to see list)`);
-        }
-      }
-      
-      // Handle deleted files - files that existed before but don't exist in new generation
-      // (TypeDoc might remove some files if exports changed)
-      for (const [relativePath, oldHash] of existingHashes.entries()) {
-        const targetPath = join(DOCS_DIR, relativePath);
-        const newFilePath = join(tempDocsDir, relativePath);
-        if (!existsSync(newFilePath) && existsSync(targetPath)) {
-          // File was deleted by TypeDoc - remove it
-          rmSync(targetPath, { force: true });
-          console.log(`   Deleted: ${relativePath}`);
-        }
-      }
-      
-      // Clean up temp files
-      rmSync(tempDocsDir, { recursive: true, force: true });
-      if (existsSync(backupDir)) {
-        rmSync(backupDir, { recursive: true, force: true });
-      }
-      if (existsSync(tempConfigPath)) {
-        rmSync(tempConfigPath, { force: true });
-      }
-      
-      console.log(`📊 Documentation update summary:`);
-      console.log(`   Updated: ${updatedCount} files`);
-      console.log(`   Unchanged: ${unchangedCount} files`);
-      
-      // Verification step: Check if suspicious number of files changed
-      if (updatedCount > 50 && updatedCount === newDocFiles.length) {
-        console.log(`\n⚠️  WARNING: All ${updatedCount} files appear to have changed!`);
-        console.log(`   This might indicate TypeDoc is generating non-deterministic content.`);
-        console.log(`   Check if source files actually changed, or if TypeDoc config changed.`);
-        
-        // Additional verification: Check if source files actually changed
-        const cache = loadCache();
-        const currentSourceModTime = getLatestSourceModTime();
-        if (cache.lastBuildTime > 0 && currentSourceModTime <= cache.sourceModTime) {
-          console.log(`\n🔍 VERIFICATION: Source files have NOT changed since last build.`);
-          console.log(`   This suggests TypeDoc may be generating non-deterministic output.`);
-          console.log(`   Files were updated but source is unchanged - this is unexpected.`);
-        }
-      }
-      
-      // Verification: If many files changed but normalized content matches, warn
-      if (updatedCount > 0 && unchangedCount > 0) {
-        const changeRatio = updatedCount / (updatedCount + unchangedCount);
-        if (changeRatio > 0.8) {
-          console.log(`\n⚠️  WARNING: ${Math.round(changeRatio * 100)}% of files were updated.`);
-          console.log(`   This is unusually high. Verify source files actually changed.`);
-        }
-      }
-      
-      // Get final file hashes after update
-      const finalHashes = getExistingDocHashes();
-      const fileHashesObj = {};
-      for (const [relativePath, hash] of finalHashes.entries()) {
-        fileHashesObj[relativePath] = hash;
-      }
-      
-      return { success: true, fileHashes: fileHashesObj };
-    }
-    
-    return { success: true, fileHashes: {} };
-  } catch (error) {
-    // Clean up on error
-    if (existsSync(tempDocsDir)) {
-      rmSync(tempDocsDir, { recursive: true, force: true });
-    }
-    const tempConfigPath = join(PACKAGE_ROOT, '.typedoc-temp.json');
-    if (existsSync(tempConfigPath)) {
-      rmSync(tempConfigPath, { force: true });
-    }
-    console.error('❌ TypeDoc failed:', error.message);
-    return { success: false, fileHashes: {} };
-  }
-}
+const IGNORE_PATTERNS = [
+  /\.test\.(ts|tsx)$/,
+  /\.spec\.(ts|tsx)$/,
+  /__tests__/,
+  /\/test\//,
+  /\/tests\//
+];
 
 /**
  * Main function
@@ -930,11 +49,41 @@ function main() {
   const dryRun = process.argv.includes('--dry-run');
   const verifyGit = process.argv.includes('--verify-git');
 
+  // Create configuration object for modules
+  const config = {
+    packageRoot: PACKAGE_ROOT,
+    repoRoot: REPO_ROOT,
+    srcDir: SRC_DIR,
+    docsDir: DOCS_DIR,
+    cacheFile: CACHE_FILE,
+    docsRelevantPaths: DOCS_RELEVANT_PATHS,
+    ignorePatterns: IGNORE_PATTERNS,
+    getLatestSourceModTime,
+    getLatestDocModTime,
+    getSourceFileHashes: (srcDir) => getSourceFileHashes(srcDir, IGNORE_PATTERNS),
+    getExistingDocHashes,
+    hasSourceChanged,
+    hashesMatch,
+    shouldSkipDueToCleanGitState,
+    primeCacheFromExistingDocs: (config) => primeCacheFromExistingDocs({
+      cacheFile: config.cacheFile,
+      docsDir: config.docsDir,
+      srcDir: config.srcDir,
+      getLatestSourceModTime: config.getLatestSourceModTime,
+      getLatestDocModTime: config.getLatestDocModTime,
+      getExistingDocHashes: config.getExistingDocHashes,
+      getSourceFileHashes: config.getSourceFileHashes
+    })
+  };
+
   if (forceRebuild) {
     console.log('🔄 Force rebuild requested, regenerating all documentation...');
-    const result = runTypeDoc(dryRun);
+    const result = runTypeDoc({
+      ...config,
+      dryRun
+    });
     if (result.success) {
-      const currentSourceHashes = getSourceFileHashes();
+      const currentSourceHashes = getSourceFileHashes(SRC_DIR, IGNORE_PATTERNS);
       const sourceHashesObj = {};
       for (const [relativePath, hash] of currentSourceHashes.entries()) {
         sourceHashesObj[relativePath] = hash;
@@ -942,13 +91,13 @@ function main() {
       
       const cache = {
         lastBuildTime: Date.now(),
-        sourceModTime: getLatestSourceModTime(),
-        docModTime: getLatestDocModTime(),
+        sourceModTime: getLatestSourceModTime(SRC_DIR, IGNORE_PATTERNS),
+        docModTime: getLatestDocModTime(DOCS_DIR),
         fileHashes: result.fileHashes || {},
         sourceFileHashes: sourceHashesObj
       };
       if (!dryRun) {
-        saveCache(cache);
+        saveCache(CACHE_FILE, cache);
       }
       console.log('✅ Documentation generation completed');
     }
@@ -956,8 +105,16 @@ function main() {
     return;
   }
 
+  // Load cache for decision making
+  const cache = loadCache(CACHE_FILE);
+
   // Aggressive pre-check: Skip TypeDoc entirely if source unchanged
-  if (!shouldRunTypeDoc()) {
+  const shouldRunConfig = {
+    ...config,
+    cache
+  };
+  
+  if (!shouldRunTypeDoc(shouldRunConfig)) {
     console.log('⏭️  Skipping TypeDoc - source files unchanged and docs are up to date');
     process.exit(0);
     return;
@@ -966,14 +123,22 @@ function main() {
   // Get git status before if verifying
   let gitStatusBefore = [];
   if (verifyGit) {
-    gitStatusBefore = getGitStatus(DOCS_DIR);
+    gitStatusBefore = getGitStatus(PACKAGE_ROOT, DOCS_DIR);
     console.log(`📋 Git status before: ${gitStatusBefore.length} modified files`);
   }
 
-  if (needsRebuild()) {
-    const result = runTypeDoc(dryRun);
+  const needsRebuildConfig = {
+    ...config,
+    cache
+  };
+
+  if (needsRebuild(needsRebuildConfig)) {
+    const result = runTypeDoc({
+      ...config,
+      dryRun
+    });
     if (result.success) {
-      const currentSourceHashes = getSourceFileHashes();
+      const currentSourceHashes = getSourceFileHashes(SRC_DIR, IGNORE_PATTERNS);
       const sourceHashesObj = {};
       for (const [relativePath, hash] of currentSourceHashes.entries()) {
         sourceHashesObj[relativePath] = hash;
@@ -981,18 +146,18 @@ function main() {
       
       const cache = {
         lastBuildTime: Date.now(),
-        sourceModTime: getLatestSourceModTime(),
-        docModTime: getLatestDocModTime(),
+        sourceModTime: getLatestSourceModTime(SRC_DIR, IGNORE_PATTERNS),
+        docModTime: getLatestDocModTime(DOCS_DIR),
         fileHashes: result.fileHashes || {},
         sourceFileHashes: sourceHashesObj
       };
       if (!dryRun) {
-        saveCache(cache);
+        saveCache(CACHE_FILE, cache);
       }
       
       // Verify git status after if requested
       if (verifyGit && !dryRun) {
-        const gitStatusAfter = getGitStatus(DOCS_DIR);
+        const gitStatusAfter = getGitStatus(PACKAGE_ROOT, DOCS_DIR);
         const newChanges = gitStatusAfter.filter(file => !gitStatusBefore.includes(file));
         if (newChanges.length > 0 && result.updatedCount === 0) {
           console.log(`\n⚠️  WARNING: Git shows ${newChanges.length} files changed but script reported 0 updates`);
@@ -1012,4 +177,3 @@ function main() {
 }
 
 main();
-