@jxsuite/parser 1.8.1 → 2.0.0

package/src/highlight.ts

@@ -1,18 +1,18 @@
 /**
  * Build-time syntax highlighting for fenced code blocks (node-only).
  *
- * A synchronous Shiki core (JavaScript regex engine — no WASM, no async) tokenizes a fixed
- * grammar set against a light + dark GitHub theme pair. Tokens are emitted as span elements
- * carrying both colors as CSS custom properties (--shiki-light / --shiki-dark); the page's
- * stylesheet decides which one paints, so highlighting follows the color-scheme contract
- * (spec §9.5) for auto and forced schemes alike.
+ * A synchronous Shiki core (JavaScript regex engine — no WASM, no async) tokenizes a fixed grammar
+ * set (see `getHighlighter` for the list) against a light + dark GitHub theme pair. Tokens are
+ * emitted as span elements carrying both colors as CSS custom properties (--shiki-light /
+ * --shiki-dark); the page's stylesheet decides which one paints, so highlighting follows the
+ * color-scheme contract (spec §9.5) for auto and forced schemes alike.
  *
  * Lives outside the browser-safe transpile module: only the compile-time markdown path
  * (processMarkdown in md.ts) pays for the grammars.
  *
- * @docs framework/site/jx-markdown
  * @module @jxsuite/parser/highlight
  * @license MIT
+ * @docs framework/site/jx-markdown
  */
 
 import { createHighlighterCoreSync } from "shiki/core";
@@ -20,15 +20,28 @@ import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 import githubDark from "@shikijs/themes/github-dark-default";
 import githubLight from "@shikijs/themes/github-light-default";
 import css from "@shikijs/langs/css";
+import diff from "@shikijs/langs/diff";
+import dockerfile from "@shikijs/langs/dockerfile";
 import html from "@shikijs/langs/html";
+import ini from "@shikijs/langs/ini";
 import javascript from "@shikijs/langs/javascript";
 import json from "@shikijs/langs/json";
+import jsonc from "@shikijs/langs/jsonc";
 import markdown from "@shikijs/langs/markdown";
+import nginx from "@shikijs/langs/nginx";
+import nix from "@shikijs/langs/nix";
+import php from "@shikijs/langs/php";
+import python from "@shikijs/langs/python";
+import ruby from "@shikijs/langs/ruby";
 import shellscript from "@shikijs/langs/shellscript";
+import sql from "@shikijs/langs/sql";
+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 type { JxElement } from "@jxsuite/schema/types";
 import type { HighlighterCore } from "shiki/core";
+import { caddyfile } from "./grammars/caddyfile.ts";
 
 const THEMES = { dark: "github-dark-default", light: "github-light-default" } as const;
 
@@ -38,7 +51,32 @@ let _highlighter: HighlighterCore | null = null;
 function getHighlighter(): HighlighterCore {
   _highlighter ??= createHighlighterCoreSync({
     engine: createJavaScriptRegexEngine(),
-    langs: [json, typescript, javascript, markdown, html, shellscript, css, yaml],
+    langs: [
+      json,
+      jsonc,
+      typescript,
+      javascript,
+      markdown,
+      html,
+      shellscript,
+      css,
+      yaml,
+      /* The languages a technical knowledge base reaches for next: server config, scripting,
+         databases, data files, and patches. They were chosen by reading every fence in a real
+         operations vault, and tests/highlight.test.ts tokenizes a sample of each. */
+      sql,
+      php,
+      python,
+      ruby,
+      nix,
+      nginx,
+      caddyfile,
+      toml,
+      ini,
+      diff,
+      xml,
+      dockerfile,
+    ],
     themes: [githubLight, githubDark],
   });
   return _highlighter;
@@ -49,11 +87,13 @@ function getHighlighter(): HighlighterCore {
  * unknown languages (callers keep the plain-text fallback).
  *
  * @param {string} code
- * @param {string} lang - Fence info string (grammar name or registered alias)
+ * @param {string} info - Fence info string (grammar name or registered alias, any case)
  * @returns {(JxElement | string)[] | null}
  */
-export function highlightFence(code: string, lang: string): (JxElement | string)[] | null {
+export function highlightFence(code: string, info: string): (JxElement | string)[] | null {
   const h = getHighlighter();
+  // Grammar names and aliases are lower case; an author's fence is whatever they typed (```SQL).
+  const lang = info.toLowerCase();
   if (!h.getLoadedLanguages().includes(lang)) {
     return null;
   }

package/src/inert.ts

@@ -0,0 +1,101 @@
+/**
+ * Inert — making template-looking text in Markdown content stay text.
+ *
+ * Jx treats any string that contains `${` as a template and evaluates it, at build time and again
+ * in the browser (`isTemplateString`, `@jxsuite/schema/guards`). That is the right rule for a
+ * document an author wrote, and the wrong one for content: the body of a Markdown entry is prose
+ * and code samples, and a JavaScript template literal, a shell `${HOME}` or a GitHub Actions `${{
+ * secrets.TOKEN }}` in a fence is **text to show**, not an expression to run. Left alone, a
+ * highlighted fence containing `${` had its tokens turned into reactive bindings whose value is
+ * whatever the page's state says (usually nothing), so the sample silently lost the very code it
+ * was there to show.
+ *
+ * The framework's own guidance for content that reaches the tree is to escape `${` first (spec.md
+ * §21.1), and the compiler already has an idiom for it: it writes `${` into `innerHTML` so "the
+ * compile phase won't re-interpret" the result as a template. This module applies that idiom at the
+ * source, to the one producer that knows its text is content. A node whose `textContent` holds `${`
+ * gets the same text as HTML-escaped `innerHTML`, and a bare string child holding `${` becomes a
+ * `span` doing the same, so every other part of the pipeline sees nothing it could mistake for a
+ * template.
+ *
+ * It runs last, after heading ids and the table of contents are built from the text, because those
+ * read `textContent`.
+ *
+ * **Attribute values are different, and the rule is stated rather than hidden.** An entity cannot
+ * be written into an attribute (the serializer would escape its `&`), and a link's `href` or an
+ * image's `src` may legitimately name a template, so those two are left to the page author. The
+ * attributes that carry prose are made inert instead: `alt` and `title` (an image's description, a
+ * link's tooltip) and `data-title` (a callout's title), by writing a zero-width space between the
+ * `$` and the `{`. A note that says "set `${HOME}`" in an image description would otherwise become
+ * a binding whose evaluation throws in every visitor's browser, and the page would stop hydrating.
+ *
+ * Pure: no `node:` imports.
+ *
+ * @module @jxsuite/parser/inert
+ * @license MIT
+ * @docs framework/site/jx-markdown
+ */
+
+import type { JxElement } from "@jxsuite/schema/types";
+
+/**
+ * A content tree. A raw HTML block arrives as a nested array of nodes, so the shape is recursive
+ * and every walk over it has to descend into arrays as well as into `children`.
+ */
+export type ContentNodes = (JxElement | string | ContentNodes)[];
+
+/** HTML-escape text, and spell `${` as `${` so nothing downstream reads it as a template. */
+export function escapeTemplateText(text: string): string {
+  return text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("${", "&#36;{");
+}
+
+/** The attributes whose value is prose, so a `${` in one is text and never a binding. */
+const PROSE_ATTRIBUTES = ["alt", "title", "data-title"] as const;
+
+/** `${` spelled so an attribute value is not read as a template: a zero-width space splits it. */
+export function neutralizeTemplateAttribute(value: string): string {
+  return value.replaceAll("${", "$\u200B{");
+}
+
+/**
+ * Make every `${` in a content tree plain text, in place.
+ *
+ * @param {ContentNodes} nodes - An entry's `$children`
+ */
+export function makeTemplatesInert(nodes: ContentNodes): void {
+  for (const [i, node] of nodes.entries()) {
+    if (typeof node === "string") {
+      if (node.includes("${")) {
+        nodes[i] = { innerHTML: escapeTemplateText(node), tagName: "span" };
+      }
+      continue;
+    }
+    if (Array.isArray(node)) {
+      makeTemplatesInert(node);
+      continue;
+    }
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    if (typeof node.textContent === "string" && node.textContent.includes("${")) {
+      node.innerHTML = escapeTemplateText(node.textContent);
+      delete node.textContent;
+    }
+    const { attributes } = node;
+    if (attributes) {
+      for (const name of PROSE_ATTRIBUTES) {
+        const value = attributes[name];
+        if (typeof value === "string" && value.includes("${")) {
+          attributes[name] = neutralizeTemplateAttribute(value);
+        }
+      }
+    }
+    if (Array.isArray(node.children)) {
+      makeTemplatesInert(node.children as ContentNodes);
+    }
+  }
+}

package/src/markdown.ts

@@ -2,19 +2,20 @@
  * Markdown — the markdown format-extension class for Jx
  *
  * Single class carrying every format capability:
- * - static `parse` (markdown source → Jx document) — browser-safe
- * - static `serialize` (Jx document → markdown source) — browser-safe
- * - static `discover` / `load` (compile-time content access) — node-only, dynamic imports
- * - instance `resolve` (runtime on-demand access for `$prototype: "Markdown"` state)
  *
- * The node-only capabilities dynamically import `node:fs` / `./md.ts` inside the
- * method so this module stays importable in the browser (studio calls parse/serialize
- * in-process).
+ * - Static `parse` (markdown source → Jx document) — browser-safe
+ * - Static `serialize` (Jx document → markdown source) — browser-safe
+ * - Static `discover` / `load` (compile-time content access) — node-only, dynamic imports
+ * - Instance `resolve` (runtime on-demand access for `$prototype: "Markdown"` state)
+ *
+ * The node-only capabilities dynamically import `node:fs` / `./md.ts` inside the method so this
+ * module stays importable in the browser (studio calls parse/serialize in-process).
  *
  * @module @jxsuite/parser/markdown
  * @license MIT
  */
 
+import { compileExclude } from "./content-rules.ts";
 import { transpileJxMarkdown } from "./transpile.ts";
 import { serializeJxMarkdown } from "./serialize.ts";
 import type { SerializeOptions } from "./serialize.ts";
@@ -32,6 +33,24 @@ export interface MarkdownLoadOptions {
    * basename ids.
    */
   sourceRoot?: string;
+  /**
+   * 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;
+  /** Told of each `[!type]` marker whose type is not enabled (it stays a blockquote). */
+  onUnknownAlert?: (type: string) => void;
+}
+
+/** Options for {@link Markdown.discover}. */
+export interface MarkdownDiscoverOptions {
+  /** Directory the `source` is relative to. */
+  baseDir?: string;
+  /**
+   * Glob patterns, relative to the source directory, for files (and whole directories) to leave
+   * out. A directory every file of which is excluded is not read at all.
+   */
+  exclude?: readonly string[];
 }
 
 /**
@@ -58,22 +77,27 @@ export class Markdown {
     return serializeJxMarkdown(doc, options);
   }
 
-  /** List .md entry files for a content-type source (file path or directory). */
-  static async discover(source: string, options: { baseDir?: string } = {}): Promise<string[]> {
-    const { existsSync, readdirSync } = await import("node:fs");
+  /**
+   * List .md entry files for a content-type source (file path or directory).
+   *
+   * A directory is walked in sorted order, so the entries of a collection come back in the same
+   * order on every machine. The platform's own directory order is whatever the filesystem happens
+   * to return, which made an unsorted listing differ between a laptop and CI.
+   */
+  static async discover(source: string, options: MarkdownDiscoverOptions = {}): Promise<string[]> {
+    const { existsSync } = await import("node:fs");
     const { resolve, extname } = await import("node:path");
+    const { walkFiles } = await import("./walk.ts");
     const resolved = options.baseDir ? resolve(options.baseDir, source) : resolve(source);
 
     if (extname(resolved)) {
       return existsSync(resolved) ? [resolved] : [];
     }
-    try {
-      return readdirSync(resolved, { recursive: true })
-        .filter((f) => String(f).endsWith(".md"))
-        .map((f) => resolve(resolved, String(f)));
-    } catch {
-      return [];
-    }
+    return walkFiles(
+      resolved,
+      (name) => name.toLowerCase().endsWith(".md"),
+      compileExclude(options.exclude),
+    );
   }
 
   /** Load one markdown file into a content entry (frontmatter → data, body preserved). */
@@ -90,6 +114,8 @@ export class Markdown {
         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"] = {};
     /*

package/src/md.ts

@@ -2,8 +2,9 @@
  * Jxsuite/md — Markdown integration for Jx
  *
  * Provides two exports:
- *   - MarkdownFile       — Parse a single markdown file (external class for $prototype)
- *   - MarkdownCollection — Parse a glob of markdown files as a content collection
+ *
+ * - MarkdownFile — Parse a single markdown file (external class for $prototype)
+ * - MarkdownCollection — Parse a glob of markdown files as a content collection
  *
  * Built on the unified/remark ecosystem. Converts MDAST to JX node trees via mdastNodeToJx.
  *
@@ -21,8 +22,10 @@ import { readFileSync } from "node:fs";
 import { DEFAULT_FORMAT_LOCALE } from "@jxsuite/schema/intl";
 import { basename, extname, relative, resolve as resolvePath } 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";
 
@@ -163,8 +166,12 @@ function extractExcerpt(tree: MdastNode) {
 /**
  * Derive an entry slug from a file path. Without a source root (or for files directly at the root),
  * the slug is the basename — the historical behavior every flat collection relies on. Files in
- * subdirectories of the root get path-based slugs with POSIX separators and a trailing `/index`
- * stripped, so `studio/canvas.md` and `studio/canvas/index.md` both yield `studio/canvas`.
+ * subdirectories of the root get path-based slugs with POSIX separators and a trailing `/index` or
+ * `/README` (either case, as the link and route rules read them) stripped, so `studio/canvas.md`,
+ * `studio/canvas/index.md` and `studio/canvas/README.md` all yield `studio/canvas`: the file a
+ * folder shows (on GitHub, in Obsidian) is that folder's entry. Case and spaces in names are kept
+ * as written, so `Linux/Swap Configuration.md` is the id `Linux/Swap Configuration`; a collection
+ * that wants URL-friendly ids sets `idField` or slugifies in its `route`.
  *
  * @param {string} filePath - Absolute path to the markdown file
  * @param {string} [sourceRoot] - Resolved content-source root directory
@@ -175,8 +182,8 @@ function deriveSlug(filePath: string, sourceRoot?: string): string {
     const rel = relative(sourceRoot, filePath).split("\\").join("/");
     if (rel && !rel.startsWith("..") && rel.includes("/")) {
       let slug = rel.slice(0, rel.length - extname(rel).length);
-      if (slug.endsWith("/index")) {
-        slug = slug.slice(0, -"/index".length);
+      if (/\/(?:index|readme)$/i.test(slug)) {
+        slug = slug.slice(0, slug.lastIndexOf("/"));
       }
       return slug;
     }
@@ -195,6 +202,10 @@ function deriveSlug(filePath: string, sourceRoot?: string): string {
  * @param {boolean} [config.directives] - Enable directive support
  * @param {unknown} [config.directiveOptions] - Directive plugin options
  * @param {string} [config.sourceRoot] - Content-source root; files below it get path-based slugs
+ * @param {unknown} [config.alerts] - The content type's `alerts` option: alert type → element name,
+ *   or `false` to leave `> [!NOTE]` blockquotes as written. Absent means the built-in callouts.
+ * @param {(type: string) => void} [config.onUnknownAlert] - Told of each `[!type]` marker whose
+ *   type is not enabled, which stays a blockquote.
  * @returns {MarkdownFileResult}
  */
 export function processMarkdown(
@@ -204,6 +215,8 @@ export function processMarkdown(
     directives?: boolean;
     directiveOptions?: unknown;
     sourceRoot?: string;
+    alerts?: unknown;
+    onUnknownAlert?: (type: string) => void;
   } = {},
 ) {
   let processor = (unified as unknown as () => UnifiedProcessor)()
@@ -220,6 +233,12 @@ export function processMarkdown(
   const vfile = { 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);
+  }
+
   const vfileData = vfile.data as Record<string, unknown>;
   const frontmatter = (vfileData.frontmatter ?? {}) as Record<string, unknown>;
   const mdTree = tree as unknown as MdastNode;
@@ -242,6 +261,10 @@ export function processMarkdown(
   // Table of contents agree by construction (specs/parser.md).
   const toc = assignHeadingIds($children);
 
+  // Last, because the ids and the table of contents above read `textContent`. Text that happens
+  // To contain `${` is content, not a template (inert.ts).
+  makeTemplatesInert($children);
+
   return {
     $children,
     $excerpt: excerpt,

package/src/serialize.ts

@@ -1152,9 +1152,6 @@ function deepResolve(
   scope: Record<string, unknown>,
   ctx: ExportContext,
 ) {
-  if (!Array.isArray(nodes)) {
-    return [];
-  }
   return nodes.map((node) => resolveNode(node, scope, ctx));
 }
 

package/src/transpile.ts

@@ -1,11 +1,11 @@
 /**
  * Jx Markdown Transpiler — Browser-safe module
  *
- * Exports only the transpiler functions that work in browser environments
- * (no node:fs, node:path, or glob dependencies).
+ * Exports only the transpiler functions that work in browser environments (no node:fs, node:path,
+ * or glob dependencies).
  *
- * Use `@jxsuite/parser/transpile` to import in browser contexts (e.g. studio).
- * Use `@jxsuite/parser` for the full parser including MarkdownFile/MarkdownCollection.
+ * Use `@jxsuite/parser/transpile` to import in browser contexts (e.g. studio). Use
+ * `@jxsuite/parser` for the full parser including MarkdownFile/MarkdownCollection.
  *
  * @module @jxsuite/parser/transpile
  * @license MIT
@@ -18,6 +18,8 @@ import remarkParseFrontmatter from "remark-parse-frontmatter";
 import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
 import { htmlToJx } from "@jxsuite/markup/html-to-jx";
+import { ALERT_NODE, DEFAULT_ALERT_TITLES, inlineText } from "./alerts.ts";
+import type { AlertNode } from "./alerts.ts";
 import type { MdastNode, UnifiedProcessor } from "./types.ts";
 import type {
   JsonValue,
@@ -389,6 +391,10 @@ export function mdastNodeToJx(node: MdastNode) {
     return directiveToJx(node);
   }
 
+  if (node.type === ALERT_NODE) {
+    return alertToJx(node as AlertNode);
+  }
+
   if (node.type === "text") {
     return node.value ?? null;
   }
@@ -516,6 +522,56 @@ export function mdastNodeToJx(node: MdastNode) {
   return el;
 }
 
+/**
+ * Convert an alert (`> [!NOTE]`, rewritten by `transformAlerts` before conversion) to a Jx element.
+ *
+ * Two shapes, chosen by the content type's `alerts` option. A type mapped to an element renders as
+ * exactly what `:::that-element` would have produced, with the alert type at `data-alert` and any
+ * author title at `data-title`, so the component owns its own look and its own title. A type with
+ * no mapping gets built-in markup that stands alone: a `div` with `role="note"` whose first child
+ * is a visible title paragraph, and class hooks (`jx-alert`, `jx-alert-<type>`, `jx-alert-title`)
+ * for the page's stylesheet. The title is a `p`, not a heading, so a callout never lands in the
+ * table of contents or in the search index's section list.
+ *
+ * @param {AlertNode} node
+ * @returns {JxElement}
+ */
+function alertToJx(node: AlertNode): JxElement {
+  const body = convertChildren(node.children ?? []);
+
+  if (node.element) {
+    const attributes: Record<string, JxAttributeValue> = { "data-alert": node.alert };
+    if (node.titleNodes) {
+      attributes["data-title"] = inlineText(node.titleNodes).trim();
+    }
+    const el: JxElement = { attributes, tagName: node.element };
+    if (body.length > 0) {
+      el.children = body;
+    }
+    return el;
+  }
+
+  const title: JxElement = { className: "jx-alert-title", tagName: "p" };
+  if (node.titleNodes) {
+    const inline = convertChildren(node.titleNodes);
+    if (inline.length === 1 && typeof inline[0] === "string") {
+      [title.textContent] = inline;
+    } else {
+      title.children = inline;
+    }
+  } else {
+    title.textContent =
+      DEFAULT_ALERT_TITLES[node.alert] ??
+      `${node.alert.charAt(0).toUpperCase()}${node.alert.slice(1)}`;
+  }
+  return {
+    attributes: { "data-alert": node.alert, role: "note" },
+    children: [title, ...body],
+    className: `jx-alert jx-alert-${node.alert}`,
+    tagName: "div",
+  };
+}
+
 /**
  * Convert a directive mdast node to a Jx element.
  *
@@ -536,7 +592,8 @@ function directiveToJx(node: MdastNode) {
     if (isCustomElement) {
       // For custom elements:
       //   - style, children, textContent, innerHTML, $-prefixed → element-level
-      //   - props (from props.X dot-path) → $props (component state)
+      //     ($props included: "props", bare or dotted, is a JX_DOLLAR_KEYS entry, so
+      //     `expandDotPaths` has already renamed it to "$props" by the time this loop sees it)
       //   - everything else → HTML attributes
       for (const [key, value] of Object.entries(props)) {
         if (
@@ -547,8 +604,6 @@ function directiveToJx(node: MdastNode) {
           key.startsWith("$")
         ) {
           el[key] = value;
-        } else if (key === "props") {
-          el.$props = value as Record<string, JsonValue>;
         } else {
           if (!el.attributes) {
             el.attributes = {};

package/src/types.ts

@@ -27,6 +27,23 @@ export interface ContentTypeDef {
   format?: string;
   schema?: Record<string, unknown>;
   $elements?: (string | { $ref: string })[];
+  /** Globs, relative to a directory `source`, for files that are never read. */
+  exclude?: string[];
+  /** Declarative frontmatter filter: only entries that satisfy it are kept. */
+  where?: Record<string, unknown>;
+  /** Frontmatter field whose value is the entry id (the path-derived id when absent). */
+  idField?: string;
+  /** Route template giving each entry its URL. */
+  route?: string;
+  /** Route template for a directory's README.md or index.md (`route` is used when absent). */
+  indexRoute?: string;
+  /** How a link that has no page is reported. Default `"warn"`. */
+  links?: "warn" | "error" | "ignore";
+  /**
+   * GitHub alert type → custom element, `true` for the built-in markup, `false` to leave it a
+   * blockquote. `false` for the whole option turns callouts off, `true` is the default.
+   */
+  alerts?: Record<string, string | boolean | null> | boolean;
   [key: string]: unknown;
 }
 

package/src/walk.ts

@@ -0,0 +1,97 @@
+/**
+ * Walk — the one directory walk behind every collection's file discovery (node-only).
+ *
+ * Three properties are the reason it is not a bare `readdirSync(dir, { recursive: true })`:
+ *
+ * - **Sorted.** Entries are visited by name within each directory, depth first, so a collection loads
+ *   in the same order on every machine. The platform's own directory order is whatever the
+ *   filesystem returns, and "first one wins" rules (a duplicate id, a duplicate route) must not
+ *   depend on it.
+ * - **Pruned.** A directory an `exclude` pattern excludes whole (`**` + `/node_modules/**`,
+ *   `internal/**`, a dot-folder) is never read, which is the difference between a vault that sits
+ *   beside a website's `node_modules` building in a blink and building after listing every file in
+ *   it. A directory that cannot be read is skipped rather than failing the whole collection.
+ * - **Loop-safe.** A symlinked directory is followed, as `readdirSync` always did, because a monorepo
+ *   that mounts shared documentation into a collection (`content/docs` pointing at `../../docs`) is
+ *   a real layout. What it refuses is a link back into a directory it is already inside, which
+ *   would otherwise recurse until the platform gave up.
+ *
+ * @module @jxsuite/parser/walk
+ * @license MIT
+ * @docs framework/site/content-collections
+ */
+
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ExcludeMatcher } from "./content-rules.ts";
+
+/**
+ * Absolute paths of the files under `root` whose name `accept`s and that `exclude` does not hide.
+ *
+ * A symlink is a file when it points at one and is ignored when it dangles. A symlink to a
+ * directory is entered once per path that reaches it, except that a link resolving to a directory
+ * the walk is currently inside is skipped, so a link back to an ancestor cannot loop. Links are
+ * trusted: where one points is the author's choice, exactly as it is for any other file in the
+ * source.
+ *
+ * @param {string} root - Absolute directory
+ * @param {(name: string) => boolean} accept - Whether a file name is an entry file
+ * @param {ExcludeMatcher} exclude - The type's `exclude` patterns, matched against root-relative
+ *   paths
+ * @returns {string[]}
+ */
+export function walkFiles(
+  root: string,
+  accept: (name: string) => boolean,
+  exclude: ExcludeMatcher,
+): string[] {
+  const found: string[] = [];
+  /** The real path of every directory the walk is inside right now, root first. */
+  const inside = new Set<string>();
+  const real = (path: string): string | undefined => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return undefined;
+    }
+  };
+  const walk = (dir: string, rel: string, realDir: string) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    inside.add(realDir);
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+      const path = rel === "" ? entry.name : `${rel}/${entry.name}`;
+      const full = join(dir, entry.name);
+      let isDirectory = entry.isDirectory();
+      let realChild = join(realDir, entry.name);
+      let isFile = entry.isFile();
+      if (entry.isSymbolicLink()) {
+        const target = statSync(full, { throwIfNoEntry: false });
+        isDirectory = target?.isDirectory() === true;
+        isFile = target?.isFile() === true;
+        if (isDirectory) {
+          const resolved = real(full);
+          if (resolved === undefined) {
+            continue;
+          }
+          realChild = resolved;
+        }
+      }
+      if (isDirectory) {
+        if (!inside.has(realChild) && !exclude.excludesDir(path)) {
+          walk(full, path, realChild);
+        }
+      } else if (isFile && accept(entry.name) && !exclude.excludedBy(path)) {
+        found.push(full);
+      }
+    }
+    inside.delete(realDir);
+  };
+  walk(root, "", real(root) ?? root);
+  return found;
+}