@kenjura/ursa 0.86.0 → 0.87.1

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.87.1
+2026-06-15
+
+- nothing
+
+# 0.87.0
+2026-06-11
+
+- Added support for definition lists in Markdown/MDX documents, allowing for structured term-definition pairs to be rendered as HTML definition lists (<dl>, <dt>, <dd>).
+- Added response headers for json files with the ursa and doc repo version numbers, so consumers can invalidate caches when a new version is deployed.
+
+
+## Serve Revamp (Phases 0–1)
+
+`ursa serve` could miss cascading updates — stylesheet edits, static files in `meta/`, template changes, and any change saved while a rebuild was already running — forcing a restart with `--clean`. This release ships the first two phases of the rework; design, root-cause analysis, and remaining TODOs: [docs/changes/serve-logic.md](docs/changes/serve-logic.md).
+
+- **Serve-mode reliability fixes (Phase 0):**
+  - Static assets in `meta/` (images, fonts, PDFs, media) are now watched; replacing one re-copies it to output and reloads clients, without a full rebuild. Previously these changes were invisible until restart.
+  - Changes saved while a regeneration is in flight are queued and processed when the current pass finishes, instead of being dropped with "changes lost".
+  - Every full-rebuild path now deletes `content-hashes.json` and `nav-cache.json` first, so a rebuild after a template/meta change actually regenerates unchanged articles instead of hash-skipping them and leaving stale HTML.
+  - The dependency tracker is persisted to `.ursa/dependency-graph.json` and reloaded on warm start, so hash-skipped documents keep their invalidation edges. Single-file regeneration now registers dependencies too, and template edits are recognized under the `templates/{name}/index.html` folder structure — a template edit on a warm start is now a selective rebuild of just the documents using that template.
+- **New incremental build engine (Phase 1):** `src/helper/build/graph.js` — a fingerprinted dependency graph (Make/Shake-style) with dynamic dependency discovery (`ctx.read`/`ctx.exists`/`ctx.get`), lookup nodes so file *creation* invalidates, size+mtime fast-path fingerprinting with content-hash confirmation, early cutoff, topological demand-driven scheduling, failure isolation with retry, and versioned persistence to `.ursa/graph.json`. Fully unit-tested; the build/serve pipelines will be ported onto it in the next phases (2–4).
+
 # 0.86.0
 2026-05-18
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.86.0",
+  "version": "0.87.1",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {

package/src/dev.js

@@ -34,7 +34,7 @@ import { extractImageReferences } from "./helper/imageExtractor.js";
 import { recurse } from "./helper/recursive-readdir.js";
 import { isFolderHidden, clearConfigCache } from "./helper/folderConfig.js";
 import { extractSections } from "./helper/sectionExtractor.js";
-import { getTemplates, getMenu, findAllCustomMenus, getCustomMenuForFile, getTransformedMetadata, getFooter, toTitleCase, addTrailingSlash, generateAutoIndexHtmlFromSource, copyMetaAssets } from "./helper/build/index.js";
+import { getTemplates, getMenu, findAllCustomMenus, getCustomMenuForFile, getTransformedMetadata, getFooter, getUrsaMetadata, toTitleCase, addTrailingSlash, generateAutoIndexHtmlFromSource, copyMetaAssets } from "./helper/build/index.js";
 import { findCustomMenu, extractMenuFrontmatter, parseCustomMenu, combineAutoAndManualMenu } from "./helper/customMenu.js";
 import { getAndIncrementBuildId } from "./helper/ursaConfig.js";
 import { resolvePort } from "./helper/portUtils.js";
@@ -47,6 +47,9 @@ const devState = {
   source: null,
   meta: null,
   output: null,
+
+  // Ursa + doc repo versions, embedded in JSON response headers
+  ursaMetadata: null,
   
   // Background cache status
   cacheReady: false,
@@ -766,6 +769,7 @@ export async function dev({
   devState.source = sourceDir + '/';
   devState.meta = metaDir;
   devState.output = outputDir + '/';
+  devState.ursaMetadata = await getUrsaMetadata(_source);
   
   console.log('🚀 Ursa Dev Mode');
   console.log('━'.repeat(50));
@@ -810,6 +814,17 @@ export async function dev({
     threshold: 1024,
     level: 6
   }));
+
+  // Add ursa-version and doc-version headers to all JSON responses
+  // (per-document JSON, directory index arrays, and public/*.json index files)
+  app.use((req, res, next) => {
+    if (req.path.endsWith('.json')) {
+      const meta = devState.ursaMetadata || {};
+      res.setHeader('X-ursa-version', meta.ursaVersion || 'unknown');
+      res.setHeader('X-doc-version', meta.docVersion || 'unknown');
+    }
+    next();
+  });
   
   // Dev mode document handler
   app.use(async (req, res, next) => {

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

@@ -0,0 +1,157 @@
+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/__test__/autoIndex.test.js

@@ -0,0 +1,95 @@
+import { join } from "path";
+import { mkdtemp, mkdir, writeFile, rm, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { tmpdir } from "os";
+import { generateAutoIndices } from "../autoIndex.js";
+
+let tempDir;
+let source;
+let output;
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), "ursa-autoindex-"));
+  source = join(tempDir, "source");
+  output = join(tempDir, "output");
+  await mkdir(source, { recursive: true });
+  await mkdir(output, { recursive: true });
+});
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+const TEMPLATE =
+  "<html><head>${styleLink}</head><body>${menu}${body}${footer}${customScript}</body></html>";
+
+function makeProgress() {
+  const logs = [];
+  return {
+    logs,
+    log: (msg) => logs.push(msg),
+    status: () => {},
+    done: () => {},
+  };
+}
+
+function runAutoIndices(directories, generatedArticles, progress) {
+  return generateAutoIndices(
+    output,
+    directories,
+    source,
+    { "default-template": TEMPLATE },
+    "",
+    "",
+    generatedArticles,
+    new Set(),
+    new Set(),
+    "20260101000000",
+    progress,
+    null
+  );
+}
+
+describe("generateAutoIndices with empty source folders", () => {
+  it("skips output directories that were never created instead of logging an error", async () => {
+    // Source has an empty folder (guides) and a folder with a document (docs).
+    // Only docs produced output files, so output/guides does not exist.
+    await mkdir(join(source, "guides"));
+    await mkdir(join(source, "docs"));
+    await writeFile(join(source, "docs", "hello.md"), "# Hello\n\nWorld\n");
+    await mkdir(join(output, "docs"));
+    await writeFile(join(output, "docs", "hello.html"), "<html><body>Hello</body></html>");
+
+    const progress = makeProgress();
+    await runAutoIndices(
+      [join(source, "guides"), join(source, "docs")],
+      [join(source, "docs", "hello.md")],
+      progress
+    );
+
+    const errors = progress.logs.filter((m) => /Error generating auto-index/i.test(m));
+    expect(errors).toEqual([]);
+    // The missing output directory is skipped, not created
+    expect(existsSync(join(output, "guides"))).toBe(false);
+    expect(existsSync(join(output, "guides", "index.html"))).toBe(false);
+  });
+
+  it("still generates auto-indices for folders that produced output", async () => {
+    await mkdir(join(source, "guides"));
+    await mkdir(join(source, "docs"));
+    await writeFile(join(source, "docs", "hello.md"), "# Hello\n\nWorld\n");
+    await mkdir(join(output, "docs"));
+    await writeFile(join(output, "docs", "hello.html"), "<html><body>Hello</body></html>");
+
+    const progress = makeProgress();
+    await runAutoIndices(
+      [join(source, "guides"), join(source, "docs")],
+      [join(source, "docs", "hello.md")],
+      progress
+    );
+
+    // Root and docs both exist in output, so both get an index.html
+    const docsIndex = await readFile(join(output, "docs", "index.html"), "utf8");
+    expect(docsIndex).toContain('<a href="hello.html">');
+    const rootIndex = await readFile(join(output, "index.html"), "utf8");
+    expect(rootIndex).toContain('<a href="docs/index.html">');
+  });
+});