@jmruthers/pace-core 0.5.193 → 0.6.2

package/scripts/build-docs/build-decision.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+/**
+ * Build decision logic for documentation generation
+ */
+
+import { existsSync, statSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Aggressive pre-check: Should we run TypeDoc at all?
+ * This checks source file hashes BEFORE running TypeDoc to avoid unnecessary runs
+ */
+export function shouldRunTypeDoc(config) {
+  const {
+    cache,
+    docsDir,
+    repoRoot,
+    docsRelevantPaths,
+    srcDir,
+    shouldSkipDueToCleanGitState,
+    primeCacheFromExistingDocs,
+    getSourceFileHashes,
+    hasSourceChanged,
+    getExistingDocHashes,
+    hashesMatch
+  } = config;
+
+  // If no cache, must run
+  if (cache.lastBuildTime === 0) {
+    if (shouldSkipDueToCleanGitState(repoRoot, docsDir, docsRelevantPaths)) {
+      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({
+        cacheFile: config.cacheFile,
+        docsDir: config.docsDir,
+        srcDir: config.srcDir,
+        getLatestSourceModTime: config.getLatestSourceModTime,
+        getLatestDocModTime: config.getLatestDocModTime,
+        getExistingDocHashes: config.getExistingDocHashes,
+        getSourceFileHashes: config.getSourceFileHashes
+      });
+      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(docsDir)) {
+    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(srcDir);
+  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(docsDir);
+  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(config);
+  return false;
+}
+
+/**
+ * Check if any source files have changed since last build
+ */
+export function needsRebuild(config) {
+  const {
+    cache,
+    packageRoot,
+    docsDir,
+    srcDir,
+    getLatestSourceModTime,
+    getLatestDocModTime,
+    getExistingDocHashes
+  } = config;
+
+  const ignorePatterns = [
+    /\.test\.(ts|tsx)$/,
+    /\.spec\.(ts|tsx)$/,
+    /__tests__/,
+    /\/test\//,
+    /\/tests\//
+  ];
+
+  const currentSourceModTime = getLatestSourceModTime(srcDir, ignorePatterns);
+  const currentDocModTime = getLatestDocModTime(docsDir);
+
+  // If docs don't exist, we need to build
+  if (!existsSync(docsDir) || currentDocModTime === 0) {
+    console.log('📝 Documentation directory not found or empty, building...');
+    return true;
+  }
+
+  // Check if typedoc.json has changed
+  const typedocConfigPath = join(packageRoot, '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(packageRoot, '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(docsDir);
+      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;
+}
+

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * Cache utilities for documentation build
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+
+/**
+ * Load the cache file
+ */
+export function loadCache(cacheFile) {
+  if (!existsSync(cacheFile)) {
+    return {
+      lastBuildTime: 0,
+      sourceModTime: 0,
+      docModTime: 0,
+      fileHashes: {},
+      sourceFileHashes: {}
+    };
+  }
+
+  try {
+    const content = readFileSync(cacheFile, '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
+ */
+export function saveCache(cacheFile, cache) {
+  // Ensure fileHashes is always present
+  if (!cache.fileHashes) {
+    cache.fileHashes = {};
+  }
+  if (!cache.sourceFileHashes) {
+    cache.sourceFileHashes = {};
+  }
+  writeFileSync(cacheFile, JSON.stringify(cache, null, 2), 'utf-8');
+}
+
+/**
+ * Prime the docs cache using the currently checked-in documentation.
+ * This lets future runs rely on hash comparisons even if git status is dirty.
+ */
+export function primeCacheFromExistingDocs(config) {
+  const {
+    cacheFile,
+    docsDir,
+    srcDir,
+    getLatestSourceModTime,
+    getLatestDocModTime,
+    getExistingDocHashes,
+    getSourceFileHashes
+  } = config;
+
+  const currentDocHashes = getExistingDocHashes(docsDir);
+  const currentSourceHashes = getSourceFileHashes(srcDir);
+
+  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 ignorePatterns = [
+    /\.test\.(ts|tsx)$/,
+    /\.spec\.(ts|tsx)$/,
+    /__tests__/,
+    /\/test\//,
+    /\/tests\//
+  ];
+
+  const cache = {
+    lastBuildTime: Date.now(),
+    sourceModTime: getLatestSourceModTime(srcDir, ignorePatterns),
+    docModTime: getLatestDocModTime(docsDir),
+    fileHashes: docHashesObj,
+    sourceFileHashes: sourceHashesObj
+  };
+
+  saveCache(cacheFile, cache);
+}
+

package/scripts/build-docs/content-normalization.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * Content normalization utilities for documentation comparison
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Sort markdown list items for deterministic comparison
+ */
+export 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
+ */
+export 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.
+ */
+export 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)
+ */
+export 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 current package version from package.json
+ */
+export function getPackageVersion(packageRoot) {
+  try {
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return packageJson.version || '';
+  } catch (err) {
+    return '';
+  }
+}
+

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

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+/**
+ * File system utilities for documentation build
+ */
+
+import { existsSync, statSync, readdirSync } from 'fs';
+import { join, relative } from 'path';
+
+/**
+ * Recursively scan directory for files matching pattern
+ */
+export function scanDirectory(dir, extensions, ignorePatterns = [], baseDir = null) {
+  const files = [];
+  const base = baseDir || dir;
+  
+  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 - test against relative path from base
+        const shouldIgnore = ignorePatterns.length > 0 && ignorePatterns.some(pattern => {
+          const relativePath = relative(base, fullPath);
+          return pattern.test(relativePath) || pattern.test(item.name);
+        });
+        
+        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;
+}
+
+/**
+ * Get the most recent modification time of all source files
+ */
+export function getLatestSourceModTime(srcDir, ignorePatterns = []) {
+  const sourceFiles = scanDirectory(srcDir, ['.ts', '.tsx'], ignorePatterns, srcDir);
+
+  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
+ */
+export function getLatestDocModTime(docsDir) {
+  if (!existsSync(docsDir)) {
+    return 0;
+  }
+
+  const docFiles = scanDirectory(docsDir, ['.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;
+}
+

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+/**
+ * Git utilities for documentation build
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { scanDirectory } from './file-utils.js';
+
+/**
+ * Determine if we're inside a git repository
+ */
+export function isGitRepository(repoRoot) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', {
+      cwd: repoRoot,
+      stdio: 'pipe'
+    });
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Check if git reports any relevant source changes
+ */
+export function hasGitTrackedSourceChanges(repoRoot, docsRelevantPaths) {
+  if (!isGitRepository(repoRoot)) {
+    return true; // Without git context, err on the side of rebuilding
+  }
+
+  try {
+    const status = execSync(`git status --porcelain -- ${docsRelevantPaths.join(' ')}`.trim(), {
+      cwd: repoRoot,
+      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
+ */
+export function shouldSkipDueToCleanGitState(repoRoot, docsDir, docsRelevantPaths) {
+  if (!existsSync(docsDir)) {
+    return false;
+  }
+
+  const existingDocs = scanDirectory(docsDir, ['.md']);
+  if (existingDocs.length === 0) {
+    return false;
+  }
+
+  if (hasGitTrackedSourceChanges(repoRoot, docsRelevantPaths)) {
+    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;
+}
+
+/**
+ * Get git status of docs directory
+ */
+export function getGitStatus(packageRoot, directory) {
+  try {
+    const result = execSync(`git status --porcelain ${directory}`, {
+      cwd: packageRoot,
+      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 [];
+  }
+}
+