@jmruthers/pace-core 0.5.184 → 0.5.186

package/scripts/build-docs-incremental.js

@@ -0,0 +1,1015 @@
+#!/usr/bin/env node
+
+/**
+ * Incremental TypeDoc Build Script
+ * 
+ * This script only regenerates documentation when source files have changed,
+ * 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 { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const PACKAGE_ROOT = join(__dirname, '..');
+const REPO_ROOT = join(PACKAGE_ROOT, '..', '..');
+const SRC_DIR = join(PACKAGE_ROOT, 'src');
+const DOCS_DIR = join(PACKAGE_ROOT, 'docs', 'api');
+const CACHE_FILE = join(PACKAGE_ROOT, '.docs-cache.json');
+const DOCS_RELEVANT_PATHS = [
+  'packages/core/src',
+  'packages/core/examples',
+  '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: {} };
+  }
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const forceRebuild = process.argv.includes('--force');
+  const dryRun = process.argv.includes('--dry-run');
+  const verifyGit = process.argv.includes('--verify-git');
+
+  if (forceRebuild) {
+    console.log('🔄 Force rebuild requested, regenerating all documentation...');
+    const result = runTypeDoc(dryRun);
+    if (result.success) {
+      const currentSourceHashes = getSourceFileHashes();
+      const sourceHashesObj = {};
+      for (const [relativePath, hash] of currentSourceHashes.entries()) {
+        sourceHashesObj[relativePath] = hash;
+      }
+      
+      const cache = {
+        lastBuildTime: Date.now(),
+        sourceModTime: getLatestSourceModTime(),
+        docModTime: getLatestDocModTime(),
+        fileHashes: result.fileHashes || {},
+        sourceFileHashes: sourceHashesObj
+      };
+      if (!dryRun) {
+        saveCache(cache);
+      }
+      console.log('✅ Documentation generation completed');
+    }
+    process.exit(result.success ? 0 : 1);
+    return;
+  }
+
+  // Aggressive pre-check: Skip TypeDoc entirely if source unchanged
+  if (!shouldRunTypeDoc()) {
+    console.log('⏭️  Skipping TypeDoc - source files unchanged and docs are up to date');
+    process.exit(0);
+    return;
+  }
+
+  // Get git status before if verifying
+  let gitStatusBefore = [];
+  if (verifyGit) {
+    gitStatusBefore = getGitStatus(DOCS_DIR);
+    console.log(`📋 Git status before: ${gitStatusBefore.length} modified files`);
+  }
+
+  if (needsRebuild()) {
+    const result = runTypeDoc(dryRun);
+    if (result.success) {
+      const currentSourceHashes = getSourceFileHashes();
+      const sourceHashesObj = {};
+      for (const [relativePath, hash] of currentSourceHashes.entries()) {
+        sourceHashesObj[relativePath] = hash;
+      }
+      
+      const cache = {
+        lastBuildTime: Date.now(),
+        sourceModTime: getLatestSourceModTime(),
+        docModTime: getLatestDocModTime(),
+        fileHashes: result.fileHashes || {},
+        sourceFileHashes: sourceHashesObj
+      };
+      if (!dryRun) {
+        saveCache(cache);
+      }
+      
+      // Verify git status after if requested
+      if (verifyGit && !dryRun) {
+        const gitStatusAfter = getGitStatus(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`);
+          console.log(`   This suggests files were modified unnecessarily`);
+        } else if (newChanges.length !== result.updatedCount) {
+          console.log(`\n📊 Git verification: ${newChanges.length} files changed in git, ${result.updatedCount} reported by script`);
+        }
+      }
+      
+      console.log('✅ Documentation generation completed');
+    }
+    process.exit(result.success ? 0 : 1);
+  } else {
+    console.log('⏭️  Skipping documentation generation (no changes detected)');
+    process.exit(0);
+  }
+}
+
+main();
+