@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/build-docs/hash-utils.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * Hash utilities for documentation build
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { relative } from 'path';
+import { createHash } from 'crypto';
+import { scanDirectory } from './file-utils.js';
+import { normalizeContent } from './content-normalization.js';
+
+/**
+ * Get hashes of all source files
+ */
+export function getSourceFileHashes(srcDir, ignorePatterns = []) {
+  const sourceFiles = scanDirectory(srcDir, ['.ts', '.tsx'], ignorePatterns, srcDir);
+  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(srcDir, filePath);
+      hashes.set(relativePath, hash);
+    } catch (err) {
+      // Skip files we can't read
+    }
+  }
+  
+  return hashes;
+}
+
+/**
+ * Check if source files have changed by comparing hashes
+ */
+export 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
+ */
+export 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;
+}
+
+/**
+ * Get file content hash for comparison
+ */
+export 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
+ */
+export function getExistingDocHashes(docsDir) {
+  const hashes = new Map();
+  if (!existsSync(docsDir)) {
+    return hashes;
+  }
+  
+  const docFiles = scanDirectory(docsDir, ['.md']);
+  for (const filePath of docFiles) {
+    const relativePath = relative(docsDir, filePath);
+    const hash = getFileHash(filePath);
+    if (hash) {
+      hashes.set(relativePath, hash);
+    }
+  }
+  
+  return hashes;
+}
+

package/scripts/build-docs/typedoc-runner.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+/**
+ * TypeDoc execution and file update logic
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, cpSync } from 'fs';
+import { join, dirname, relative } from 'path';
+import { scanDirectory } from './file-utils.js';
+import { getFileHash, getExistingDocHashes } from './hash-utils.js';
+import { normalizeContent } from './content-normalization.js';
+import { loadCache } from './cache-utils.js';
+import { getLatestSourceModTime } from './file-utils.js';
+
+/**
+ * Run TypeDoc to generate documentation, but only update files that actually changed
+ */
+export function runTypeDoc(config) {
+  const {
+    dryRun = false,
+    packageRoot,
+    docsDir,
+    cacheFile,
+    srcDir
+  } = config;
+
+  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(docsDir);
+  const totalExistingFiles = existingHashes.size;
+  console.log(`📋 Found ${totalExistingFiles} existing documentation files to compare against`);
+  
+  // Create temp directory for new docs
+  const tempDocsDir = join(packageRoot, '.docs-temp');
+  
+  try {
+    // Backup current docs if they exist
+    const backupDir = join(packageRoot, '.docs-backup');
+    if (existsSync(docsDir)) {
+      if (existsSync(backupDir)) {
+        rmSync(backupDir, { recursive: true, force: true });
+      }
+      cpSync(docsDir, backupDir, { recursive: true });
+    }
+    
+    // Run TypeDoc to temp directory first
+    const tempTypedocConfig = {
+      ...JSON.parse(readFileSync(join(packageRoot, 'typedoc.json'), 'utf-8')),
+      out: '.docs-temp'
+    };
+    const tempConfigPath = join(packageRoot, '.typedoc-temp.json');
+    writeFileSync(tempConfigPath, JSON.stringify(tempTypedocConfig, null, 2));
+    
+    execSync(`npx typedoc --options ${tempConfigPath}`, {
+      cwd: packageRoot,
+      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(docsDir)) {
+        mkdirSync(docsDir, { recursive: true });
+      }
+      
+      const updatedFiles = [];
+      
+      for (const newFilePath of newDocFiles) {
+        const relativePath = relative(tempDocsDir, newFilePath);
+        const targetPath = join(docsDir, 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(docsDir, 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(cacheFile);
+        const ignorePatterns = [
+          /\.test\.(ts|tsx)$/,
+          /\.spec\.(ts|tsx)$/,
+          /__tests__/,
+          /\/test\//,
+          /\/tests\//
+        ];
+        const currentSourceModTime = getLatestSourceModTime(srcDir, ignorePatterns);
+        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(docsDir);
+      const fileHashesObj = {};
+      for (const [relativePath, hash] of finalHashes.entries()) {
+        fileHashesObj[relativePath] = hash;
+      }
+      
+      return { success: true, fileHashes: fileHashesObj, updatedCount };
+    }
+    
+    return { success: true, fileHashes: {}, updatedCount: 0 };
+  } catch (error) {
+    // Clean up on error
+    if (existsSync(tempDocsDir)) {
+      rmSync(tempDocsDir, { recursive: true, force: true });
+    }
+    const tempConfigPath = join(packageRoot, '.typedoc-temp.json');
+    if (existsSync(tempConfigPath)) {
+      rmSync(tempConfigPath, { force: true });
+    }
+    console.error('❌ TypeDoc failed:', error.message);
+    return { success: false, fileHashes: {}, updatedCount: 0 };
+  }
+}
+