@kenjura/ursa 0.96.0 → 0.97.0

package/src/helper/__test__/dependencyTracker.test.js

@@ -1,157 +0,0 @@
-import { join } from "path";
-import { mkdtemp, rm, readFile } from "fs/promises";
-import { existsSync } from "fs";
-import { tmpdir } from "os";
-import {
-  DependencyTracker,
-  loadDependencyTracker,
-  saveDependencyTracker,
-  getDependencyGraphPath,
-} from "../dependencyTracker.js";
-
-let tempDir;
-beforeEach(async () => {
-  tempDir = await mkdtemp(join(tmpdir(), "ursa-deptracker-"));
-});
-afterEach(async () => {
-  await rm(tempDir, { recursive: true, force: true });
-});
-
-function makeTracker(sourceDir) {
-  const tracker = new DependencyTracker();
-  tracker.init(sourceDir);
-  return tracker;
-}
-
-describe("serialize / load", () => {
-  it("round-trips registrations through serialize + load", () => {
-    const t1 = makeTracker("/site/docs");
-    t1.registerDocument("/site/docs/a.md", {
-      templateName: "default-template",
-      cssPaths: ["/site/docs/style.css"],
-      scriptPaths: ["/site/docs/script.js"],
-    });
-    t1.registerDocument("/site/docs/sub/b.md", {
-      templateName: "wiki",
-      cssPaths: ["/site/docs/style.css", "/site/docs/sub/style.css"],
-    });
-
-    const data = JSON.parse(JSON.stringify(t1.serialize()));
-    const t2 = makeTracker("/site/docs");
-    expect(t2.load(data)).toBe(true);
-
-    expect([...t2.getAffectedDocuments("/site/docs/style.css")].sort()).toEqual([
-      "/site/docs/a.md",
-      "/site/docs/sub/b.md",
-    ]);
-    expect([...t2.getDocumentsUsingTemplate("wiki")]).toEqual(["/site/docs/sub/b.md"]);
-    expect(t2.getStats()).toEqual(t1.getStats());
-  });
-
-  it("merges with current-run registrations, which take precedence", () => {
-    const t1 = makeTracker("/site/docs");
-    t1.registerDocument("/site/docs/a.md", { templateName: "old-template" });
-    t1.registerDocument("/site/docs/b.md", { templateName: "default-template" });
-    const persisted = t1.serialize();
-
-    // New run: a.md was re-rendered with a different template before load
-    const t2 = makeTracker("/site/docs");
-    t2.registerDocument("/site/docs/a.md", { templateName: "new-template" });
-    expect(t2.load(persisted)).toBe(true);
-
-    // Live registration wins; persisted fills in the hash-skipped doc
-    expect([...t2.getDocumentsUsingTemplate("new-template")]).toEqual(["/site/docs/a.md"]);
-    expect([...t2.getDocumentsUsingTemplate("old-template")]).toEqual([]);
-    expect([...t2.getDocumentsUsingTemplate("default-template")]).toEqual(["/site/docs/b.md"]);
-  });
-
-  it("rejects mismatched schema versions and source dirs", () => {
-    const t = makeTracker("/site/docs");
-    expect(t.load(null)).toBe(false);
-    expect(t.load({ version: 99, documents: {} })).toBe(false);
-    const other = makeTracker("/different/source").serialize();
-    other.documents["/different/source/a.md"] = ["template:default-template"];
-    expect(t.load(other)).toBe(false);
-    expect(t.getStats().totalDocuments).toBe(0);
-  });
-});
-
-describe("prune", () => {
-  it("drops registrations for documents not in the keep set", () => {
-    const t = makeTracker("/site/docs");
-    t.registerDocument("/site/docs/keep.md", { cssPaths: ["/site/docs/style.css"] });
-    t.registerDocument("/site/docs/deleted.md", { cssPaths: ["/site/docs/style.css"] });
-
-    t.prune(new Set(["/site/docs/keep.md"]));
-
-    expect([...t.getAffectedDocuments("/site/docs/style.css")]).toEqual(["/site/docs/keep.md"]);
-    expect(t.getStats().totalDocuments).toBe(1);
-  });
-});
-
-describe("file persistence helpers", () => {
-  it("saves to and loads from .ursa/dependency-graph.json", async () => {
-    const t1 = makeTracker(tempDir);
-    t1.registerDocument(join(tempDir, "a.md"), {
-      templateName: "default-template",
-      cssPaths: [join(tempDir, "style.css")],
-    });
-    expect(await saveDependencyTracker(tempDir, t1)).toBe(true);
-    expect(existsSync(getDependencyGraphPath(tempDir))).toBe(true);
-    const onDisk = JSON.parse(await readFile(getDependencyGraphPath(tempDir), "utf8"));
-    expect(onDisk.version).toBe(1);
-
-    const t2 = makeTracker(tempDir);
-    expect(await loadDependencyTracker(tempDir, t2)).toBe(true);
-    expect([...t2.getAffectedDocuments(join(tempDir, "style.css"))]).toEqual([
-      join(tempDir, "a.md"),
-    ]);
-  });
-
-  it("returns false when no persisted graph exists", async () => {
-    const t = makeTracker(tempDir);
-    expect(await loadDependencyTracker(tempDir, t)).toBe(false);
-  });
-});
-
-describe("getMetaInvalidationPlan", () => {
-  it("does not force a full rebuild for static assets in meta", () => {
-    const t = makeTracker("/site/docs");
-    t.registerDocument("/site/docs/a.md", { templateName: "default-template" });
-
-    for (const file of ["logo.png", "font.woff2", "manual.pdf", "icon.SVG"]) {
-      const plan = t.getMetaInvalidationPlan(`/site/meta/shared/${file}`, "/site/meta");
-      expect(plan.requiresFullRebuild).toBe(false);
-      expect(plan.affectedDocuments).toEqual([]);
-    }
-  });
-
-  it("still regenerates documents for template and css/js meta changes", () => {
-    const t = makeTracker("/site/docs");
-    t.registerDocument("/site/docs/a.md", { templateName: "default-template" });
-
-    // New folder structure: templates/{name}/index.html → name from the folder
-    const tplPlan = t.getMetaInvalidationPlan(
-      "/site/meta/templates/default-template/index.html",
-      "/site/meta"
-    );
-    expect(tplPlan.requiresFullRebuild).toBe(false);
-    expect(tplPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
-
-    // Legacy flat structure: {name}.html at the meta root
-    const legacyPlan = t.getMetaInvalidationPlan(
-      "/site/meta/default-template.html",
-      "/site/meta"
-    );
-    expect(legacyPlan.requiresFullRebuild).toBe(false);
-    expect(legacyPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
-
-    const cssPlan = t.getMetaInvalidationPlan("/site/meta/shared/theme.css", "/site/meta");
-    expect(cssPlan.requiresFullRebuild).toBe(false);
-    expect(cssPlan.affectedDocuments).toEqual(["/site/docs/a.md"]);
-
-    // Unknown meta file types still fall back to a full rebuild
-    const unknownPlan = t.getMetaInvalidationPlan("/site/meta/shared/data.json", "/site/meta");
-    expect(unknownPlan.requiresFullRebuild).toBe(true);
-  });
-});

package/src/helper/build/cacheBust.js

@@ -1,141 +0,0 @@
-// 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;
-}
-
-/**
- * Generate a short content-based hash for a file's contents.
- * Used for per-file cache-busting so that only changed files invalidate caches.
- * @param {string} content - File content to hash
- * @returns {string} Short hex hash (8 chars)
- */
-export function generateFileHash(content) {
-  let hash = 0;
-  for (let i = 0; i < content.length; i++) {
-    const char = content.charCodeAt(i);
-    hash = ((hash << 5) - hash) + char;
-    hash = hash & hash; // Convert to 32-bit integer
-  }
-  return Math.abs(hash).toString(16).padStart(8, "0").substring(0, 8);
-}
-
-/**
- * A cache-bust hash map that stores per-file content hashes.
- * When a static file changes, its hash changes, which invalidates
- * any document referencing it via ?v= query parameters.
- */
-export class CacheBustHashMap {
-  constructor() {
-    /** @type {Map<string, string>} relative file path → content hash */
-    this.hashes = new Map();
-    /** @type {string} fallback timestamp for files not individually tracked */
-    this.fallbackTimestamp = generateCacheBustTimestamp();
-  }
-
-  /**
-   * Update the hash for a file.
-   * @param {string} relativePath - File path relative to output dir (e.g., "campaigns/abs/style.css")
-   * @param {string} content - File content
-   * @returns {string} The new hash
-   */
-  update(relativePath, content) {
-    const hash = generateFileHash(content);
-    this.hashes.set(relativePath, hash);
-    return hash;
-  }
-
-  /**
-   * Get the cache-bust version string for a file.
-   * Returns the per-file hash if available, otherwise the fallback timestamp.
-   * @param {string} relativePath - File path relative to output dir
-   * @returns {string} Version string
-   */
-  getVersion(relativePath) {
-    return this.hashes.get(relativePath) || this.fallbackTimestamp;
-  }
-
-  /**
-   * Check if a file's hash has changed.
-   * @param {string} relativePath
-   * @param {string} content
-   * @returns {boolean} true if the hash differs from the stored value
-   */
-  hasChanged(relativePath, content) {
-    const newHash = generateFileHash(content);
-    const oldHash = this.hashes.get(relativePath);
-    return newHash !== oldHash;
-  }
-
-  /**
-   * Refresh the fallback timestamp (e.g., at the start of a new build).
-   */
-  refreshTimestamp() {
-    this.fallbackTimestamp = generateCacheBustTimestamp();
-  }
-
-  /**
-   * Get the fallback timestamp (for backward compatibility).
-   * @returns {string}
-   */
-  get timestamp() {
-    return this.fallbackTimestamp;
-  }
-}

package/src/helper/build/navCache.js

@@ -1,145 +0,0 @@
-// Navigation cache for build performance
-// Caches the menu structure and only rebuilds when the file list changes
-
-import { readFile, writeFile, mkdir, stat } from 'fs/promises';
-import { existsSync, readFileSync } from 'fs';
-import { join, dirname, extname, basename } from 'path';
-import { createHash } from 'crypto';
-
-const NAV_CACHE_FILE = 'nav-cache.json';
-
-/**
- * Generate a hash of the file list to detect changes
- * @param {string[]} files - Array of file paths
- * @returns {string} Hash of the file list
- */
-export function hashFileList(files) {
-  const sorted = [...files].sort();
-  return createHash('md5').update(sorted.join('\n')).digest('hex').substring(0, 16);
-}
-
-/**
- * Generate a hash of file stats for detecting content changes
- * Uses mtime and size for speed (avoids reading file contents)
- * @param {string[]} files - Array of file paths to check
- * @returns {Promise<string>} Hash of file stats
- */
-export async function hashFileStats(files) {
-  // Only check index files and config files that affect menu generation
-  const relevantFiles = files.filter(f => {
-    const base = basename(f).toLowerCase();
-    return base === 'index.md' || 
-           base === 'index.mdx' ||
-           base === 'index.txt' || 
-           base === 'index.yml' ||
-           base === 'config.json' ||
-           base === 'menu.md' ||
-           base === 'menu.txt' ||
-           base === '_menu.md' ||
-           base === '_menu.txt' ||
-           base.endsWith('-icon.png') ||
-           base.endsWith('-icon.svg') ||
-           base === 'icon.png' ||
-           base === 'icon.svg';
-  }).sort();
-  
-  // Stat files in parallel batches for speed
-  const BATCH_SIZE = 100;
-  const stats = [];
-  
-  for (let i = 0; i < relevantFiles.length; i += BATCH_SIZE) {
-    const batch = relevantFiles.slice(i, i + BATCH_SIZE);
-    const batchResults = await Promise.all(batch.map(async (file) => {
-      try {
-        const s = await stat(file);
-        return `${file}:${s.mtimeMs}:${s.size}`;
-      } catch (e) {
-        return null; // File might not exist
-      }
-    }));
-    stats.push(...batchResults.filter(Boolean));
-  }
-  
-  return createHash('md5').update(stats.join('\n')).digest('hex').substring(0, 16);
-}
-
-/**
- * Load the navigation cache from disk
- * @param {string} sourceDir - Source directory root
- * @returns {Promise<object|null>} Cached nav data or null
- */
-export async function loadNavCache(sourceDir) {
-  const cachePath = join(sourceDir, '.ursa', NAV_CACHE_FILE);
-  try {
-    if (existsSync(cachePath)) {
-      const data = await readFile(cachePath, 'utf8');
-      return JSON.parse(data);
-    }
-  } catch (e) {
-    // Ignore errors
-  }
-  return null;
-}
-
-/**
- * Save the navigation cache to disk
- * @param {string} sourceDir - Source directory root
- * @param {object} cache - Cache data to save
- */
-export async function saveNavCache(sourceDir, cache) {
-  const ursaDir = join(sourceDir, '.ursa');
-  const cachePath = join(ursaDir, NAV_CACHE_FILE);
-  try {
-    await mkdir(ursaDir, { recursive: true });
-    await writeFile(cachePath, JSON.stringify(cache, null, 2));
-  } catch (e) {
-    console.warn('Could not save nav cache:', e.message);
-  }
-}
-
-/**
- * Check if the navigation cache is valid
- * @param {object} cache - The cached data
- * @param {string} fileListHash - Current file list hash
- * @param {string} fileStatsHash - Current file stats hash
- * @returns {boolean} True if cache is valid
- */
-export function isNavCacheValid(cache, fileListHash, fileStatsHash) {
-  if (!cache) return false;
-  if (cache.fileListHash !== fileListHash) return false;
-  if (cache.fileStatsHash !== fileStatsHash) return false;
-  if (!cache.menuData || !cache.menuHtml || !cache.validPaths) return false;
-  return true;
-}
-
-/**
- * Create a cache entry
- * @param {string} fileListHash - Hash of file list
- * @param {string} fileStatsHash - Hash of file stats
- * @param {object} menuData - Menu data structure
- * @param {string} menuHtml - Rendered menu HTML
- * @param {Array} validPathsArray - Valid paths as array of [key, value] pairs
- * @param {Map} customMenus - Custom menus map
- * @returns {object} Cache entry
- */
-export function createNavCacheEntry(fileListHash, fileStatsHash, menuData, menuHtml, validPathsArray, customMenusArray) {
-  return {
-    version: 1,
-    timestamp: Date.now(),
-    fileListHash,
-    fileStatsHash,
-    menuData,
-    menuHtml,
-    validPaths: validPathsArray,
-    customMenus: customMenusArray,
-  };
-}
-
-/**
- * Restore a Map from cached array
- * @param {Array} arr - Array of [key, value] pairs
- * @returns {Map} Restored map
- */
-export function restoreMap(arr) {
-  return new Map(arr);
-}

package/src/helper/build/watchCache.js

@@ -1,33 +0,0 @@
-// Watch mode cache and clear function for build
-
-import { dependencyTracker } from "../dependencyTracker.js";
-
-export const watchModeCache = {
-  templates: null,
-  menu: null,
-  footer: null,
-  validPaths: null,
-  source: null,
-  meta: null,
-  output: null,
-  hashCache: null,
-  cacheBustTimestamp: null,
-  cacheBustHashes: null,   // CacheBustHashMap instance for per-file cache-busting
-  allArticlePaths: null,   // Array of all article paths (for full rebuild tracking)
-  lastFullBuild: 0,
-  isInitialized: false,
-};
-
-export function clearWatchCache(cssPathCache) {
-  watchModeCache.templates = null;
-  watchModeCache.menu = null;
-  watchModeCache.footer = null;
-  watchModeCache.validPaths = null;
-  watchModeCache.hashCache = null;
-  watchModeCache.cacheBustHashes = null;
-  watchModeCache.allArticlePaths = null;
-  watchModeCache.isInitialized = false;
-  dependencyTracker.init("");
-  if (cssPathCache) cssPathCache.clear();
-  console.log('Watch cache cleared');
-}