@kenjura/ursa 0.53.0 → 0.55.0

package/src/helper/build/cacheBust.js

@@ -0,0 +1,62 @@
+// Cache busting helpers for build
+
+/**
+ * Generate a cache-busting timestamp in ISO format (e.g., 20251221T221700Z)
+ * @returns {string} Timestamp string suitable for query params
+ */
+export function generateCacheBustTimestamp() {
+  const now = new Date();
+  const year = now.getUTCFullYear();
+  const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(now.getUTCDate()).padStart(2, '0');
+  const hours = String(now.getUTCHours()).padStart(2, '0');
+  const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+  const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+  return `${year}${month}${day}T${hours}${minutes}${seconds}Z`;
+}
+
+/**
+ * Add cache-busting timestamp to url() references in CSS content
+ * @param {string} cssContent - The CSS file content
+ * @param {string} timestamp - The cache-busting timestamp
+ * @returns {string} CSS with timestamped URLs
+ */
+export function addTimestampToCssUrls(cssContent, timestamp) {
+  // Match url(...) in any context, including CSS variables, with optional whitespace and quotes
+  // Exclude data: URLs and already-timestamped URLs
+  return cssContent.replace(
+    /url\(\s*(['"]?)(?!data:)([^'"\)]+?)\1\s*\)/gi,
+    (match, quote, url) => {
+      // Don't add timestamp if already has query string
+      if (url.includes('?')) {
+        return match;
+      }
+      return `url(${quote}${url}?v=${timestamp}${quote})`;
+    }
+  );
+}
+
+/**
+ * Add cache-busting timestamp to static file references in HTML
+ * @param {string} html - The HTML content
+ * @param {string} timestamp - The cache-busting timestamp
+ * @returns {string} HTML with timestamped static file references
+ */
+export function addTimestampToHtmlStaticRefs(html, timestamp) {
+  // Add timestamp to CSS links
+  html = html.replace(
+    /(<link[^>]+href=["'])([^"']+\.css)(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$3`
+  );
+  // Add timestamp to JS scripts
+  html = html.replace(
+    /(<script[^>]+src=["'])([^"']+\.js)(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$3`
+  );
+  // Add timestamp to images in img tags
+  html = html.replace(
+    /(<img[^>]+src=["'])([^"']+\.(jpg|jpeg|png|gif|webp|svg|ico))(["'][^>]*>)/gi,
+    `$1$2?v=${timestamp}$4`
+  );
+  return html;
+}

package/src/helper/build/excludeFilter.js

@@ -0,0 +1,67 @@
+// Exclude/filter helpers for build
+import { existsSync } from "fs";
+import { readFile, stat } from "fs/promises";
+
+/**
+ * Parse exclude option - can be comma-separated paths or a file path
+ * @param {string} excludeOption - The exclude option value
+ * @param {string} source - Source directory path
+ * @returns {Promise<Set<string>>} Set of excluded folder paths (normalized)
+ */
+export async function parseExcludeOption(excludeOption, source) {
+  const excludedPaths = new Set();
+  
+  if (!excludeOption) return excludedPaths;
+  
+  // Check if it's a file path (exists as a file)
+  const isFile = existsSync(excludeOption) && (await stat(excludeOption)).isFile();
+  
+  let patterns;
+  if (isFile) {
+    // Read patterns from file (one per line)
+    const content = await readFile(excludeOption, 'utf8');
+    patterns = content.split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#')); // Skip empty lines and comments
+  } else {
+    // Treat as comma-separated list
+    patterns = excludeOption.split(',').map(p => p.trim()).filter(Boolean);
+  }
+  
+  // Normalize patterns to absolute paths
+  for (const pattern of patterns) {
+    // Remove leading/trailing slashes and normalize
+    const normalized = pattern.replace(/^\/+|\/+$/g, '');
+    // Store as relative path for easier matching
+    excludedPaths.add(normalized);
+  }
+  
+  return excludedPaths;
+}
+
+/**
+ * Create a filter function that excludes files in specified folders
+ * @param {Set<string>} excludedPaths - Set of excluded folder paths
+ * @param {string} source - Source directory path
+ * @returns {Function} Filter function
+ */
+export function createExcludeFilter(excludedPaths, source) {
+  if (excludedPaths.size === 0) {
+    return () => true; // No exclusions, allow all
+  }
+  
+  return (filePath) => {
+    // Get path relative to source
+    const relativePath = filePath.replace(source, '').replace(/^\/+/, '');
+    
+    // Check if file is in any excluded folder
+    for (const excluded of excludedPaths) {
+      if (relativePath === excluded || 
+          relativePath.startsWith(excluded + '/') ||
+          relativePath.startsWith(excluded + '\\')) {
+        return false; // Exclude this file
+      }
+    }
+    return true; // Include this file
+  };
+}

package/src/helper/build/footer.js

@@ -0,0 +1,113 @@
+// Footer generation helpers for build
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { URL } from "url";
+import { renderFile } from "../fileRenderer.js";
+
+/**
+ * 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
+ * @returns {Promise<string>} Footer HTML
+ */
+export async function getFooter(source, _source, buildId) {
+  const footerParts = [];
+  
+  // Try to read footer.md from source root
+  const footerPath = join(source, 'footer.md');
+  try {
+    if (existsSync(footerPath)) {
+      const footerMd = await readFile(footerPath, 'utf8');
+      const footerHtml = renderFile({ fileContents: footerMd, type: '.md' });
+      footerParts.push(`<div class="footer-content">${footerHtml}</div>`);
+    }
+  } catch (e) {
+    console.error(`Error reading footer.md: ${e.message}`);
+  }
+  
+  // Try to read package.json from doc repo (check both source dir and parent)
+  let docPackage = null;
+  const sourceDir = resolve(_source);
+  const packagePaths = [
+    join(sourceDir, 'package.json'),           // In source dir itself
+    join(sourceDir, '..', 'package.json'),     // One level up (if docs is a subfolder)
+  ];
+  
+  for (const packagePath of packagePaths) {
+    try {
+      if (existsSync(packagePath)) {
+        const packageJson = await readFile(packagePath, 'utf8');
+        docPackage = JSON.parse(packageJson);
+        console.log(`Found doc package.json at ${packagePath}`);
+        break;
+      }
+    } catch (e) {
+      // Continue to next path
+    }
+  }
+  
+  // Get ursa version from ursa's own package.json
+  // Use import.meta.url to find the package.json relative to this file
+  let ursaVersion = 'unknown';
+  try {
+    // From src/helper/build/footer.js, go up to package root
+    const currentFileUrl = new URL(import.meta.url);
+    const currentDir = dirname(currentFileUrl.pathname);
+    const ursaPackagePath = resolve(currentDir, '..', '..', '..', 'package.json');
+    
+    if (existsSync(ursaPackagePath)) {
+      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}`);
+  }
+  
+  // Build meta line: version, build id, timestamp, "generated by ursa"
+  const metaParts = [];
+  if (docPackage?.version) {
+    metaParts.push(`v${docPackage.version}`);
+  }
+  metaParts.push(`build ${buildId}`);
+  
+  // Full date/time in a readable format
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').replace(/\.\d{3}Z$/, ' UTC');
+  metaParts.push(timestamp);
+  
+  metaParts.push(`Generated by <a href="https://www.npmjs.com/package/@kenjura/ursa">ursa</a> v${ursaVersion}`);
+  
+  footerParts.push(`<div class="footer-meta">${metaParts.join(' • ')}</div>`);
+  
+  // Copyright line from doc package.json
+  if (docPackage?.copyright) {
+    footerParts.push(`<div class="footer-copyright">${docPackage.copyright}</div>`);
+  } else if (docPackage?.author) {
+    const year = new Date().getFullYear();
+    const author = typeof docPackage.author === 'string' ? docPackage.author : docPackage.author.name;
+    if (author) {
+      footerParts.push(`<div class="footer-copyright">© ${year} ${author}</div>`);
+    }
+  }
+  
+  // Try to get git short hash of doc repo (as HTML comment)
+  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} -->`);
+    }
+  } catch (e) {
+    // Not a git repo or git not available - silently skip
+  }
+  
+  return footerParts.join('\n');
+}

package/src/helper/build/index.js

@@ -0,0 +1,13 @@
+// Barrel file for build helpers
+export * from './cacheBust.js';
+export * from './batch.js';
+export * from './progress.js';
+export * from './watchCache.js';
+export * from './titleCase.js';
+export * from './excludeFilter.js';
+export * from './pathUtils.js';
+export * from './templates.js';
+export * from './menu.js';
+export * from './metadata.js';
+export * from './footer.js';
+export * from './autoIndex.js';

package/src/helper/build/menu.js

@@ -0,0 +1,103 @@
+// Menu helpers for build
+import { getAutomenu } from "../automenu.js";
+import { renderFile } from "../fileRenderer.js";
+import { findCustomMenu, parseCustomMenu, buildCustomMenuHtml } from "../customMenu.js";
+import { dirname, relative, resolve } from "path";
+
+/**
+ * Get menu HTML and menu data from source directory
+ * @param {string[]} allSourceFilenames - All source file names
+ * @param {string} source - Source directory path
+ * @param {Set<string>} validPaths - Set of valid internal paths for link validation
+ * @returns {Promise<{html: string, menuData: Object}>} Menu HTML and menu data
+ */
+export async function getMenu(allSourceFilenames, source, validPaths) {
+  const menuResult = await getAutomenu(source, validPaths);
+  const menuBody = renderFile({ fileContents: menuResult.html, type: ".md" });
+  return {
+    html: menuBody,
+    menuData: menuResult.menuData
+  };
+}
+
+/**
+ * Find all unique custom menus in the source tree
+ * @param {string[]} allSourceFilenames - All source file names
+ * @param {string} source - Source directory path
+ * @returns {Map<string, {menuPath: string, menuDir: string, menuData: Array}>} Map of menu dir to menu info
+ */
+export function findAllCustomMenus(allSourceFilenames, source) {
+  const customMenus = new Map();
+  const checkedDirs = new Set();
+  
+  // Check each directory for custom menus
+  for (const file of allSourceFilenames) {
+    const dir = dirname(file);
+    if (checkedDirs.has(dir)) continue;
+    checkedDirs.add(dir);
+    
+    const menuInfo = findCustomMenu(dir, source);
+    if (menuInfo && !customMenus.has(menuInfo.menuDir)) {
+      const menuData = parseCustomMenu(menuInfo.content, menuInfo.menuDir, source);
+      customMenus.set(menuInfo.menuDir, {
+        menuPath: menuInfo.path,
+        menuDir: menuInfo.menuDir,
+        menuData,
+        // The URL path for the menu JSON file
+        menuJsonPath: '/public/custom-menu-' + getMenuId(menuInfo.menuDir, source) + '.json',
+      });
+    }
+  }
+  
+  return customMenus;
+}
+
+/**
+ * Generate a unique ID for a custom menu based on its directory
+ * @param {string} menuDir - The directory where the menu is located
+ * @param {string} source - The source root directory
+ * @returns {string} - A URL-safe ID
+ */
+function getMenuId(menuDir, source) {
+  const relativePath = relative(source, menuDir);
+  if (!relativePath) return 'root';
+  return relativePath.replace(/[\/\\]/g, '-').replace(/[^a-zA-Z0-9-]/g, '');
+}
+
+/**
+ * Get the custom menu info for a specific file path
+ * @param {string} filePath - The source file path
+ * @param {string} source - The source root directory
+ * @param {Map} customMenus - Map of all custom menus
+ * @returns {{menuJsonPath: string, menuDir: string} | null} - Custom menu info or null
+ */
+export function getCustomMenuForFile(filePath, source, customMenus) {
+  const fileDir = resolve(dirname(filePath));
+  const sourceResolved = resolve(source);
+  
+  // Walk up from file dir to find matching custom menu
+  let currentDir = fileDir;
+  while (currentDir.startsWith(sourceResolved)) {
+    if (customMenus.has(currentDir)) {
+      const menuInfo = customMenus.get(currentDir);
+      return {
+        menuJsonPath: menuInfo.menuJsonPath,
+        menuDir: relative(source, menuInfo.menuDir) || '',
+      };
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) break;
+    currentDir = parentDir;
+  }
+  
+  return null;
+}
+
+/**
+ * Build HTML for a custom menu
+ * @param {Array} menuData - The parsed menu data
+ * @returns {string} - HTML string for the menu
+ */
+export function buildCustomMenuHtmlExport(menuData) {
+  return buildCustomMenuHtml(menuData);
+}

package/src/helper/build/metadata.js

@@ -0,0 +1,30 @@
+// Metadata transformation helpers for build
+import { join } from "path";
+
+/**
+ * Get transformed metadata using custom or default transform function
+ * @param {string} dirname - Directory containing the file
+ * @param {Object} metadata - Raw metadata object
+ * @returns {Promise<string>} Transformed metadata string
+ */
+export async function getTransformedMetadata(dirname, metadata) {
+  // custom transform? else, use default
+  const customTransformFnFilename = join(dirname, "transformMetadata.js");
+  let transformFn = defaultTransformFn;
+  try {
+    const customTransformFn = (await import(customTransformFnFilename)).default;
+    if (typeof customTransformFn === "function")
+      transformFn = customTransformFn;
+  } catch (e) {
+    // No custom transform found, use default
+  }
+  try {
+    return transformFn(metadata);
+  } catch (e) {
+    return "error transforming metadata";
+  }
+
+  function defaultTransformFn(metadata) {
+    return "default transform";
+  }
+}

package/src/helper/build/pathUtils.js

@@ -0,0 +1,13 @@
+// Path utility helpers for build
+
+/**
+ * Add trailing slash to a path if not present
+ * @param {string} somePath - Path to modify
+ * @returns {string} Path with trailing slash
+ */
+export function addTrailingSlash(somePath) {
+  if (typeof somePath !== "string") return somePath;
+  if (somePath.length < 1) return somePath;
+  if (somePath[somePath.length - 1] === "/") return somePath;
+  return `${somePath}/`;
+}

package/src/helper/build/progress.js

@@ -0,0 +1,35 @@
+// Progress reporter for build
+
+export class ProgressReporter {
+  constructor() {
+    this.lines = {};
+    this.isTTY = process.stdout.isTTY;
+  }
+  status(name, message) {
+    if (this.isTTY) {
+      const line = `${name}: ${message}`;
+      this.lines[name] = line;
+      process.stdout.write(`\r\x1b[K${line}`);
+    }
+  }
+  done(name, message) {
+    if (this.isTTY) {
+      process.stdout.write(`\r\x1b[K${name}: ${message}\n`);
+    } else {
+      console.log(`${name}: ${message}`);
+    }
+    delete this.lines[name];
+  }
+  log(message) {
+    if (this.isTTY) {
+      process.stdout.write(`\r\x1b[K${message}\n`);
+    } else {
+      console.log(message);
+    }
+  }
+  clear() {
+    if (this.isTTY) {
+      process.stdout.write(`\r\x1b[K`);
+    }
+  }
+}

package/src/helper/build/templates.js

@@ -0,0 +1,30 @@
+// Template helpers for build
+import { readFile } from "fs/promises";
+import { parse } from "path";
+import { recurse } from "../recursive-readdir.js";
+
+/**
+ * Get all templates from meta directory
+ * @param {string} meta - Full path to meta files directory
+ * @returns {Promise<Object>} Map of templateName to templateBody
+ */
+export async function getTemplates(meta) {
+  const allMetaFilenames = await recurse(meta);
+  const allHtmlFilenames = allMetaFilenames.filter((filename) =>
+    filename.match(/\.html/)
+  );
+
+  let templates = {};
+  const templatesArray = await Promise.all(
+    allHtmlFilenames.map(async (filename) => {
+      const { name } = parse(filename);
+      const fileContent = await readFile(filename, "utf8");
+      return [name, fileContent];
+    })
+  );
+  templatesArray.forEach(
+    ([templateName, templateText]) => (templates[templateName] = templateText)
+  );
+
+  return templates;
+}

package/src/helper/build/titleCase.js

@@ -0,0 +1,7 @@
+// Helper to convert filename to title case
+export function toTitleCase(filename) {
+  return filename
+    .split(/[-_\s]+/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+}

package/src/helper/build/watchCache.js

@@ -0,0 +1,26 @@
+// Watch mode cache and clear function for build
+
+export const watchModeCache = {
+  templates: null,
+  menu: null,
+  footer: null,
+  validPaths: null,
+  source: null,
+  meta: null,
+  output: null,
+  hashCache: null,
+  cacheBustTimestamp: null,
+  lastFullBuild: 0,
+  isInitialized: false,
+};
+
+export function clearWatchCache(cssPathCache) {
+  watchModeCache.templates = null;
+  watchModeCache.menu = null;
+  watchModeCache.footer = null;
+  watchModeCache.validPaths = null;
+  watchModeCache.hashCache = null;
+  watchModeCache.isInitialized = false;
+  if (cssPathCache) cssPathCache.clear();
+  console.log('Watch cache cleared');
+}