@kenjura/ursa 0.90.0 → 0.93.0

package/src/helper/build/autoIndex.js

@@ -5,10 +5,18 @@ import { basename, dirname, extname, join } from "path";
 import { outputFile } from "fs-extra";
 import { findStyleCss, findAllStyleCss } from "../findStyleCss.js";
 import { findAllScriptJs } from "../findScriptJs.js";
-import { toTitleCase } from "./titleCase.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
 import { getCustomMenuForFile } from "./menu.js";
+import { getFolderConfig } from "../folderConfig.js";
+import {
+  toDisplayName,
+  getFolderLabel,
+  getFolderSortKey,
+  getMenuSortAsFromFile,
+  getFileLabel,
+  findSourceDocument,
+} from "../menuLabels.js";
 import { generateBreadcrumbs } from "../breadcrumbs.js";
 import { bundleDocumentCss, bundleDocumentJs } from "../assetBundler.js";
 
@@ -40,6 +48,44 @@ async function directoryHasDocuments(dir, extensions) {
   return false;
 }
 
+/**
+ * Resolve the label and sort key for one auto-index entry, using the same
+ * rules as the site-wide automenu: `menu-label` frontmatter wins, then
+ * config.json `label` for folders, then the prettified file/folder name.
+ *
+ * @param {boolean} isDir - Whether the entry is a directory
+ * @param {string} baseName - Name without extension
+ * @param {string|null} sourceDir - Source directory holding this entry, if known
+ * @returns {{label: string, sortKey: string}}
+ */
+function resolveEntryNaming(isDir, baseName, sourceDir) {
+  if (!sourceDir) {
+    return { label: toDisplayName(baseName), sortKey: baseName };
+  }
+  if (isDir) {
+    const childDir = join(sourceDir, baseName);
+    return {
+      label: getFolderLabel(childDir, getFolderConfig(childDir), baseName),
+      sortKey: getFolderSortKey(childDir) || baseName,
+    };
+  }
+  const sourceFile = findSourceDocument(sourceDir, baseName);
+  return {
+    label: getFileLabel(sourceFile, baseName),
+    sortKey: (sourceFile && getMenuSortAsFromFile(sourceFile)) || baseName,
+  };
+}
+
+/**
+ * Sort auto-index entries the way the automenu does: folders first, then by
+ * sort key (case-insensitive).
+ */
+function compareEntries(a, b) {
+  if (a.isDir && !b.isDir) return -1;
+  if (!a.isDir && b.isDir) return 1;
+  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)
@@ -47,9 +93,12 @@ async function directoryHasDocuments(dir, extensions) {
  * @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 = '') {
+export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pathPrefix = '', sourceDir = null) {
   try {
     const children = await readdir(dir, { withFileTypes: true });
     
@@ -65,12 +114,12 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
         // Include directories and html files
         return child.isDirectory() || child.name.endsWith('.html');
       })
-      .sort((a, b) => {
-        // Directories first, then files, alphabetically within each group
-        if (a.isDirectory() && !b.isDirectory()) return -1;
-        if (!a.isDirectory() && b.isDirectory()) return 1;
-        return a.name.localeCompare(b.name);
-      });
+      .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 '';
@@ -78,26 +127,26 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
     
     const items = [];
     
-    for (const child of filteredChildren) {
-      const isDir = child.isDirectory();
+    for (const { child, isDir, label } of filteredChildren) {
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(dir, child.name);
         if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
       }
-      const name = isDir ? child.name : child.name.replace('.html', '');
       // 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 displayName = toTitleCase(name);
       const icon = isDir ? '📁' : '📄';
       
-      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      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);
+        const childHtml = await generateAutoIndexHtml(
+          childDir, depth, currentDepth + 1, childPath,
+          sourceDir ? join(sourceDir, child.name) : null
+        );
         if (childHtml) {
           itemHtml += `\n${childHtml}`;
         }
@@ -140,12 +189,12 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         // Include directories and article files (md, mdx, txt, yml, html)
         return child.isDirectory() || child.name.match(/\.(md|mdx|txt|yml|html)$/i);
       })
-      .sort((a, b) => {
-        // Directories first, then files, alphabetically within each group
-        if (a.isDirectory() && !b.isDirectory()) return -1;
-        if (!a.isDirectory() && b.isDirectory()) return 1;
-        return a.name.localeCompare(b.name);
-      });
+      .map(child => {
+        const isDir = child.isDirectory();
+        const baseName = isDir ? child.name : basename(child.name, extname(child.name));
+        return { child, isDir, baseName, ...resolveEntryNaming(isDir, baseName, sourceDir) };
+      })
+      .sort(compareEntries);
     
     if (filteredChildren.length === 0) {
       return '';
@@ -153,24 +202,19 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
     
     const items = [];
     
-    for (const child of filteredChildren) {
-      const isDir = child.isDirectory();
+    for (const { child, isDir, baseName, label } of filteredChildren) {
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(sourceDir, child.name);
         if (!await directoryHasDocuments(childDir, SOURCE_DOC_EXTENSIONS)) continue;
       }
-      // Get name without extension for display
-      const ext = isDir ? '' : extname(child.name);
-      const nameWithoutExt = isDir ? child.name : basename(child.name, ext);
       // Generate href - directories link to folder/index.html, files convert to .html
       // 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 + '/' : ''}${nameWithoutExt}.html`;
-      const displayName = toTitleCase(nameWithoutExt);
+      const href = isDir ? `${childPath}/index.html` : `${pathPrefix ? pathPrefix + '/' : ''}${baseName}.html`;
       const icon = isDir ? '📁' : '📄';
       
-      let itemHtml = `<li>${icon} <a href="${href}">${displayName}</a>`;
+      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) {
@@ -313,28 +357,32 @@ export async function generateAutoIndices(output, directories, source, templates
         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;
-          // Include directories and html files
-          return child.isDirectory() || child.name.endsWith('.html');
-        });
+        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;
+            // 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 of filteredItems) {
-          const isDir = child.isDirectory();
+        for (const { child, isDir, label } of filteredItems) {
           if (isDir) {
             const childDir = join(dir, child.name);
             if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
           }
-          const name = isDir ? child.name : child.name.replace('.html', '');
           // For directories, link to /folder/index.html; for files, use the filename directly
           const href = isDir ? `${child.name}/index.html` : child.name;
-          const displayName = toTitleCase(name);
           const icon = isDir ? '📁' : '📄';
-          items.push(`<li>${icon} <a href="${href}">${displayName}</a></li>`);
+          items.push(`<li>${icon} <a href="${href}">${label}</a></li>`);
         }
         
         if (items.length === 0) {
@@ -342,12 +390,16 @@ export async function generateAutoIndices(output, directories, source, templates
           continue;
         }
         
-        const folderDisplayName = dir === outputNorm ? 'Home' : toTitleCase(folderName);
+        // 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);
+        const breadcrumbHtml = generateBreadcrumbs(breadcrumbDir, 'index', null, sourceNorm);
 
         const indexHtml = `${breadcrumbHtml}<h1>${folderDisplayName}</h1>\n<ul class="auto-index">\n${items.join('\n')}\n</ul>`;
         

package/src/helper/build/ursaMetadata.js

@@ -1,27 +1,8 @@
 // Helper for building the _ursa_metadata field embedded in generated JSON files
 import { existsSync } from "fs";
 import { readFile } from "fs/promises";
-import { dirname, join, resolve } from "path";
-import { URL } from "url";
-
-/**
- * Read the ursa version from ursa's own package.json
- * @returns {Promise<string>} The ursa version, or 'unknown' if it can't be read
- */
-async function getUrsaVersion() {
-  try {
-    // From src/helper/build/ursaMetadata.js, go up to the package root
-    const currentDir = dirname(new URL(import.meta.url).pathname);
-    const ursaPackagePath = resolve(currentDir, "..", "..", "..", "package.json");
-    if (existsSync(ursaPackagePath)) {
-      const ursaPackage = JSON.parse(await readFile(ursaPackagePath, "utf8"));
-      if (ursaPackage.version) return ursaPackage.version;
-    }
-  } catch (e) {
-    console.error(`Error reading ursa package.json: ${e.message}`);
-  }
-  return "unknown";
-}
+import { join, resolve } from "path";
+import { getUrsaVersion } from "../ursaVersion.js";
 
 /**
  * Read the documentation repo version from its package.json.
@@ -54,9 +35,5 @@ async function getDocVersion(_source) {
  * @returns {Promise<{ursaVersion: string, docVersion: string}>}
  */
 export async function getUrsaMetadata(_source) {
-  const [ursaVersion, docVersion] = await Promise.all([
-    getUrsaVersion(),
-    getDocVersion(_source),
-  ]);
-  return { ursaVersion, docVersion };
+  return { ursaVersion: getUrsaVersion(), docVersion: await getDocVersion(_source) };
 }

package/src/helper/contentHash.js

@@ -1,10 +1,12 @@
 import { createHash } from 'crypto';
-import { readFile, writeFile, mkdir } from 'fs/promises';
+import { readFile, writeFile, mkdir, rm } from 'fs/promises';
 import { existsSync } from 'fs';
 import { dirname, join } from 'path';
+import { getUrsaVersion } from './ursaVersion.js';
 
 const URSA_DIR = '.ursa';
 const HASH_CACHE_FILE = 'content-hashes.json';
+const CACHE_STAMP_FILE = 'cache-stamp.json';
 
 /**
  * Get the path to the .ursa directory for a given source directory
@@ -13,6 +15,57 @@ export function getUrsaDir(sourceDir) {
   return join(sourceDir, URSA_DIR);
 }
 
+/**
+ * Stamp `.ursa/` with the running ursa version, discarding the whole directory
+ * first if it was written by a different one.
+ *
+ * Hash-skipping compares *source* content only. It says nothing about the code
+ * that turned that source into output, so a cache warmed by an older ursa keeps
+ * whole documents from being re-rendered even after the templates, renderers and
+ * asset bundles that produced them have changed — the symptom users hit as
+ * "I had to run --clean again". Run this before loading any cache.
+ *
+ * On a first build there is nothing to discard, and `reset` is false.
+ *
+ * @param {string} sourceDir - Source directory root
+ * @param {string} [version] - Version to stamp with; defaults to ursa's own
+ * @returns {Promise<{reset: boolean, previous: string|null, version: string}>}
+ */
+export async function enforceCacheVersion(sourceDir, version = getUrsaVersion()) {
+  const ursaDir = getUrsaDir(sourceDir);
+  const stampPath = join(ursaDir, CACHE_STAMP_FILE);
+
+  let previous = null;
+  try {
+    if (existsSync(stampPath)) {
+      const stamp = JSON.parse(await readFile(stampPath, 'utf8'));
+      previous = typeof stamp?.ursaVersion === 'string' ? stamp.ursaVersion : null;
+    }
+  } catch (e) {
+    // An unreadable stamp tells us nothing about what wrote the cache, so treat
+    // it the same as a mismatch rather than trusting the caches beside it.
+    previous = null;
+  }
+
+  if (previous === version) return { reset: false, previous, version };
+
+  // A cache directory with no stamp predates stamping (or was hand-edited);
+  // either way its contents were not written by this ursa.
+  const hadCache = existsSync(ursaDir);
+  if (hadCache) await rm(ursaDir, { recursive: true, force: true });
+
+  try {
+    await mkdir(ursaDir, { recursive: true });
+    await writeFile(stampPath, JSON.stringify({ ursaVersion: version }, null, 2));
+  } catch (e) {
+    // A cache we cannot stamp is a cache we will discard again next run:
+    // correct, just slower. Not worth failing the build over.
+    console.warn('Could not write cache stamp:', e.message);
+  }
+
+  return { reset: hadCache, previous, version };
+}
+
 /**
  * Generate a short hash of content
  */

package/src/helper/menuLabels.js

@@ -0,0 +1,136 @@
+/*
+ * Shared menu label/sort-key resolution.
+ *
+ * Both the site-wide automenu (helper/automenu.js) and the per-folder
+ * auto-index listings (helper/build/autoIndex.js) name the same folders and
+ * documents, so they must agree on what those things are called. Keeping the
+ * resolution rules here is what makes `menu-label: 'BNW - Brave New World'`
+ * show up in both places instead of only in the sidebar.
+ */
+import { existsSync, readFileSync } from "fs";
+import { basename, extname, join } from "path";
+import { extractMetadata } from "./metadataExtractor.js";
+import { stripHtml } from "./stripHtml.js";
+
+// Index file extensions to check for folder metadata
+export const INDEX_EXTENSIONS = ['.md', '.mdx', '.txt', '.yml', '.yaml'];
+
+// Source extensions a rendered .html page can have come from
+export const SOURCE_DOC_EXTENSIONS = ['.md', '.mdx', '.txt', '.yml', '.yaml', '.html'];
+
+/**
+ * Convert filename to display name (e.g., "foo-bar" -> "Foo Bar").
+ * Unlike toTitleCase, this preserves interior capitalization, so a folder
+ * named "SoL" stays "SoL" rather than becoming "Sol".
+ */
+export function toDisplayName(filename) {
+  return filename
+    .replace(/[-_]/g, ' ')  // Replace dashes and underscores with spaces
+    .replace(/\b\w/g, c => c.toUpperCase());  // Capitalize first letter of each word
+}
+
+/**
+ * Read a single frontmatter key from a file, with HTML stripped.
+ * @param {string} filePath - Path to the source file
+ * @param {string} key - Frontmatter key to read
+ * @returns {string|null} The value, or null if absent/unreadable
+ */
+function getFrontmatterString(filePath, key) {
+  try {
+    if (!existsSync(filePath)) return null;
+    const content = readFileSync(filePath, 'utf8');
+    const metadata = extractMetadata(content);
+    if (metadata && metadata[key]) {
+      return stripHtml(String(metadata[key]));
+    }
+  } catch (e) {
+    // Ignore read errors
+  }
+  return null;
+}
+
+/**
+ * Get the menu label from a file's frontmatter
+ * @param {string} filePath - Path to the markdown file
+ * @returns {string|null} The menu-label value (with HTML stripped), or null if not found
+ */
+export function getMenuLabelFromFile(filePath) {
+  return getFrontmatterString(filePath, 'menu-label');
+}
+
+/**
+ * Get the menu-sort-as value from a file's frontmatter
+ * @param {string} filePath - Path to the markdown file
+ * @returns {string|null} The menu-sort-as value (with HTML stripped), or null if not found
+ */
+export function getMenuSortAsFromFile(filePath) {
+  return getFrontmatterString(filePath, 'menu-sort-as');
+}
+
+/**
+ * Get the menu label for a folder from its index.md frontmatter
+ * Falls back to config.json label (deprecated), then display name
+ * @param {string} dirPath - Path to the folder
+ * @param {object|null} folderConfig - The folder's config.json if any
+ * @param {string} baseName - The folder's base name
+ * @returns {string} The label to display
+ */
+export function getFolderLabel(dirPath, folderConfig, baseName) {
+  // First, check index.md for menu-label (preferred method)
+  for (const ext of INDEX_EXTENSIONS) {
+    const indexPath = join(dirPath, `index${ext}`);
+    const label = getMenuLabelFromFile(indexPath);
+    if (label) return label;
+  }
+
+  // Fall back to config.json label (deprecated)
+  if (folderConfig?.label) {
+    return folderConfig.label;
+  }
+
+  // Default to display name from folder name
+  return toDisplayName(baseName);
+}
+
+/**
+ * Get the sort key for a folder from its index.md frontmatter
+ * @param {string} dirPath - Path to the folder
+ * @returns {string|null} The menu-sort-as value, or null if not found
+ */
+export function getFolderSortKey(dirPath) {
+  for (const ext of INDEX_EXTENSIONS) {
+    const indexPath = join(dirPath, `index${ext}`);
+    const sortKey = getMenuSortAsFromFile(indexPath);
+    if (sortKey) return sortKey;
+  }
+  return null;
+}
+
+/**
+ * Locate the source document that produced (or would produce) a page.
+ * Auto-index listings built from the OUTPUT folder only see "foo.html"; this
+ * finds the "foo.md" it came from so its frontmatter can be read.
+ * @param {string} dir - Source directory to look in
+ * @param {string} baseName - File name without extension
+ * @returns {string|null} Path to the source document, or null if none exists
+ */
+export function findSourceDocument(dir, baseName) {
+  if (!dir) return null;
+  for (const ext of SOURCE_DOC_EXTENSIONS) {
+    const candidate = join(dir, `${baseName}${ext}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Get the menu label for a single document.
+ * @param {string|null} filePath - Path to the source document (may be null)
+ * @param {string} [baseName] - Fallback name; defaults to the file's base name
+ * @returns {string} The label to display
+ */
+export function getFileLabel(filePath, baseName) {
+  const fallback = baseName ?? (filePath ? basename(filePath, extname(filePath)) : '');
+  if (!filePath) return toDisplayName(fallback);
+  return getMenuLabelFromFile(filePath) || toDisplayName(fallback);
+}

package/src/helper/ursaVersion.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+let cached = null;
+
+/**
+ * Read ursa's own version from the package.json that ships with it.
+ * Memoised — it cannot change while the process runs.
+ * @returns {string} The version, or 'unknown' if it can't be read
+ */
+export function getUrsaVersion() {
+  if (cached) return cached;
+  try {
+    // From src/helper/ursaVersion.js, go up to the package root
+    const currentDir = dirname(fileURLToPath(import.meta.url));
+    const ursaPackagePath = resolve(currentDir, "..", "..", "package.json");
+    if (existsSync(ursaPackagePath)) {
+      const ursaPackage = JSON.parse(readFileSync(ursaPackagePath, "utf8"));
+      if (ursaPackage.version) return (cached = ursaPackage.version);
+    }
+  } catch (e) {
+    console.error(`Error reading ursa package.json: ${e.message}`);
+  }
+  return (cached = "unknown");
+}

package/src/jobs/generate.js

@@ -21,6 +21,7 @@ import {
   outputsExist,
   updateHash,
   getUrsaDir,
+  enforceCacheVersion,
 } from "../helper/contentHash.js";
 import {
   buildValidPaths,
@@ -168,7 +169,20 @@ export async function generate({
     progress.logTimed(`Clean build: clearing output directory ${output}`);
     await emptyDir(output);
     progress.logTimed(`Clean complete [${progress.stopTimer('Clean')}]`);
-  } else {
+  }
+
+  // Stamp the cache with ursa's version, discarding it if a different ursa
+  // wrote it. Hash-skipping only compares source content, so without this an
+  // upgrade leaves every unchanged document frozen at whatever the previous
+  // version's templates and renderers produced.
+  const cacheStamp = await enforceCacheVersion(source);
+  if (cacheStamp.reset) {
+    progress.logTimed(
+      `Cache discarded: written by ursa ${cacheStamp.previous ?? '(unstamped)'}, now running ${cacheStamp.version}`
+    );
+  }
+
+  if (!_clean) {
     // Warm start: reload persisted dependency registrations so hash-skipped
     // documents keep their edges (current-run registrations take precedence)
     const loaded = await loadDependencyTracker(source);
@@ -734,7 +748,7 @@ export async function generate({
       }
 
       // Inject breadcrumbs before the H1
-      const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta);
+      const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta, source);
       if (breadcrumbs) {
         body = breadcrumbs + body;
       }
@@ -1552,7 +1566,7 @@ export async function regenerateSingleFile(changedFile, {
     }
 
     // Inject breadcrumbs before the H1
-    const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta);
+    const breadcrumbs = generateBreadcrumbs(dir, base, fileMeta, source);
     if (breadcrumbs) {
       body = breadcrumbs + body;
     }