@kenjura/ursa 0.96.0 → 0.97.0

package/src/helper/build/autoIndex.js

@@ -1,13 +1,6 @@
 // Auto-index generation helpers for build
-import { existsSync, readFileSync } from "fs";
-import { readdir, readFile } from "fs/promises";
-import { basename, dirname, extname, join } from "path";
-import { outputFile } from "fs-extra";
-import { findStyleCss, findAllStyleCss } from "../findStyleCss.js";
-import { findAllScriptJs } from "../findScriptJs.js";
-import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
-import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
-import { getCustomMenuForFile } from "./menu.js";
+import { readdir } from "./tracedFs.js";
+import { basename, extname, join } from "path";
 import { getFolderConfig, isFolderSelfHidden } from "../folderConfig.js";
 import {
   toDisplayName,
@@ -17,12 +10,9 @@ import {
   getFileLabel,
   findSourceDocument,
 } from "../menuLabels.js";
-import { generateBreadcrumbs } from "../breadcrumbs.js";
-import { bundleDocumentCss, bundleDocumentJs } from "../assetBundler.js";
 
 // Document extensions for checking if a folder has content
 const SOURCE_DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.yml', '.html'];
-const OUTPUT_DOC_EXTENSIONS = ['.html'];
 
 /**
  * Recursively check if a directory contains any document files.
@@ -95,87 +85,6 @@ function compareEntries(a, b) {
   return a.sortKey.toLowerCase().localeCompare(b.sortKey.toLowerCase());
 }
 
-/**
- * Generate auto-index HTML content for a directory from the OUTPUT folder
- * (used by fallback auto-index generation after all files are generated)
- * @param {string} dir - The directory path to generate index for (in output folder)
- * @param {number} depth - How deep to recurse (1 = current level only, 2 = current + children, etc.)
- * @param {number} [currentDepth=0] - Current recursion depth (internal use)
- * @param {string} [pathPrefix=''] - Path prefix for generating correct hrefs (internal use)
- * @param {string|null} [sourceDir=null] - Matching source directory, so `menu-label`
- *   frontmatter and config.json labels can be honored. Without it, entries fall
- *   back to their prettified file names.
- * @returns {Promise<string>} HTML content for the auto-index
- */
-export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pathPrefix = '', sourceDir = null) {
-  try {
-    const children = await readdir(dir, { withFileTypes: true });
-    
-    // Filter to only include relevant files and folders
-    const filteredChildren = children
-      .filter(child => {
-        // Skip hidden files
-        if (child.name.startsWith('.')) return false;
-        // Skip index.html - we're generating it or it's the current page
-        if (child.name === 'index.html') return false;
-        // Skip img folders (contain images, not content)
-        if (child.isDirectory() && child.name === 'img') return false;
-        // Skip folders config.json marks hidden — they are ignored entirely,
-        // so a stale output directory must not resurrect them in a listing
-        if (child.isDirectory() && sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) return false;
-        // Include directories and html files
-        return child.isDirectory() || child.name.endsWith('.html');
-      })
-      .map(child => {
-        const isDir = child.isDirectory();
-        const baseName = isDir ? child.name : child.name.replace(/\.html$/, '');
-        return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
-      })
-      .sort(compareEntries);
-    
-    if (filteredChildren.length === 0) {
-      return '';
-    }
-    
-    const items = [];
-    
-    for (const { child, isDir, label } of filteredChildren) {
-      // Skip directories that contain no documents
-      if (isDir) {
-        const childDir = join(dir, child.name);
-        const childSource = sourceDir ? join(sourceDir, child.name) : null;
-        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, childSource)) continue;
-      }
-      // Use pathPrefix to ensure hrefs are correct relative to the document root
-      const childPath = pathPrefix ? `${pathPrefix}/${child.name}` : child.name;
-      const href = isDir ? `${childPath}/index.html` : (pathPrefix ? `${pathPrefix}/${child.name}` : child.name);
-      const icon = isDir ? '📁' : '📄';
-      
-      let itemHtml = `<li>${icon} <a href="${href}">${label}</a>`;
-      
-      // If this is a directory and we need to go deeper, recurse
-      if (isDir && currentDepth + 1 < depth) {
-        const childDir = join(dir, child.name);
-        const childHtml = await generateAutoIndexHtml(
-          childDir, depth, currentDepth + 1, childPath,
-          sourceDir ? join(sourceDir, child.name) : null
-        );
-        if (childHtml) {
-          itemHtml += `\n${childHtml}`;
-        }
-      }
-      
-      itemHtml += '</li>';
-      items.push(itemHtml);
-    }
-    
-    return `<ul class="auto-index depth-${currentDepth + 1}">\n${items.join('\n')}\n</ul>`;
-  } catch (e) {
-    console.error(`Error generating auto-index HTML for ${dir}: ${e.message}`);
-    return '';
-  }
-}
-
 /**
  * Generate auto-index HTML content from the SOURCE folder
  * (used for inline auto-index generation in index.md files with generate-auto-index: true)
@@ -250,281 +159,3 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
     return '';
   }
 }
-
-/**
- * Generate automatic index.html files for folders that don't have one
- * @param {string} output - Output directory path
- * @param {string[]} directories - List of source directories
- * @param {string} source - Source directory path
- * @param {object} templates - Template map
- * @param {string} menu - Rendered menu HTML
- * @param {string} footer - Footer HTML
- * @param {string[]} generatedArticles - List of source article paths that were generated
- * @param {Set<string>} copiedCssFiles - Set of CSS files already copied to output
- * @param {Set<string>} existingHtmlFiles - Set of existing HTML files in source (relative paths)
- * @param {string} cacheBustTimestamp - Cache-busting timestamp
- * @param {object} progress - Progress reporter instance
- * @param {Map} customMenus - Map of custom menus by directory path
- */
-export async function generateAutoIndices(output, directories, source, templates, menu, footer, generatedArticles, copiedCssFiles, existingHtmlFiles, cacheBustTimestamp, progress, customMenus) {
-  // Alternate index file names to look for (in priority order)
-  const INDEX_ALTERNATES = ['_index.html', 'home.html', '_home.html'];
-  
-  // Normalize paths (remove trailing slashes for consistent replacement)
-  const sourceNorm = source.replace(/\/+$/, '');
-  const outputNorm = output.replace(/\/+$/, '');
-  
-  // Build set of directories that already have an index.html from a source index.md/txt/yml
-  // Exclude metadata-only index files - they should still get auto-generated indices
-  const dirsWithSourceIndex = new Set();
-  for (const articlePath of generatedArticles) {
-    const base = basename(articlePath, extname(articlePath));
-    if (base === 'index') {
-      // Check if this is a metadata-only index file
-      try {
-        if (existsSync(articlePath)) {
-          const content = readFileSync(articlePath, 'utf8');
-          if (isMetadataOnly(content)) {
-            // Skip - this folder should still get an auto-index
-            continue;
-          }
-        }
-      } catch (e) {
-        // If we can't read it, assume it has content
-      }
-      const dir = dirname(articlePath);
-      const outputDir = dir.replace(sourceNorm, outputNorm);
-      dirsWithSourceIndex.add(outputDir);
-    }
-  }
-  
-  // Get all output directories (including root)
-  const outputDirs = new Set([outputNorm]);
-  for (const dir of directories) {
-    // Handle both with and without trailing slash in source
-    const outputDir = dir.replace(sourceNorm, outputNorm);
-    outputDirs.add(outputDir);
-  }
-  
-  let generatedCount = 0;
-  let renamedCount = 0;
-  let skippedHtmlCount = 0;
-  
-  for (const dir of outputDirs) {
-    // Skip output directories that were never created (the source folder
-    // produced no output files, e.g. it was empty)
-    if (!existsSync(dir)) {
-      continue;
-    }
-
-    const indexPath = join(dir, 'index.html');
-
-    // Skip if this directory had a source index.md/txt/yml that was already processed
-    if (dirsWithSourceIndex.has(dir)) {
-      continue;
-    }
-    
-    // Check if there's an existing index.html in the source directory (don't overwrite it)
-    const sourceDir = dir.replace(outputNorm, sourceNorm);
-    const relativeIndexPath = join(sourceDir, 'index.html').replace(sourceNorm + '/', '');
-    if (existingHtmlFiles && existingHtmlFiles.has(relativeIndexPath)) {
-      skippedHtmlCount++;
-      continue; // Don't overwrite existing source HTML
-    }
-    
-    // NOTE: an existing index.html in output is deliberately NOT a reason to
-    // skip. This listing describes the folder's contents, so it goes stale the
-    // moment a document or subfolder is added or removed, and warm builds kept
-    // whatever was written the first time — indefinitely. Everything that has a
-    // rightful claim on index.html is already excluded above: folders with a
-    // source index document (dirsWithSourceIndex, built from every source
-    // article rather than only the regenerated ones) and hand-written source
-    // HTML (existingHtmlFiles). Alternates are re-promoted below, so those stay
-    // authoritative too.
-
-    // Get folder name for (foldername).html check
-    const folderName = basename(dir);
-    const folderNameAlternate = `${folderName}.html`;
-    
-    // Check for alternate index files
-    let foundAlternate = null;
-    for (const alt of [...INDEX_ALTERNATES, folderNameAlternate]) {
-      const altPath = join(dir, alt);
-      if (existsSync(altPath)) {
-        foundAlternate = altPath;
-        break;
-      }
-    }
-    
-    if (foundAlternate) {
-      // Rename/copy alternate to index.html
-      try {
-        const content = await readFile(foundAlternate, 'utf8');
-        await outputFile(indexPath, content);
-        renamedCount++;
-        progress.status('Auto-index', `Promoted ${basename(foundAlternate)} → index.html in ${dir.replace(outputNorm, '') || '/'}`);
-      } catch (e) {
-        progress.log(`Error promoting ${foundAlternate} to index.html: ${e.message}`);
-      }
-    } else {
-      // Generate a simple index listing direct children
-      try {
-        const children = await readdir(dir, { withFileTypes: true });
-        
-        // Filter to only include relevant files and folders
-        const filteredItems = children
-          .filter(child => {
-            // Skip hidden files and index alternates we just checked
-            if (child.name.startsWith('.')) return false;
-            if (child.name === 'index.html') return false;
-            // Skip folders config.json marks hidden — they produce no output
-            if (child.isDirectory() && isFolderSelfHidden(join(sourceDir, child.name))) return false;
-            // Include directories and html files
-            return child.isDirectory() || child.name.endsWith('.html');
-          })
-          .map(child => {
-            const isDir = child.isDirectory();
-            const baseName = isDir ? child.name : child.name.replace(/\.html$/, '');
-            return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
-          })
-          .sort(compareEntries);
-
-        // Build items, skipping directories with no documents
-        const items = [];
-        for (const { child, isDir, label } of filteredItems) {
-          if (isDir) {
-            const childDir = join(dir, child.name);
-            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS, join(sourceDir, child.name))) continue;
-          }
-          // For directories, link to /folder/index.html; for files, use the filename directly
-          const href = isDir ? `${child.name}/index.html` : child.name;
-          const icon = isDir ? '📁' : '📄';
-          items.push(`<li>${icon} <a href="${href}">${label}</a></li>`);
-        }
-        
-        if (items.length === 0) {
-          // Empty folder, skip generating index
-          continue;
-        }
-        
-        // The page's own heading and <title> follow the same naming rules, so a
-        // folder labelled "BNW - Brave New World" in the menu is not "Bnw" here.
-        const folderDisplayName = dir === outputNorm
-          ? 'Home'
-          : getFolderLabel(sourceDir, getFolderConfig(sourceDir), folderName);
-
-        // Generate breadcrumbs for auto-index pages
-        const relDir = dir.replace(outputNorm, '').replace(/^\//, '');
-        const breadcrumbDir = relDir ? relDir + '/' : '/';
-        const breadcrumbHtml = generateBreadcrumbs(breadcrumbDir, 'index', null, sourceNorm);
-
-        const indexHtml = `${breadcrumbHtml}<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
-        
-        const template = templates["default-template"];
-        if (!template) {
-          progress.log(`Warning: No default template for auto-index in ${dir}`);
-          continue;
-        }
-        
-        // Find all style.css files up the tree and bundle them into a single CSS file
-        // (Generate mode: one CSS bundle per unique folder path)
-        let styleLink = "";
-        try {
-          const sourceDir = dir.replace(outputNorm, sourceNorm);
-          const cssPaths = await findAllStyleCss(sourceDir, sourceNorm);
-          if (cssPaths.length > 0) {
-            // Copy all CSS files to output
-            for (const cssPath of cssPaths) {
-              if (!copiedCssFiles.has(cssPath)) {
-                const cssOutputPath = cssPath.replace(sourceNorm, outputNorm);
-                const cssContent = await readFile(cssPath, 'utf8');
-                await outputFile(cssOutputPath, cssContent);
-                copiedCssFiles.add(cssPath);
-              }
-            }
-            // Bundle into a single file
-            const folderRelative = sourceDir.replace(sourceNorm, '').replace(/^\//, '');
-            const bundleUrl = await bundleDocumentCss(cssPaths, outputNorm, sourceNorm, folderRelative, { minify: true });
-            styleLink = `<link rel="stylesheet" href="${bundleUrl}" />`;
-          }
-        } catch (e) {
-          // ignore CSS lookup errors
-        }
-        
-        // Find all script.js files from docroot to this directory and bundle them
-        // (Generate mode: one JS bundle per unique folder path)
-        let customScript = "";
-        try {
-          const sourceDir = dir.replace(outputNorm, sourceNorm);
-          const scriptPaths = await findAllScriptJs(sourceDir, sourceNorm);
-          if (scriptPaths.length > 0) {
-            const folderRelative = sourceDir.replace(sourceNorm, '').replace(/^\//, '');
-            const bundleUrl = await bundleDocumentJs(scriptPaths, outputNorm, sourceNorm, folderRelative, { minify: true });
-            customScript = `<script src="${bundleUrl}"></script>`;
-          }
-        } catch (e) {
-          // ignore script lookup errors
-        }
-        
-        // Find custom menu for this directory
-        let customMenuInfo = null;
-        if (customMenus) {
-          // Create a pseudo-file path for this directory to look up custom menu
-          const sourceDir = dir.replace(outputNorm, sourceNorm);
-          const pseudoFilePath = join(sourceDir, 'index.md'); // Pretend there's an index.md
-          customMenuInfo = getCustomMenuForFile(pseudoFilePath, sourceNorm, customMenus);
-        }
-        
-        let finalHtml = template;
-        const replacements = {
-          "${menu}": menu,
-          "${body}": indexHtml,
-          "${searchIndex}": "[]",
-          "${title}": folderDisplayName,
-          "${meta}": "{}",
-          "${transformedMetadata}": "",
-          "${styleLink}": styleLink,
-          "${customScript}": customScript,
-          "${footer}": footer
-        };
-        for (const [key, value] of Object.entries(replacements)) {
-          finalHtml = finalHtml.replace(key, value);
-        }
-        
-        // Add menu data attributes to body
-        if (customMenuInfo) {
-          const menuPosition = customMenuInfo.menuPosition || 'top';
-          finalHtml = finalHtml.replace(
-            /<body([^>]*)>/,
-            `<body$1 data-custom-menu="${customMenuInfo.menuJsonPath}" data-menu-position="${menuPosition}">`
-          );
-        } else {
-          // No custom menu — default to top menu
-          finalHtml = finalHtml.replace(
-            /<body([^>]*)>/,
-            `<body$1 data-menu-position="top">`
-          );
-        }
-        
-        // Add cache-busting timestamps to static file references
-        finalHtml = addTimestampToHtmlStaticRefs(finalHtml, cacheBustTimestamp);
-        
-        await outputFile(indexPath, finalHtml);
-        generatedCount++;
-        progress.status('Auto-index', `Generated index.html for ${dir.replace(outputNorm, '') || '/'}`);
-      } catch (e) {
-        progress.log(`Error generating auto-index for ${dir}: ${e.message}`);
-      }
-    }
-  }
-  
-  if (generatedCount > 0 || renamedCount > 0 || skippedHtmlCount > 0) {
-    let summary = `${generatedCount} generated, ${renamedCount} promoted`;
-    if (skippedHtmlCount > 0) {
-      summary += `, ${skippedHtmlCount} skipped (existing HTML)`;
-    }
-    progress.done('Auto-index', summary);
-  } else {
-    progress.log(`Auto-index: All folders already have index.html`);
-  }
-}

package/src/helper/build/excludeFilter.js

@@ -1,6 +1,5 @@
 // Exclude/filter helpers for build
-import { existsSync } from "fs";
-import { readFile, stat } from "fs/promises";
+import { existsSync, readFile, stat } from "./tracedFs.js";
 
 /**
  * Parse exclude option - can be comma-separated paths or a file path

package/src/helper/build/footer.js

@@ -1,18 +1,23 @@
 // Footer generation helpers for build
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
+import { existsSync, readFile } from "./tracedFs.js";
 import { dirname, join, resolve } from "path";
 import { URL } from "url";
 import { renderFile } from "../fileRenderer.js";
+import { execSync } from "child_process";
 
 /**
  * Generate footer HTML from footer.md and package.json
  * @param {string} source - resolved source path with trailing slash
  * @param {string} _source - original source path
  * @param {number} buildId - the current build ID
+ * @param {{now?: Date, gitHash?: string|null}} [session] - Build metadata fixed once per
+ *   serve session (or generate run): the timestamp shown in the footer and the
+ *   doc repo's short commit hash. Supplying them keeps the footer a pure
+ *   function of its inputs for the length of the session; when omitted they are
+ *   taken now.
  * @returns {Promise<string>} Footer HTML
  */
-export async function getFooter(source, _source, buildId) {
+export async function getFooter(source, _source, buildId, session = {}) {
   const footerParts = [];
   
   // Try to read footer.md from source root
@@ -40,7 +45,6 @@ export async function getFooter(source, _source, buildId) {
       if (existsSync(packagePath)) {
         const packageJson = await readFile(packagePath, 'utf8');
         docPackage = JSON.parse(packageJson);
-        console.log(`Found doc package.json at ${packagePath}`);
         break;
       }
     } catch (e) {
@@ -61,7 +65,6 @@ export async function getFooter(source, _source, buildId) {
       const ursaPackageJson = await readFile(ursaPackagePath, 'utf8');
       const ursaPackage = JSON.parse(ursaPackageJson);
       ursaVersion = ursaPackage.version;
-      console.log(`Found ursa package.json at ${ursaPackagePath}, version: ${ursaVersion}`);
     }
   } catch (e) {
     console.error(`Error reading ursa package.json: ${e.message}`);
@@ -75,7 +78,7 @@ export async function getFooter(source, _source, buildId) {
   metaParts.push(`build ${buildId}`);
   
   // Full date/time in a readable format
-  const now = new Date();
+  const now = session.now ?? new Date();
   const timestamp = now.toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, ' UTC');
   metaParts.push(timestamp);
   
@@ -94,20 +97,30 @@ export async function getFooter(source, _source, buildId) {
     }
   }
   
-  // Try to get git short hash of doc repo (as HTML comment)
+  // Git short hash of the doc repo (as HTML comment)
+  const gitHash = session.gitHash !== undefined ? session.gitHash : readGitHash(_source);
+  if (gitHash) {
+    footerParts.push(`<!-- git: ${gitHash} -->`);
+  }
+  
+  return footerParts.join('\n');
+}
+
+/**
+ * The doc repo's short commit hash, or null outside a git work tree.
+ * @param {string} _source - Source directory
+ * @returns {string|null}
+ */
+export function readGitHash(_source) {
   try {
-    const { execSync } = await import('child_process');
     const gitHash = execSync('git rev-parse --short HEAD', {
       cwd: resolve(_source),
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'pipe']
     }).trim();
-    if (gitHash) {
-      footerParts.push(`<!-- git: ${gitHash} -->`);
-    }
+    return gitHash || null;
   } catch (e) {
-    // Not a git repo or git not available - silently skip
+    // Not a git repo or git not available
+    return null;
   }
-  
-  return footerParts.join('\n');
 }