@kenjura/ursa 0.93.0 → 0.96.0

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

@@ -0,0 +1,159 @@
+import { join } from 'path';
+import { mkdtemp, writeFile, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { renderMDX, generateHydrationScript } from '../mdxRenderer.js';
+
+// Helper: a temp source tree with a _components/ directory
+let tempDir;
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'ursa-mdx-'));
+  await mkdir(join(tempDir, '_components'), { recursive: true });
+});
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+async function writeComponent(name, body) {
+  const path = join(tempDir, '_components', `${name}.jsx`);
+  await writeFile(path, body);
+  return path;
+}
+
+async function render(mdx, { hydrate = true } = {}) {
+  const filePath = join(tempDir, 'page.mdx');
+  await writeFile(filePath, mdx);
+  return renderMDX({ source: mdx, filePath, sourceRoot: tempDir, hydrate });
+}
+
+const COUNTER = `
+import React from 'react';
+export default function Counter({ label }) {
+  const [n, setN] = React.useState(0);
+  return <button onClick={() => setN(n + 1)}>{label}: {n}</button>;
+}
+`;
+
+// ---------------------------------------------------------------------------
+// Island wrapping
+// ---------------------------------------------------------------------------
+describe('renderMDX islands', () => {
+  test('wraps a component imported from the MDX in <ursa-island>', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+# Page
+
+<Counter label="Clicks" />
+`);
+    expect(html).toMatch(/<ursa-island data-island="0" data-component="Counter"[^>]*>/);
+    expect(html).toContain('<button>Clicks<!-- -->: <!-- -->0</button>');
+    expect(html).toContain('</ursa-island>');
+  });
+
+  test('numbers islands in document order', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="A" />
+
+Some prose.
+
+<Counter label="B" />
+`);
+    const ids = [...html.matchAll(/<ursa-island data-island="(\d+)"/g)].map((m) => m[1]);
+    expect(ids).toEqual(['0', '1']);
+    expect(html.indexOf('>A<')).toBeLessThan(html.indexOf('>B<'));
+  });
+
+  test('does not nest islands: a component imported by a component is rendered plainly', async () => {
+    await writeComponent('Inner', `
+import React from 'react';
+export default function Inner() { return <em>inner</em>; }
+`);
+    await writeComponent('Outer', `
+import React from 'react';
+import Inner from './Inner.jsx';
+export default function Outer() { return <div>outer <Inner /></div>; }
+`);
+    const { html } = await render(`
+import Outer from '_components/Outer.jsx';
+
+<Outer />
+`);
+    expect(html.match(/<ursa-island/g)).toHaveLength(1);
+    expect(html).toContain('data-component="Outer"');
+    expect(html).toContain('<em>inner</em>');
+  });
+
+  test('leaves the surrounding markdown outside any island', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { html } = await render(`
+import Counter from '_components/Counter.jsx';
+
+# Heading
+
+<Counter label="x" />
+
+## Sub
+`);
+    // Headings are siblings of the island, not children of it
+    expect(html).toMatch(/<h1>Heading<\/h1>\s*<ursa-island/);
+    expect(html).toMatch(/<\/ursa-island>\s*<h2>Sub<\/h2>/);
+  });
+
+  test('client bundle contains the island runtime', async () => {
+    await writeComponent('Counter', COUNTER);
+    const { clientCode } = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="x" />
+`);
+    expect(clientCode).toContain('hydrateRoot');
+    expect(clientCode).toContain('data-island');
+  });
+
+  test('hydrate: false still renders islands but emits no client code', async () => {
+    await writeComponent('Counter', COUNTER);
+    const result = await render(`
+import Counter from '_components/Counter.jsx';
+
+<Counter label="x" />
+`, { hydrate: false });
+    expect(result.html).toContain('<ursa-island');
+    expect(result.clientCode).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Preload stripping
+// ---------------------------------------------------------------------------
+describe('renderMDX preload stripping', () => {
+  test('removes React 19 hoisted <link rel="preload"> so the body starts with its heading', async () => {
+    const { html } = await render(`
+# Title
+![pic](../img/pic.jpg)
+`);
+    expect(html).not.toContain('rel="preload"');
+    expect(html.trimStart().startsWith('<h1>')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Hydration script
+// ---------------------------------------------------------------------------
+describe('generateHydrationScript', () => {
+  test('renders into a detached root and looks up islands rather than a page container', () => {
+    const script = generateHydrationScript('return { default: function () { return null; } };');
+    expect(script).toContain('ursa-island[data-island]');
+    expect(script).toContain('createRoot(detached)');
+    expect(script).not.toContain("getElementById('main-content')");
+  });
+
+  test('escapes the bundle for embedding in a template literal', () => {
+    const script = generateHydrationScript('var s = `a${b}`; // </script>');
+    expect(script).toContain('\\`a\\${b}\\`');
+    expect(script).toContain('<\\/script>');
+  });
+});

package/src/helper/automenu.js

@@ -218,8 +218,10 @@ function buildMenuData(tree, source, validPaths, parentPath = '', includeDebug =
       }
     }
     
-    // Check if this folder is hidden via config.json
-    if (hasChildren && isFolderHidden(item.path, source)) {
+    // Check if this folder is hidden via config.json.
+    // Not gated on hasChildren: a hidden folder is ignored whether or not the
+    // tree walker found children under it.
+    if (isFolderHidden(item.path, source)) {
       continue; // Skip hidden folders
     }
     

package/src/helper/build/__test__/autoIndex.test.js

@@ -3,6 +3,7 @@ import { mkdtemp, mkdir, writeFile, rm, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { tmpdir } from "os";
 import { generateAutoIndices, generateAutoIndexHtmlFromSource } from "../autoIndex.js";
+import { clearConfigCache } from "../../folderConfig.js";
 
 let tempDir;
 let source;
@@ -160,3 +161,69 @@ describe("auto-index naming matches the automenu", () => {
     expect(rootIndex).toContain('<a href="bnw/index.html">BNW - Brave New World</a>');
   });
 });
+
+describe("folders ignored via config.json { hidden: true }", () => {
+  beforeEach(() => {
+    // getFolderConfig memoizes per absolute path; temp dirs are unique per
+    // test, but clearing keeps the cache from growing across the suite.
+    clearConfigCache();
+  });
+
+  it("omits a hidden folder from an auto-index built from source", async () => {
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await writeFile(join(source, "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("_art");
+    expect(html).not.toContain("prompts");
+  });
+
+  it("omits a hidden folder even when stale output for it still exists", async () => {
+    // A folder generated before it was hidden leaves files behind in output.
+    // The listing is built from output, so without a source-side check the
+    // hidden folder would reappear in the index.
+    await mkdir(join(source, "_art"), { recursive: true });
+    await writeFile(join(source, "_art", "config.json"), JSON.stringify({ hidden: true }));
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    await mkdir(join(output, "_art"), { recursive: true });
+    await writeFile(join(output, "_art", "prompts.html"), "<html><body>stale</body></html>");
+    await mkdir(join(output, "people"), { recursive: true });
+    await writeFile(join(output, "people", "alice.html"), "<html><body>Alice</body></html>");
+
+    const progress = makeProgress();
+    await runAutoIndices(
+      [source, join(source, "people")],
+      [join(source, "people", "alice.md")],
+      progress
+    );
+
+    const index = await readFile(join(output, "index.html"), "utf8");
+    expect(index).toContain("people");
+    expect(index).not.toContain("_art");
+  });
+
+  it("does not count documents inside a hidden subfolder when deciding a folder has content", async () => {
+    // `notes` holds nothing but a hidden subfolder, so it produces no pages
+    // and must not be linked as though it did.
+    await mkdir(join(source, "notes", "_art"), { recursive: true });
+    await writeFile(
+      join(source, "notes", "_art", "config.json"),
+      JSON.stringify({ hidden: true })
+    );
+    await writeFile(join(source, "notes", "_art", "prompts.md"), "# Prompts\n");
+    await mkdir(join(source, "people"), { recursive: true });
+    await writeFile(join(source, "people", "alice.md"), "# Alice\n");
+
+    const html = await generateAutoIndexHtmlFromSource(source, 2);
+
+    expect(html).toContain("people");
+    expect(html).not.toContain("notes");
+  });
+});

package/src/helper/build/autoIndex.js

@@ -8,7 +8,7 @@ import { findAllScriptJs } from "../findScriptJs.js";
 import { addTimestampToHtmlStaticRefs } from "./cacheBust.js";
 import { isMetadataOnly, extractMetadata, getAutoIndexConfig } from "../metadataExtractor.js";
 import { getCustomMenuForFile } from "./menu.js";
-import { getFolderConfig } from "../folderConfig.js";
+import { getFolderConfig, isFolderSelfHidden } from "../folderConfig.js";
 import {
   toDisplayName,
   getFolderLabel,
@@ -26,11 +26,18 @@ const OUTPUT_DOC_EXTENSIONS = ['.html'];
 
 /**
  * Recursively check if a directory contains any document files.
+ *
+ * Documents inside a config-hidden subfolder do not count: they produce no
+ * output, so a folder whose only contents are hidden must not be linked as if
+ * it had pages. When `dir` is an output directory, pass the matching source
+ * directory as `sourceDir` — the config.json lives in the source tree.
+ *
  * @param {string} dir - Directory path to check
  * @param {string[]} extensions - File extensions that count as documents
+ * @param {string|null} [sourceDir=dir] - Matching source directory, for hidden lookups
  * @returns {Promise<boolean>} True if the directory (or any subdirectory) contains at least one document
  */
-async function directoryHasDocuments(dir, extensions) {
+async function directoryHasDocuments(dir, extensions, sourceDir = dir) {
   try {
     const children = await readdir(dir, { withFileTypes: true });
     for (const child of children) {
@@ -38,7 +45,9 @@ async function directoryHasDocuments(dir, extensions) {
       const fullPath = join(dir, child.name);
       if (child.isDirectory()) {
         if (child.name === 'img') continue;
-        if (await directoryHasDocuments(fullPath, extensions)) return true;
+        if (sourceDir && isFolderSelfHidden(join(sourceDir, child.name))) continue;
+        const childSource = sourceDir ? join(sourceDir, child.name) : null;
+        if (await directoryHasDocuments(fullPath, extensions, childSource)) return true;
       } else {
         const ext = extname(child.name).toLowerCase();
         if (extensions.includes(ext)) return true;
@@ -111,6 +120,9 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
         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');
       })
@@ -131,7 +143,8 @@ export async function generateAutoIndexHtml(dir, depth = 1, currentDepth = 0, pa
       // Skip directories that contain no documents
       if (isDir) {
         const childDir = join(dir, child.name);
-        if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+        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;
@@ -186,6 +199,8 @@ export async function generateAutoIndexHtmlFromSource(sourceDir, depth = 1, curr
         if (child.name.match(/^index\.(md|mdx|txt|yml|html)$/i)) return false;
         // Skip img folders (contain images, not content)
         if (child.isDirectory() && child.name === 'img') 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 article files (md, mdx, txt, yml, html)
         return child.isDirectory() || child.name.match(/\.(md|mdx|txt|yml|html)$/i);
       })
@@ -362,6 +377,8 @@ export async function generateAutoIndices(output, directories, source, templates
             // 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');
           })
@@ -377,7 +394,7 @@ export async function generateAutoIndices(output, directories, source, templates
         for (const { child, isDir, label } of filteredItems) {
           if (isDir) {
             const childDir = join(dir, child.name);
-            if (!await directoryHasDocuments(childDir, OUTPUT_DOC_EXTENSIONS)) continue;
+            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;

package/src/helper/folderConfig.js

@@ -11,9 +11,16 @@ const configCache = new Map();
  * {
  *   label?: string,       // Custom label for menu display
  *   icon?: string,        // URL to icon image for menu
- *   hidden?: boolean,     // If true, hide from menu and don't generate files
+ *   hidden?: boolean,     // If true, ignore the folder entirely (see below)
  *   openMenuItems?: string[]  // (root only) Array of folder names to expand by default
  * }
+ * 
+ * `hidden: true` means *ignored*, not merely unlisted. The folder and its
+ * whole subtree take no part in the build: no HTML is rendered from its
+ * documents, its images and other static assets are not copied, it does not
+ * appear in the sidebar menu, in any auto-index, in breadcrumbs, or in the
+ * search index, and `ursa serve` will not render its pages on demand. The
+ * files stay in the docroot; the site behaves as if they were not there.
  */
 
 /**
@@ -60,10 +67,33 @@ export function getRootConfig(sourceRoot) {
 }
 
 /**
- * Check if a folder or any of its ancestors is hidden via config.json
- * @param {string} folderPath - Absolute path to check
+ * True when this exact folder's own config.json says `hidden: true`, ignoring
+ * its ancestors.
+ *
+ * Use this where the ancestors have already been ruled out — walking a tree
+ * top-down, say, where reaching a node means every folder above it was
+ * visible. It needs no docroot, which is what makes it usable in the
+ * auto-index builders, where only the folder being listed is known.
+ *
+ * @param {string} folderPath - Absolute path to a folder
+ * @returns {boolean} True if that folder is marked hidden
+ */
+export function isFolderSelfHidden(folderPath) {
+  return getFolderConfig(folderPath.replace(/\/$/, ''))?.hidden === true;
+}
+
+/**
+ * Check if a path lies in a folder — its own, or any ancestor up to the
+ * docroot — that config.json marks `hidden: true`.
+ *
+ * Accepts file paths as well as directories: the walk starts at `folderPath`
+ * itself, and a file simply has no config.json of its own, so the first step
+ * misses and the ancestors decide. That is what lets the build filter a mixed
+ * list of files and directories through one predicate.
+ *
+ * @param {string} folderPath - Absolute path to check (file or directory)
  * @param {string} sourceRoot - The source root directory (stop checking at this level)
- * @returns {boolean} True if this folder should be hidden
+ * @returns {boolean} True if this path should be ignored
  */
 export function isFolderHidden(folderPath, sourceRoot) {
   let currentPath = folderPath.replace(/\/$/, '');