@kenjura/ursa 0.90.1 → 0.95.0

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/__test__/generateJsonOnly.test.js

@@ -0,0 +1,154 @@
+/**
+ * `generate({ _jsonOnly: true })` — emit the data files and nothing else.
+ *
+ * The load-bearing claim is not "fewer files": it is that the .json a JSON-only
+ * build writes is byte-identical to the one a full build writes. Every step the
+ * mode skips operates on the assembled page, never on the JSON. If that ever
+ * stops being true, `identical to a full build's JSON` fails here rather than
+ * silently shipping different data to a consumer.
+ */
+
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, readFile, rm } from "fs/promises";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import { generate } from "../generate.js";
+import { clearConfigCache } from "../../helper/folderConfig.js";
+
+const META = join(process.cwd(), "meta");
+
+let source;
+let output;
+
+async function doc(relPath, contents) {
+  const full = join(source, relPath);
+  await mkdir(join(full, ".."), { recursive: true });
+  await writeFile(full, contents);
+  return full;
+}
+
+beforeEach(async () => {
+  source = await mkdtemp(join(tmpdir(), "ursa-jsononly-src-"));
+  output = await mkdtemp(join(tmpdir(), "ursa-jsononly-out-"));
+  clearConfigCache();
+
+  await doc("index.md", "# Home\n\nWelcome.\n");
+  await doc(
+    "character/powers/absorb-magic.md",
+    [
+      "---",
+      "class: Witch",
+      "name: Absorb Magic",
+      "school: Antimagic",
+      "brief: Absorb energy from a touched spell",
+      "---",
+      "",
+      "# Absorb Magic",
+      "",
+      "Touch a spell and take it apart.",
+      "",
+      "## Range",
+      "",
+      "Touch.",
+      "",
+    ].join("\n")
+  );
+  await doc("character/powers/mind-blast.md", "# Mind Blast\n\nA blast, of the mind.\n");
+});
+
+afterEach(async () => {
+  await rm(source, { recursive: true, force: true });
+  await rm(output, { recursive: true, force: true });
+});
+
+const run = (opts) =>
+  generate({ _source: source, _meta: META, _output: output, _clean: true, ...opts });
+
+describe("generate --json-only", () => {
+  it("writes the document JSON", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "character/powers/absorb-magic.json"))).toBe(true);
+    expect(existsSync(join(output, "index.json"))).toBe(true);
+  });
+
+  it("writes the directory record lists, which are the point of the mode", async () => {
+    await run({ _jsonOnly: true });
+    const listPath = join(output, "character/powers.json");
+    expect(existsSync(listPath)).toBe(true);
+
+    const records = JSON.parse(await readFile(listPath, "utf8"));
+    const absorb = records.find((r) => r.name === "absorb-magic");
+    expect(absorb).toBeDefined();
+    expect(absorb.url).toBe("/character/powers/absorb-magic.html");
+    expect(absorb.metadata.school).toBe("Antimagic");
+  });
+
+  it("writes no HTML and no XML", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "index.html"))).toBe(false);
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(false);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(false);
+    // The directory listing page, distinct from the record list above.
+    expect(existsSync(join(output, "character/powers.html"))).toBe(false);
+  });
+
+  it("writes no meta assets, search index, menu data or recent activity", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "public", "search-index.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "fulltext-index.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "menu-data.json"))).toBe(false);
+    expect(existsSync(join(output, "public", "recent-activity.json"))).toBe(false);
+  });
+
+  it("produces JSON identical to a full build's", async () => {
+    await run({ _jsonOnly: true });
+    const jsonOnly = await readFile(
+      join(output, "character/powers/absorb-magic.json"),
+      "utf8"
+    );
+    const jsonOnlyList = await readFile(join(output, "character/powers.json"), "utf8");
+
+    await rm(output, { recursive: true, force: true });
+    await mkdir(output, { recursive: true });
+    await run({ _jsonOnly: false });
+
+    const full = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+    const fullList = await readFile(join(output, "character/powers.json"), "utf8");
+
+    expect(jsonOnly).toBe(full);
+    expect(jsonOnlyList).toBe(fullList);
+  });
+
+  it("still emits everything on a normal build", async () => {
+    await run({ _jsonOnly: false });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(true);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(true);
+    expect(existsSync(join(output, "public", "menu-data.json"))).toBe(true);
+  });
+});
+
+describe("mixing modes against one source tree", () => {
+  // The hash cache lives in the SOURCE tree and is shared by both modes, so the
+  // per-document output check has to be mode-aware or one mode's cache entries
+  // would convince the other that its own missing outputs are up to date.
+
+  it("a full build after a JSON-only build still writes the HTML", async () => {
+    await run({ _jsonOnly: true });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(false);
+
+    // Warm: no --clean, so the hash cache from the JSON-only run is in play.
+    await generate({ _source: source, _meta: META, _output: output, _jsonOnly: false });
+    expect(existsSync(join(output, "character/powers/absorb-magic.html"))).toBe(true);
+    expect(existsSync(join(output, "character/powers/absorb-magic.xml"))).toBe(true);
+  });
+
+  it("a JSON-only build after a full build leaves the JSON in place", async () => {
+    await run({ _jsonOnly: false });
+    const before = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+
+    await generate({ _source: source, _meta: META, _output: output, _jsonOnly: true });
+    const after = await readFile(join(output, "character/powers/absorb-magic.json"), "utf8");
+
+    expect(after).toBe(before);
+  });
+});