@jxsuite/parser 2.0.0 → 3.0.0

package/src/dates.ts

@@ -22,7 +22,8 @@
  * @docs framework/site/content-collections
  */
 
-import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+import type { ContentFieldValue, ContentTypeSchema } from "@jxsuite/schema/types";
 import type { ContentLoaderEntry } from "./types.ts";
 
 /** The two JSON Schema `format` values that carry build behavior. */
@@ -30,7 +31,7 @@ export const DATE_FORMATS = ["date", "date-time"] as const;
 export type DateFormat = (typeof DATE_FORMATS)[number];
 
 export function isDateFormat(format: unknown): format is DateFormat {
-  return typeof format === "string" && (DATE_FORMATS as readonly string[]).includes(format);
+  return DATE_FORMATS.some((candidate) => candidate === format);
 }
 
 /** `YYYY-MM-DD`, with no time part. */
@@ -58,7 +59,10 @@ function toInstant(d: Date): string {
  * Accepts, in order: a `Date` (YAML frontmatter parsers routinely produce one for an unquoted
  * `date: 2025-03-04`), an RFC 3339 string, and a bare `YYYY-MM-DD`. Everything else is refused.
  */
-export function parseDateValue(value: unknown, format: DateFormat): string | null {
+export function parseDateValue(
+  value: ContentFieldValue | undefined,
+  format: DateFormat,
+): string | null {
   if (value instanceof Date) {
     return Number.isNaN(value.getTime())
       ? null
@@ -66,7 +70,7 @@ export function parseDateValue(value: unknown, format: DateFormat): string | nul
         ? toDateOnly(value)
         : toInstant(value);
   }
-  if (typeof value !== "string") {
+  if (!isString(value)) {
     return null;
   }
   const text = value.trim();
@@ -107,7 +111,7 @@ export function isCoercedDate(value: string): boolean {
 export interface DateCoercionWarning {
   entryId: string;
   field: string;
-  value: unknown;
+  value: ContentFieldValue;
   message: string;
 }
 
@@ -128,9 +132,9 @@ export function coerceEntryDates(
     return warnings;
   }
 
-  const dateFields: [string, DateFormat][] = Object.entries(properties)
-    .map(([field, def]): [string, unknown] => [field, (def as { format?: unknown }).format])
-    .filter((pair): pair is [string, DateFormat] => isDateFormat(pair[1]));
+  const dateFields = Object.entries(properties).flatMap(([field, def]): [string, DateFormat][] =>
+    isDateFormat(def.format) ? [[field, def.format]] : [],
+  );
   if (dateFields.length === 0) {
     return warnings;
   }
@@ -174,11 +178,12 @@ export function coerceEntryDates(
  * compares false against everything. Normalized RFC 3339 strings compare chronologically as text,
  * so the fix is to notice when both sides are dates and stay in string space.
  */
-export function parseComparable(a: unknown, b: unknown): [number, number] | [string, string] {
-  const aDate = typeof a === "string" && (DATE_ONLY.test(a) || RFC_3339.test(a));
-  const bDate = typeof b === "string" && (DATE_ONLY.test(b) || RFC_3339.test(b));
-  if (aDate && bDate) {
-    return [a as string, b as string];
+export function parseComparable(
+  a: ContentFieldValue | undefined,
+  b: ContentFieldValue | undefined,
+): [number, number] | [string, string] {
+  if (isString(a) && isCoercedDate(a) && isString(b) && isCoercedDate(b)) {
+    return [a, b];
   }
   return [Number(a), Number(b)];
 }

package/src/highlight.ts

@@ -39,6 +39,7 @@ import toml from "@shikijs/langs/toml";
 import typescript from "@shikijs/langs/typescript";
 import xml from "@shikijs/langs/xml";
 import yaml from "@shikijs/langs/yaml";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 import type { HighlighterCore } from "shiki/core";
 import { caddyfile } from "./grammars/caddyfile.ts";
@@ -106,7 +107,7 @@ export function highlightFence(code: string, info: string): (JxElement | string)
     for (const token of line) {
       const span: JxElement = { tagName: "span", textContent: token.content };
       if (token.htmlStyle && Object.keys(token.htmlStyle).length > 0) {
-        span.style = token.htmlStyle as Record<string, string>;
+        span.style = token.htmlStyle;
       }
       out.push(span);
     }
@@ -122,17 +123,17 @@ export function highlightFence(code: string, info: string): (JxElement | string)
  */
 export function highlightCodeBlocks(nodes: (JxElement | string)[]): void {
   for (const node of nodes) {
-    if (!node || typeof node !== "object") {
+    if (!isNonNullObject(node)) {
       continue;
     }
     if (node.tagName === "pre" && Array.isArray(node.children)) {
       for (const child of node.children) {
-        if (!child || typeof child !== "object" || child.tagName !== "code") {
+        if (!isNonNullObject(child) || child.tagName !== "code") {
           continue;
         }
         const lang = /^language-(\S+)/.exec(child.className ?? "")?.[1];
         const code = child.textContent;
-        if (!lang || typeof code !== "string" || code.length === 0) {
+        if (!lang || !isString(code) || code.length === 0) {
           continue;
         }
         const spans = highlightFence(code, lang);
@@ -146,7 +147,7 @@ export function highlightCodeBlocks(nodes: (JxElement | string)[]): void {
       continue;
     }
     if (Array.isArray(node.children)) {
-      highlightCodeBlocks(node.children as (JxElement | string)[]);
+      highlightCodeBlocks(node.children);
     }
   }
 }

package/src/inert.ts

@@ -36,6 +36,7 @@
  * @docs framework/site/jx-markdown
  */
 
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxElement } from "@jxsuite/schema/types";
 
 /**
@@ -68,7 +69,7 @@ export function neutralizeTemplateAttribute(value: string): string {
  */
 export function makeTemplatesInert(nodes: ContentNodes): void {
   for (const [i, node] of nodes.entries()) {
-    if (typeof node === "string") {
+    if (isString(node)) {
       if (node.includes("${")) {
         nodes[i] = { innerHTML: escapeTemplateText(node), tagName: "span" };
       }
@@ -78,10 +79,11 @@ export function makeTemplatesInert(nodes: ContentNodes): void {
       makeTemplatesInert(node);
       continue;
     }
-    if (typeof node !== "object" || node === null) {
+    // A hole in a hand-built tree (`null`) is skipped, not walked into.
+    if (!isNonNullObject(node)) {
       continue;
     }
-    if (typeof node.textContent === "string" && node.textContent.includes("${")) {
+    if (isString(node.textContent) && node.textContent.includes("${")) {
       node.innerHTML = escapeTemplateText(node.textContent);
       delete node.textContent;
     }
@@ -89,13 +91,13 @@ export function makeTemplatesInert(nodes: ContentNodes): void {
     if (attributes) {
       for (const name of PROSE_ATTRIBUTES) {
         const value = attributes[name];
-        if (typeof value === "string" && value.includes("${")) {
+        if (isString(value) && value.includes("${")) {
           attributes[name] = neutralizeTemplateAttribute(value);
         }
       }
     }
     if (Array.isArray(node.children)) {
-      makeTemplatesInert(node.children as ContentNodes);
+      makeTemplatesInert(node.children);
     }
   }
 }

package/src/markdown.ts

@@ -19,7 +19,7 @@ import { compileExclude } from "./content-rules.ts";
 import { transpileJxMarkdown } from "./transpile.ts";
 import { serializeJxMarkdown } from "./serialize.ts";
 import type { SerializeOptions } from "./serialize.ts";
-import type { JxDocument } from "@jxsuite/schema/types";
+import type { JsonValue, JxDocument } from "@jxsuite/schema/types";
 import type { ContentLoaderEntry, MarkdownFileResult } from "./types.ts";
 
 export interface MarkdownLoadOptions {
@@ -37,9 +37,16 @@ export interface MarkdownLoadOptions {
    * The content type's `alerts` option: alert type → custom element, or `false` to leave GitHub
    * alerts (`> [!NOTE]`) as plain blockquotes. Absent renders the built-in callout markup.
    */
-  alerts?: unknown;
+  alerts?: JsonValue;
   /** Told of each `[!type]` marker whose type is not enabled (it stays a blockquote). */
   onUnknownAlert?: (type: string) => void;
+  /**
+   * Read the frontmatter and leave the body unparsed: the entry comes back without `$children` and
+   * without the `_meta` fields read from the body (`excerpt`, `toc`, `readingTime`, `wordCount`).
+   * The content loader asks for this when a host loads a collection lazily, and loads the file
+   * again without it once the entry is actually returned (specs/extensions.md §8).
+   */
+  deferBody?: boolean;
 }
 
 /** Options for {@link Markdown.discover}. */
@@ -105,18 +112,9 @@ export class Markdown {
     path: string,
     options: MarkdownLoadOptions = {},
   ): Promise<ContentLoaderEntry[]> {
-    const { processMarkdown } = await import("./md.ts");
+    const { processMarkdown, readFrontmatter } = await import("./md.ts");
     const { readFileSync, statSync } = await import("node:fs");
     const source = readFileSync(path, "utf8");
-    const result = processMarkdown(source, path, {
-      ...(options.directives !== undefined && { directives: options.directives }),
-      ...(options.directiveOptions !== undefined && {
-        directiveOptions: options.directiveOptions,
-      }),
-      ...(options.sourceRoot !== undefined && { sourceRoot: options.sourceRoot }),
-      ...(options.alerts !== undefined && { alerts: options.alerts }),
-      ...(options.onUnknownAlert !== undefined && { onUnknownAlert: options.onUnknownAlert }),
-    });
     const _meta: ContentLoaderEntry["_meta"] = {};
     /*
      * The modification time is the only date a file always has. A feed falls back to it when the
@@ -130,18 +128,24 @@ export class Markdown {
     } catch {
       // A format class may be handed content that is not on disk; an absent mtime is not an error.
     }
-    if (result.$excerpt != null) {
-      _meta.excerpt = result.$excerpt;
-    }
-    if (result.$toc != null) {
-      _meta.toc = result.$toc;
-    }
-    if (result.$readingTime != null) {
-      _meta.readingTime = result.$readingTime;
-    }
-    if (result.$wordCount != null) {
-      _meta.wordCount = result.$wordCount;
+    if (options.deferBody) {
+      const { frontmatter, slug } = readFrontmatter(source, path, options.sourceRoot);
+      return [{ _meta, body: source, data: frontmatter, id: slug }];
     }
+    const result = processMarkdown(source, path, {
+      ...(options.directives !== undefined && { directives: options.directives }),
+      ...(options.directiveOptions !== undefined && {
+        directiveOptions: options.directiveOptions,
+      }),
+      ...(options.sourceRoot !== undefined && { sourceRoot: options.sourceRoot }),
+      ...(options.alerts !== undefined && { alerts: options.alerts }),
+      ...(options.onUnknownAlert !== undefined && { onUnknownAlert: options.onUnknownAlert }),
+    });
+    // `processMarkdown` always derives all four, so every entry carries them.
+    _meta.excerpt = result.$excerpt;
+    _meta.toc = result.$toc;
+    _meta.readingTime = result.$readingTime;
+    _meta.wordCount = result.$wordCount;
     return [
       {
         $children: result.$children,

package/src/md.ts

@@ -20,46 +20,42 @@ import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
 import { readFileSync } from "node:fs";
 import { DEFAULT_FORMAT_LOCALE } from "@jxsuite/schema/intl";
-import { basename, extname, relative, resolve as resolvePath } from "node:path";
+import { basename, extname, relative, resolve } from "node:path";
 import { globSync } from "glob";
 import { normalizeAlerts, transformAlerts } from "./alerts.ts";
 import { assignHeadingIds, mdastNodeToJx } from "./transpile.ts";
 import { highlightCodeBlocks } from "./highlight.ts";
 import { makeTemplatesInert } from "./inert.ts";
-import type { MarkdownFileResult, MdastNode, UnifiedProcessor } from "./types.ts";
-import type { JxElement } from "@jxsuite/schema/types";
+import type {
+  MarkdownFileResult,
+  MdastNode,
+  UnifiedFile,
+  UnifiedPlugin,
+  UnifiedProcessor,
+} from "./types.ts";
+import { isFunction } from "@jxsuite/schema/guards";
+import type { ContentFieldValue, JsonObject, JsonValue, JxElement } from "@jxsuite/schema/types";
 
 // ─── Tree utilities (inline to avoid Bun ESM resolution issues with unist-util-*) ──
 
 /**
- * Walk an AST tree, calling visitor for nodes matching the given type.
+ * Find the first node of a type in an AST tree, in document (depth-first, pre-order) order.
  *
- * @param {object} tree
- * @param {string | function} typeOrVisitor
- * @param {function} [maybeVisitor]
+ * @param {MdastNode} node
+ * @param {string} type
+ * @returns {MdastNode | null}
  */
-function visit(
-  tree: MdastNode,
-  typeOrVisitor: string | ((node: MdastNode) => void),
-  maybeVisitor?: (node: MdastNode) => void,
-) {
-  const type = typeof typeOrVisitor === "string" ? typeOrVisitor : null;
-  const visitor = type ? maybeVisitor : typeOrVisitor;
-
-  function walk(node: MdastNode) {
-    if (!node || typeof node !== "object") {
-      return;
-    }
-    if (!type || node.type === type) {
-      (visitor as (node: MdastNode) => void)(node);
-    }
-    if (Array.isArray(node.children)) {
-      for (const child of node.children) {
-        walk(child);
-      }
+function findFirst(node: MdastNode, type: string): MdastNode | null {
+  if (node.type === type) {
+    return node;
+  }
+  for (const child of node.children ?? []) {
+    const found = findFirst(child, type);
+    if (found) {
+      return found;
     }
   }
-  walk(tree as MdastNode);
+  return null;
 }
 
 /**
@@ -69,12 +65,6 @@ function visit(
  * @returns {string}
  */
 function mdastToString(node: MdastNode): string {
-  if (!node) {
-    return "";
-  }
-  if (typeof node === "string") {
-    return node;
-  }
   if (node.value) {
     return node.value;
   }
@@ -86,6 +76,15 @@ function mdastToString(node: MdastNode): string {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * The unified processor chain, through the hand-written surface `UnifiedProcessor` describes.
+ *
+ * SAFETY: `unified()` returns a remark-compatible Processor whose `use`, `parse`, `runSync` and
+ * `stringify` are the four members `UnifiedProcessor` declares; the assertion only states that
+ * surface for a type-aware linter that resolves the package's ESM-only types as `any`.
+ */
+const createProcessor = unified as () => UnifiedProcessor;
+
 /** Average reading speed. See {@link readingTime} for why this is one number and not a table. */
 const WORDS_PER_MINUTE = 200;
 
@@ -151,12 +150,7 @@ function readingTime(text: string) {
  * @returns {string} Plain text of first paragraph, or empty string
  */
 function extractExcerpt(tree: MdastNode) {
-  let firstParagraph: MdastNode | null = null;
-  visit(tree, "paragraph", (node: MdastNode) => {
-    if (!firstParagraph) {
-      firstParagraph = node;
-    }
-  });
+  const firstParagraph = findFirst(tree, "paragraph");
   if (!firstParagraph) {
     return "";
   }
@@ -191,6 +185,64 @@ function deriveSlug(filePath: string, sourceRoot?: string): string {
   return basename(filePath, extname(filePath));
 }
 
+/** A frontmatter fence line: `---`, optionally followed by spaces or tabs (micromark's rule). */
+const FENCE_LINE = /^---[ \t]*\r?$/;
+
+/**
+ * Where a leading frontmatter block ends: the index just past its closing fence line, or 0 when the
+ * source does not open with one. Only the cut is decided here; whether the block IS frontmatter is
+ * still decided by the same remark plugins {@link processMarkdown} runs.
+ */
+function frontmatterEnd(source: string): number {
+  const firstBreak = source.indexOf("\n");
+  if (firstBreak === -1 || !FENCE_LINE.test(source.slice(0, firstBreak))) {
+    return 0;
+  }
+  let start = firstBreak + 1;
+  while (start < source.length) {
+    const lineEnd = source.indexOf("\n", start);
+    const end = lineEnd === -1 ? source.length : lineEnd;
+    if (FENCE_LINE.test(source.slice(start, end))) {
+      return end;
+    }
+    start = end + 1;
+  }
+  return 0;
+}
+
+/**
+ * The parsed frontmatter and slug of a markdown file, without parsing its body.
+ *
+ * A collection's queries, routes, ids and `where` rules read frontmatter alone, and the body is
+ * where the cost is: one knowledge base spent three of its four load seconds highlighting code
+ * blocks in articles no request had asked for. The block is parsed by the same plugins
+ * {@link processMarkdown} uses, cut off after its closing fence, so the two always agree on what the
+ * frontmatter is (specs/parser.md).
+ *
+ * @param {string} source - Raw markdown string
+ * @param {string} filePath - File path (for slug derivation)
+ * @param {string} [sourceRoot] - Content-source root; files below it get path-based slugs
+ * @returns {{ frontmatter: JsonObject; slug: string }}
+ */
+export function readFrontmatter(source: string, filePath: string, sourceRoot?: string) {
+  const slug = deriveSlug(filePath, sourceRoot);
+  const end = frontmatterEnd(source);
+  if (end === 0) {
+    return { frontmatter: {}, slug };
+  }
+  /* SAFETY: as in processMarkdown below — the three remark packages are shorthand `declare module`
+     entries whose default exports are unified attachers taking optional JSON settings. */
+  const processor = createProcessor()
+    .use(remarkParse as UnifiedPlugin)
+    .use(remarkFrontmatter as UnifiedPlugin, ["yaml"])
+    .use(remarkParseFrontmatter as UnifiedPlugin);
+  const vfile: UnifiedFile = { data: {} };
+  processor.runSync(processor.parse(source.slice(0, end)), vfile);
+  /* SAFETY: the same claim processMarkdown makes of the same plugin's output: a mapping parses to
+     a JsonObject, and no block gives `{}`. */
+  return { frontmatter: (vfile.data.frontmatter ?? {}) as JsonObject, slug };
+}
+
 /**
  * Process a single markdown source string into a MarkdownFileResult.
  *
@@ -215,14 +267,18 @@ export function processMarkdown(
     directives?: boolean;
     directiveOptions?: unknown;
     sourceRoot?: string;
-    alerts?: unknown;
+    alerts?: JsonValue;
     onUnknownAlert?: (type: string) => void;
   } = {},
 ) {
-  let processor = (unified as unknown as () => UnifiedProcessor)()
-    .use(remarkParse)
-    .use(remarkFrontmatter, ["yaml"])
-    .use(remarkParseFrontmatter)
+  /* SAFETY: `remark-parse`, `remark-frontmatter` and `remark-parse-frontmatter` are shorthand
+     `declare module` entries in the root types.d.ts, so their default imports are `any` here. Each
+     package default-exports a unified attacher taking optional JSON settings (remark-frontmatter
+     receives the `["yaml"]` preset list), which is the UnifiedPlugin shape. */
+  let processor = createProcessor()
+    .use(remarkParse as UnifiedPlugin)
+    .use(remarkFrontmatter as UnifiedPlugin, ["yaml"])
+    .use(remarkParseFrontmatter as UnifiedPlugin)
     .use(remarkGfm);
 
   if (config.directives || config.directiveOptions) {
@@ -230,25 +286,34 @@ export function processMarkdown(
   }
 
   const tree = processor.parse(source);
-  const vfile = { data: {} };
+  const vfile: UnifiedFile = { data: {} };
   processor.runSync(tree, vfile);
 
   // Callouts first, so the excerpt and word count read the alert's own text, not its `[!NOTE]` marker.
   const alerts = normalizeAlerts(config.alerts);
   if (alerts) {
-    transformAlerts(tree as unknown as MdastNode, alerts, config.onUnknownAlert);
+    transformAlerts(tree, alerts, config.onUnknownAlert);
   }
 
-  const vfileData = vfile.data as Record<string, unknown>;
-  const frontmatter = (vfileData.frontmatter ?? {}) as Record<string, unknown>;
-  const mdTree = tree as unknown as MdastNode;
-  const plainText = mdastToString(mdTree);
+  /* SAFETY: a front-matter block is a YAML mapping by convention, which yaml.parse gives as a
+     JsonObject, and no block (or an empty one) gives `{}`. A block that parses to a scalar or a
+     list is not a mapping; it is relayed as the result's `frontmatter` unchanged, as it always has
+     been, so the claimed object type does not hold for that malformed input. */
+  const frontmatter = (vfile.data.frontmatter ?? {}) as JsonObject;
+  const plainText = mdastToString(tree);
   const excerpt = extractExcerpt(tree);
   const slug = deriveSlug(filePath, config.sourceRoot);
 
-  const bodyNodes = tree.children!.filter(
+  const bodyNodes = (tree.children ?? []).filter(
     (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
-  ) as MdastNode[];
+  );
+  /*
+   * SAFETY: `filter(Boolean)` drops the nulls (and empty text), and what remains is an element, a
+   * string, or the node array a raw HTML block converts to, kept nested as one element. `$children`
+   * is declared flat, and every walk over it handles that nested array: highlightCodeBlocks and
+   * assignHeadingIds skip it (it has no `tagName` or `children`), while makeTemplatesInert and the
+   * content loader's link and asset passes descend into it as `ContentNodes`.
+   */
   const $children = bodyNodes.map((n: MdastNode) => mdastNodeToJx(n)).filter(Boolean) as (
     | JxElement
     | string
@@ -280,14 +345,19 @@ export function processMarkdown(
 /**
  * Resolve a dot-notation path within an object.
  *
- * @param {Record<string, unknown> | MarkdownFileResult} obj
+ * @param {MarkdownFileResult} obj
  * @param {string} path
- * @returns {unknown}
+ * @returns {ContentFieldValue | MarkdownFileResult | undefined}
  */
-function getNestedValue(obj: Record<string, unknown> | MarkdownFileResult, path: string) {
-  let current: unknown = obj;
+function getNestedValue(obj: MarkdownFileResult, path: string) {
+  let current: ContentFieldValue | MarkdownFileResult | undefined = obj;
   for (const k of path.split(".")) {
-    current = (current as Record<string, unknown> | undefined)?.[k];
+    /*
+     * SAFETY: `processMarkdown` builds a result out of strings, numbers, node arrays and the JSON
+     * frontmatter object, so every key a path steps through holds a content field value, or
+     * nothing, which `?.` carries to the end of the path.
+     */
+    current = (current as Record<string, ContentFieldValue | undefined> | null | undefined)?.[k];
   }
   return current;
 }
@@ -359,9 +429,10 @@ export class MarkdownCollection {
       ...processorConfig
     } = this.config;
 
-    const resolved = basePath ? resolvePath(basePath, src) : src;
+    const resolved = basePath ? resolve(basePath, src) : src;
     // Normalize to forward slashes — glob requires POSIX paths on all platforms
     const pattern = resolved.split("\\").join("/");
+    // SAFETY: with `absolute: true` and no `withFileTypes`, `globSync` returns the matched paths as strings.
     const files = (globSync as (p: string, o: { absolute: boolean }) => string[])(pattern, {
       absolute: true,
     });
@@ -373,16 +444,14 @@ export class MarkdownCollection {
 
     // Filter
     let filtered = results;
-    if (typeof filter === "function") {
-      filtered = results.filter((r: MarkdownFileResult) =>
-        (filter as (r: MarkdownFileResult) => boolean)(r),
-      );
+    if (isFunction(filter)) {
+      filtered = results.filter((r: MarkdownFileResult) => filter(r));
     }
 
     // Sort
     filtered.sort((a: MarkdownFileResult, b: MarkdownFileResult) => {
-      const aVal = getNestedValue(a, sortBy) ?? ("" as string | number);
-      const bVal = getNestedValue(b, sortBy) ?? ("" as string | number);
+      const aVal = getNestedValue(a, sortBy) ?? "";
+      const bVal = getNestedValue(b, sortBy) ?? "";
       if (aVal < bVal) {
         return sortOrder === "asc" ? -1 : 1;
       }