@jxsuite/parser 1.8.2 → 2.0.0

package/src/alerts.ts

@@ -0,0 +1,257 @@
+/**
+ * Alerts — GitHub-style callouts (`> [!NOTE]`) recognised in a Markdown tree.
+ *
+ * GitHub, Obsidian and most static-site plugins agree on one notation for a callout: a blockquote
+ * whose first line is `[!TYPE]`. Without recognising it a document renders as a quotation that
+ * begins with the literal text `[!NOTE]`, which is wrong everywhere a reader sees it.
+ *
+ * Recognition is a **tree rewrite that runs before conversion**, not a case inside the blockquote
+ * handler, for two reasons. Alerts nest (in list items, in other callouts, inside directives), and
+ * a rewrite that visits every blockquote gets all of those without the converter having to know the
+ * configuration at every depth. And it keeps `transpileJxMarkdown`, the path Studio parses a file
+ * through, untouched: that path round-trips back to Markdown on save, and a callout already
+ * converted to a `div` would be written back as a directive, silently rewriting the author's file.
+ * Only the content loader asks for alerts.
+ *
+ * Pure: no `node:` imports, no knowledge of Jx elements. The converter lives beside `mdastNodeToJx`
+ * in `transpile.ts`.
+ *
+ * @module @jxsuite/parser/alerts
+ * @license MIT
+ * @docs framework/site/jx-markdown
+ */
+
+import type { MdastNode } from "./types.ts";
+
+/** The five alert types GitHub defines, and the title each shows by default. */
+export const DEFAULT_ALERT_TITLES: Readonly<Record<string, string>> = {
+  caution: "Caution",
+  important: "Important",
+  note: "Note",
+  tip: "Tip",
+  warning: "Warning",
+};
+
+/** The synthetic mdast node type an alert becomes, consumed by `mdastNodeToJx`. */
+export const ALERT_NODE = "jxAlert";
+
+/**
+ * The `alerts` option of a content type: alert type (case-insensitive) → the custom element that
+ * renders it, or `true` for the built-in markup (which is also how a type beyond GitHub's five,
+ * such as Obsidian's `info` or `example`, is switched on). A `null` or `false` value leaves that
+ * type as an ordinary blockquote, and `false` for the whole option turns alert recognition off.
+ */
+export type AlertsConfig = Record<string, string | boolean | null> | false;
+
+/** The option after validation, keyed by lower-case alert type. */
+export interface AlertSettings {
+  /** Type → element tag name, or `null` to render the built-in markup. */
+  types: Map<string, string | null>;
+  /** Types the option switched off on purpose, so an unknown-type report can skip them. */
+  disabled: Set<string>;
+}
+
+/** A tag name an author could mean: HTML elements and custom elements alike. */
+const TAG_NAME = /^[A-Za-z][\w.-]*$/;
+
+/**
+ * Validate the `alerts` option into settings, or `null` when recognition is off.
+ *
+ * Throws on a value that is not a tag name so a typo in `project.json` fails the build where it was
+ * written rather than rendering a callout as an unknown element.
+ */
+export function normalizeAlerts(config?: unknown, where = "alerts"): AlertSettings | null {
+  if (config === false) {
+    return null;
+  }
+  const types = new Map<string, string | null>(
+    Object.keys(DEFAULT_ALERT_TITLES).map((type) => [type, null]),
+  );
+  const disabled = new Set<string>();
+  if (config === undefined || config === true) {
+    return { disabled, types };
+  }
+  if (typeof config !== "object" || config === null || Array.isArray(config)) {
+    throw new TypeError(
+      `${where}: expected an object mapping alert types to element names, or false`,
+    );
+  }
+  for (const [type, element] of Object.entries(config)) {
+    const key = type.toLowerCase();
+    if (!/^[a-z][\w-]*$/.test(key)) {
+      throw new TypeError(`${where}: "${type}" is not a valid alert type name`);
+    }
+    if (element === false || element === null) {
+      types.delete(key);
+      disabled.add(key);
+    } else if (element === true) {
+      types.set(key, null);
+    } else if (typeof element === "string" && TAG_NAME.test(element)) {
+      types.set(key, element);
+    } else {
+      throw new TypeError(
+        `${where}.${type}: expected an element name such as "doc-note", true or false, got ${JSON.stringify(element)}`,
+      );
+    }
+  }
+  return { disabled, types };
+}
+
+/** The shape an alert takes after the rewrite. */
+export interface AlertNode extends MdastNode {
+  type: typeof ALERT_NODE;
+  /** Lower-case alert type: `note`, `tip`, … */
+  alert: string;
+  /** Custom element tag from the `alerts` option, or null for the built-in markup. */
+  element: string | null;
+  /** The author's title as inline nodes, or null to use the type's default title. */
+  titleNodes: MdastNode[] | null;
+}
+
+const MARKER = /^\[!([A-Za-z][\w-]*)\][+-]?/;
+
+/** Plain text of a run of inline nodes. */
+export function inlineText(nodes: readonly MdastNode[]): string {
+  let out = "";
+  for (const node of nodes) {
+    if (typeof node.value === "string") {
+      out += node.value;
+    } else if (node.children) {
+      out += inlineText(node.children);
+    }
+  }
+  return out;
+}
+
+function textNode(value: string): MdastNode {
+  return { type: "text", value };
+}
+
+/** A line end in either of its spellings: a file saved on Windows keeps `\r\n` in its text nodes. */
+const LINE_END = /\r?\n/;
+
+/**
+ * The `[!TYPE]` marker at the start of a paragraph, or null when there is none.
+ *
+ * `rest` is the text after the marker in that first text node. A marker must be followed by
+ * whitespace or the end of the node (`[!NOTE]x` is not one), and the whitespace may be a carriage
+ * return, which is what a CRLF file puts there.
+ */
+function markerOf(paragraph: MdastNode): { type: string; rest: string } | null {
+  const [first] = paragraph.children ?? [];
+  if (first?.type !== "text" || typeof first.value !== "string") {
+    return null;
+  }
+  const match = MARKER.exec(first.value);
+  if (!match) {
+    return null;
+  }
+  const rest = first.value.slice(match[0].length);
+  if (rest !== "" && !/^[ \t\r\n]/.test(rest)) {
+    return null;
+  }
+  return { rest, type: match[1]!.toLowerCase() };
+}
+
+/**
+ * Split the first paragraph of a blockquote into the title line and the rest, or null when the
+ * blockquote is not an alert of a configured type.
+ *
+ * The title is whatever follows `[!TYPE]` on its own line, across inline formatting (`> [!NOTE] A
+ * **bold** title`). That is Obsidian's custom-title form; GitHub itself shows such a blockquote as
+ * plain text, so a file using it still reads sensibly there.
+ */
+function splitMarker(
+  paragraph: MdastNode,
+  settings: AlertSettings,
+): { type: string; title: MdastNode[]; body: MdastNode[] } | null {
+  const marker = markerOf(paragraph);
+  if (!marker || !settings.types.has(marker.type)) {
+    return null;
+  }
+  const { type, rest } = marker;
+  const [, ...siblings] = paragraph.children ?? [];
+
+  const title: MdastNode[] = [];
+  const body: MdastNode[] = [];
+  let inTitle = true;
+  const take = (node: MdastNode) => {
+    if (inTitle && node.type === "break") {
+      inTitle = false;
+    } else if (inTitle && node.type === "text" && typeof node.value === "string") {
+      const lineEnd = LINE_END.exec(node.value);
+      if (lineEnd === null) {
+        title.push(node);
+      } else {
+        title.push(textNode(node.value.slice(0, lineEnd.index)));
+        inTitle = false;
+        body.push(textNode(node.value.slice(lineEnd.index + lineEnd[0].length)));
+      }
+    } else {
+      (inTitle ? title : body).push(node);
+    }
+  };
+  take(textNode(rest.replace(/^[ \t]+/, "")));
+  for (const node of siblings) {
+    take(node);
+  }
+
+  const trimmed = title.filter((node) => !(node.type === "text" && node.value === ""));
+  const text = inlineText(trimmed);
+  return {
+    body: body.filter((node) => !(node.type === "text" && node.value === "")),
+    title: text.trim() === "" ? [] : trimmed,
+    type,
+  };
+}
+
+/**
+ * Rewrite every alert blockquote in a tree into an {@link AlertNode}, in place.
+ *
+ * A blockquote that is not an alert, or is of a type the settings do not know, is left alone and
+ * its children are still searched, so a callout nested inside an ordinary quotation is found.
+ * `onUnknown` hears each well-formed `[!type]` marker whose type is not enabled.
+ *
+ * @param {MdastNode} tree
+ * @param {AlertSettings} settings
+ * @param {(type: string) => void} [onUnknown]
+ */
+export function transformAlerts(
+  tree: MdastNode,
+  settings: AlertSettings,
+  onUnknown?: (type: string) => void,
+): void {
+  const { children } = tree;
+  if (!children) {
+    return;
+  }
+  for (const [i, child] of children.entries()) {
+    if (child.type === "blockquote") {
+      const [paragraph, ...rest] = child.children ?? [];
+      const split = paragraph?.type === "paragraph" ? splitMarker(paragraph, settings) : null;
+      if (split) {
+        const bodyParagraph: MdastNode[] =
+          split.body.length > 0 && inlineText(split.body).trim() !== ""
+            ? [{ children: split.body, type: "paragraph" }]
+            : [];
+        const alert: AlertNode = {
+          alert: split.type,
+          children: [...bodyParagraph, ...rest],
+          element: settings.types.get(split.type) ?? null,
+          titleNodes: split.title.length > 0 ? split.title : null,
+          type: ALERT_NODE,
+        };
+        children[i] = alert;
+        transformAlerts(alert, settings, onUnknown);
+        continue;
+      }
+      // A well-formed marker of a type nobody switched on: it stays a blockquote, and the author
+      // Is told, because the literal `[!info]` on the page is otherwise the only clue.
+      const unknown = paragraph?.type === "paragraph" ? markerOf(paragraph) : null;
+      if (unknown && !settings.disabled.has(unknown.type)) {
+        onUnknown?.(unknown.type);
+      }
+    }
+    transformAlerts(child, settings, onUnknown);
+  }
+}

package/src/content-links.ts

@@ -0,0 +1,343 @@
+/**
+ * Content links — relative links between the entries of one collection, rewritten to routes.
+ *
+ * An author writes `[Swap](../Linux/Swap%20Configuration.md)` because that link works in Obsidian,
+ * in VS Code and on GitHub. On the published site the same link has to go to the page that document
+ * became, and that URL is not the file path: it is whatever the content type's `route` template
+ * says (`content-routes.ts`). This module is the join between the two, run once over each entry's
+ * rendered tree after the whole collection has loaded, because a link can only be resolved once
+ * every other entry is known.
+ *
+ * **What it touches, and what it never does.** Only a relative reference that resolves to a file of
+ * the collection is rewritten: an entry to its route, and any other file (a PDF, an image, a
+ * download) to the URL the collection's asset mount publishes it at, the same remap an image's
+ * `src` gets. A scheme (`https:`, `mailto:`, `tel:`), an absolute path and a same-page `#anchor`
+ * that already is a heading id are left exactly as authored. The resolution is a walk over path
+ * SEGMENTS against the entry's own directory and it stops at the source root: a `..` that would
+ * climb out of it never produces a path, so a link cannot be made to name a file outside the
+ * collection.
+ *
+ * **A link to nothing becomes text.** An entry that is excluded, filtered out, unrouted or simply
+ * absent has no page, and neither has a folder with no README or index, or an excluded attachment;
+ * a published `<a>` to any of them is a 404 waiting for a reader. The anchor is replaced by its own
+ * content and the problem is reported with the source file and the target, at the severity the
+ * content type's `links` option asks for.
+ *
+ * Pure: no `node:` imports. The loader supplies the file facts through {@link LinkIndex}.
+ *
+ * @module @jxsuite/parser/content-links
+ * @license MIT
+ * @docs framework/site/content-collections
+ */
+
+import type { JxElement } from "@jxsuite/schema/types";
+import { routeHref } from "./content-routes.ts";
+import type { ContentNodes } from "./inert.ts";
+import { slugifyHeading } from "./transpile.ts";
+
+/** What the loader knows about one source file of the collection. */
+export type FileOutcome =
+  /** Published at this route. */
+  | { route: string }
+  /** Loaded but not published, and why. */
+  | { unpublished: string };
+
+/** How the resolver asks the loader about files. */
+export interface LinkIndex {
+  /** Every file the collection loaded, keyed by path relative to the source root. */
+  files: ReadonlyMap<string, FileOutcome>;
+  /** Directory (relative path, `""` for the root) → the file that is its index. */
+  indexes: ReadonlyMap<string, string>;
+  /** Extensions that make a path an ENTRY link rather than an asset link (`.md`). */
+  entryExtensions: ReadonlySet<string>;
+  /** The `exclude` pattern that hides this path, if one does. */
+  excludedBy: (path: string) => string | undefined;
+  /** Whether a path exists on disk, so "excluded" and "missing" can be told apart. */
+  exists: (path: string) => boolean;
+  /** Whether a path is a directory on disk. */
+  isDirectory?: (path: string) => boolean;
+  /** Whether an `exclude` pattern hides every file below a directory. */
+  excludesDir?: (path: string) => boolean;
+  /**
+   * What the collection's asset mount does with an existing file that is not an entry: the URL it
+   * is published at, or why it is not. `undefined` when there is nothing to say (no such file, a
+   * directory, or no mount), which leaves the link as authored.
+   */
+  asset?: (path: string) => { url: string } | { unpublished: string } | undefined;
+  /** `build.trailingSlash`. */
+  trailingSlash: string;
+  /** A locale URL prefix (`/fr`), or `""`. */
+  localePrefix: string;
+}
+
+/** One link that could not be resolved to a page. */
+export interface LinkProblem {
+  /** The href as authored. */
+  href: string;
+  /** Why it has no page: "is not published (…)", "does not exist", … */
+  reason: string;
+}
+
+/** The outcome for one href. */
+type Resolution = { keep: true } | { href: string } | { problem: string };
+
+/** A scheme, so `https:`, `mailto:`, `tel:`, `data:` and friends are never ours. */
+const SCHEME = /^[a-z][a-z\d+.-]*:/i;
+
+/**
+ * A `#fragment` in the form the rendered heading ids use.
+ *
+ * Obsidian writes `Note.md#Heading%20Text` and GitHub writes `#heading-text`; the page carries
+ * `id="heading-text"`. Both end up at the same slug, through the same function that built the ids
+ * (`slugifyHeading`), so the link lands wherever the heading did however it was typed. The function
+ * is idempotent on text that is already a slug, so a GitHub-spelled fragment (`#foo---bar` for `##
+ * Foo - Bar`, whose id collapses the run to `foo-bar`) is not special-cased and cannot drift.
+ */
+function fragmentFor(raw: string): string {
+  try {
+    // A fragment with no letter or digit has no heading to name; it stays as written.
+    return slugifyHeading(decodeURIComponent(raw)) || raw;
+  } catch {
+    return raw;
+  }
+}
+
+/** Split `path?query#fragment` into its three parts (query and fragment keep their delimiter). */
+function splitHref(href: string): { path: string; query: string; hash: string } {
+  const hashAt = href.indexOf("#");
+  const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);
+  const hash = hashAt === -1 ? "" : href.slice(hashAt);
+  const queryAt = beforeHash.indexOf("?");
+  return {
+    hash,
+    path: queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt),
+    query: queryAt === -1 ? "" : beforeHash.slice(queryAt),
+  };
+}
+
+/**
+ * The source-root-relative path a relative href names, or `null` when it climbs out of the root.
+ *
+ * Decodes each segment on its own, so `%2F` stays a character of one name instead of becoming a
+ * separator, then walks `.` and `..` against the entry's directory. `undefined` means the href is
+ * not a path this module understands (a malformed escape, a decoded separator): leave it alone.
+ */
+function resolvePath(from: string, path: string): string | null | undefined {
+  const segments = path.split("/");
+  const stack = from.split("/").slice(0, -1);
+  for (const raw of segments) {
+    let segment: string;
+    try {
+      segment = decodeURIComponent(raw);
+    } catch {
+      return undefined;
+    }
+    if (segment.includes("/") || segment.includes("\\")) {
+      return undefined;
+    }
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (stack.length === 0) {
+        return null;
+      }
+      stack.pop();
+    } else {
+      stack.push(segment);
+    }
+  }
+  return stack.join("/");
+}
+
+function extensionOf(path: string): string {
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot).toLowerCase() : "";
+}
+
+/** A path in the form two spellings of one name agree on: composed Unicode, lower case. */
+const fold = (path: string): string => path.normalize("NFC").toLowerCase();
+
+/** Folded path → the real paths it could mean, built once per index. */
+const FOLDED = new WeakMap<LinkIndex, Map<string, string[]>>();
+
+/**
+ * A file of the collection by exact path, then by a match that ignores case and Unicode
+ * normalisation form and is unambiguous. The second half is what makes a link typed on one system
+ * (a decomposed `é`, written by a macOS sync) find the file stored on another.
+ */
+function findFile(index: LinkIndex, path: string): string | undefined {
+  if (index.files.has(path)) {
+    return path;
+  }
+  let folded = FOLDED.get(index);
+  if (!folded) {
+    folded = new Map();
+    for (const key of index.files.keys()) {
+      const name = fold(key);
+      folded.set(name, [...(folded.get(name) ?? []), key]);
+    }
+    FOLDED.set(index, folded);
+  }
+  const hits = folded.get(fold(path));
+  return hits?.length === 1 ? hits[0] : undefined;
+}
+
+/** The index file of a directory, matching the directory name by Unicode form as well. */
+function findIndex(index: LinkIndex, dir: string): string | undefined {
+  const exact = index.indexes.get(dir);
+  if (exact !== undefined) {
+    return exact;
+  }
+  const wanted = dir.normalize("NFC");
+  for (const [name, file] of index.indexes) {
+    if (name.normalize("NFC") === wanted) {
+      return file;
+    }
+  }
+  return undefined;
+}
+
+/** Why a path with an entry extension has no page: excluded, or simply not there. */
+function whyMissing(index: LinkIndex, path: string): string {
+  const pattern = index.excludedBy(path);
+  if (pattern !== undefined && index.exists(path)) {
+    return `is not published (excluded by "${pattern}")`;
+  }
+  return "does not exist";
+}
+
+/**
+ * A relative link to something that is not an entry: an attachment, or a folder.
+ *
+ * An attachment that exists is published by the collection's asset mount at its own URL, so the
+ * link follows it there (a relative `files/report.pdf` on a page at `/kb/a/note/` would otherwise
+ * be `/kb/a/note/files/report.pdf`, which nothing serves). One the type does not publish, or a
+ * folder with no README or index, has no page, which makes it a broken link like any other.
+ * Anything else, a path that exists nowhere, is not this module's to judge and stays as authored.
+ */
+function resolveNonEntry(
+  target: string,
+  query: string,
+  hash: string,
+  index: LinkIndex,
+): Resolution {
+  const asset = index.asset?.(target);
+  if (asset !== undefined) {
+    return "url" in asset
+      ? { href: `${asset.url}${query}${hash}` }
+      : { problem: `is not published (${asset.unpublished})` };
+  }
+  if (index.isDirectory?.(target) === true) {
+    return index.excludesDir?.(target) === true
+      ? { problem: "is not published (its folder is excluded)" }
+      : { problem: "is a folder with no README.md or index.md" };
+  }
+  return { keep: true };
+}
+
+/** Resolve one href found in the entry at `from`. */
+function resolveHref(href: string, from: string, index: LinkIndex): Resolution {
+  if (href === "" || href.startsWith("/") || SCHEME.test(href) || href.includes("${")) {
+    return { keep: true };
+  }
+  const { path, query, hash } = splitHref(href);
+  if (path === "") {
+    // A same-page anchor: only the fragment can need work.
+    const fixed = hash.length > 1 ? `#${fragmentFor(hash.slice(1))}` : hash;
+    return fixed === hash ? { keep: true } : { href: fixed };
+  }
+
+  const target = resolvePath(from, path);
+  if (target === undefined) {
+    return { keep: true };
+  }
+  const entryLink = index.entryExtensions.has(extensionOf(path));
+  if (target === null) {
+    return entryLink
+      ? { problem: "points outside the collection's source directory" }
+      : { keep: true };
+  }
+
+  let file = findFile(index, target);
+  if (file === undefined && (path.endsWith("/") || extensionOf(path) === "")) {
+    /* A directory link (`../Frappe/`, `../Frappe`) names that directory's index entry, and an
+       extension-less one may name a file whose extension the author left off. */
+    file = findIndex(index, target);
+    for (const ext of path.endsWith("/") ? [] : index.entryExtensions) {
+      file ??= findFile(index, `${target}${ext}`);
+    }
+  }
+  if (file === undefined) {
+    return entryLink
+      ? { problem: whyMissing(index, target) }
+      : resolveNonEntry(target, query, hash, index);
+  }
+
+  const outcome = index.files.get(file)!;
+  if ("unpublished" in outcome) {
+    return { problem: `is not published (${outcome.unpublished})` };
+  }
+  const fragment = hash.length > 1 ? `#${fragmentFor(hash.slice(1))}` : hash;
+  return {
+    href: `${routeHref(outcome.route, index.trailingSlash, index.localePrefix)}${query}${fragment}`,
+  };
+}
+
+/** What a removed anchor leaves behind: its own content, as inline nodes. */
+function contentOf(anchor: JxElement): ContentNodes {
+  if (Array.isArray(anchor.children)) {
+    return anchor.children as ContentNodes;
+  }
+  if (typeof anchor.innerHTML === "string") {
+    // Text that holds `${` was made inert as escaped `innerHTML` (inert.ts); it keeps that form.
+    return [{ innerHTML: anchor.innerHTML, tagName: "span" }];
+  }
+  return typeof anchor.textContent === "string" ? [anchor.textContent] : [];
+}
+
+/**
+ * Rewrite the relative links in an entry's rendered tree, in place.
+ *
+ * @param {ContentNodes} nodes - The entry's `$children`
+ * @param {string} from - The entry's source file, relative to the source root, `/`-separated
+ * @param {LinkIndex} index - What the collection knows about its files
+ * @param {(problem: LinkProblem) => void} report - Called once per link that has no page
+ */
+export function rewriteLinks(
+  nodes: ContentNodes,
+  from: string,
+  index: LinkIndex,
+  report: (problem: LinkProblem) => void,
+): void {
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if (Array.isArray(node)) {
+      // A raw HTML block arrives as a nested list of nodes.
+      rewriteLinks(node, from, index, report);
+      continue;
+    }
+    if (typeof node !== "object" || node === null) {
+      continue;
+    }
+    const href = node.tagName === "a" ? node.attributes?.href : undefined;
+    if (typeof href === "string") {
+      const resolution = resolveHref(href, from, index);
+      if ("problem" in resolution) {
+        report({ href, reason: resolution.problem });
+        const replacement = contentOf(node);
+        rewriteLinks(replacement, from, index, report);
+        nodes.splice(i, 1, ...replacement);
+        i += replacement.length - 1;
+        continue;
+      }
+      if ("href" in resolution) {
+        node.attributes = { ...node.attributes, href: resolution.href };
+      }
+    }
+    if (Array.isArray(node.children)) {
+      rewriteLinks(node.children as ContentNodes, from, index, report);
+    }
+  }
+}