@jxsuite/parser 1.8.2 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "1.8.2",
+  "version": "2.0.1",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,10 +48,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.11",
-    "@jxsuite/schema": "^2.3.0",
-    "@shikijs/langs": "^4.4.3",
-    "@shikijs/themes": "^4.4.3",
+    "@jxsuite/markup": "^0.4.12",
+    "@jxsuite/schema": "^3.0.0",
+    "@shikijs/langs": "^4.5.0",
+    "@shikijs/themes": "^4.5.0",
     "glob": "^13.0.6",
     "mdast-util-to-string": "^4.0.0",
     "remark-directive": "^4.0.0",
@@ -60,14 +60,14 @@
     "remark-parse": "^11.0.0",
     "remark-parse-frontmatter": "^1.0.3",
     "remark-stringify": "^11.0.0",
-    "shiki": "^4.4.3",
+    "shiki": "^4.5.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "yaml": "^2.9.1"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.14.5",
-    "@jxsuite/runtime": "^4.0.2",
+    "@happy-dom/global-registrator": "^20.14.6",
+    "@jxsuite/runtime": "^4.1.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"
   },

package/schemas/project.fragment.schema.json

@@ -9,7 +9,7 @@
       "description": "File-based content collections. Each key names a content type; entries are loaded from the named source through the format registry.",
       "type": "object",
       "additionalProperties": {
-        "description": "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
+        "description": "Content type definition. Defines the source, how entries are filtered, identified and routed, and their schema and element dependencies.",
         "type": "object",
         "properties": {
           "$elements": {
@@ -19,10 +19,16 @@
               "oneOf": [
                 {
                   "type": "object",
-                  "properties": { "$ref": { "type": "string" } },
+                  "properties": {
+                    "$ref": {
+                      "type": "string"
+                    }
+                  },
                   "required": ["$ref"]
                 },
-                { "type": "string" }
+                {
+                  "type": "string"
+                }
               ]
             }
           },
@@ -34,16 +40,22 @@
             "description": "JSON Schema for validating frontmatter of content type entries.",
             "type": "object",
             "properties": {
-              "type": { "const": "object" },
+              "type": {
+                "const": "object"
+              },
               "properties": {
                 "description": "Field definitions; values are field schemas from the effective project field union.",
                 "type": "object",
-                "additionalProperties": { "$ref": "https://jxsuite.com/schema/project/fields/v2" }
+                "additionalProperties": {
+                  "$ref": "https://jxsuite.com/schema/project/fields/v2"
+                }
               },
               "required": {
                 "description": "Frontmatter fields every entry must provide.",
                 "type": "array",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               }
             }
           },
@@ -51,6 +63,126 @@
             "description": "Path to the content directory relative to the project root.",
             "examples": ["./content/blog/", "./content/docs/"],
             "type": "string"
+          },
+          "exclude": {
+            "description": "Glob patterns, relative to the source directory, for files that are never read: `internal/**`, `STYLE.md`, `**/node_modules/**`, `.*/**`. `*` and `?` stop at `/`, `**` crosses directories, `{a,b}` alternates, and dotfiles are ordinary files. A bare name with no extension (`internal`) excludes that folder as well as a file of the name. A pattern cannot climb out of the source (`../`). Excluded files are not parsed, validated, routed, linked to, searched or published, and the collection's asset mount does not serve them either: a note that refers to one gets a warning and the reference is left as written.",
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            },
+            "examples": [["internal/**", "STYLE.md", ".*/**", "**/node_modules/**"]]
+          },
+          "where": {
+            "description": "Declarative frontmatter filter: only entries whose frontmatter satisfies every key are kept. A value is a literal to equal (a scalar also matches an array field that contains it; an array or an object with no `$` keys is compared whole) or an operator object: `$eq`, `$ne`, `$in`, `$nin`, `$exists`, `$gt`, `$gte`, `$lt`, `$lte`. Keys combine with AND; there is no OR and nothing is evaluated. A filter that removes every entry is reported. Filtered entries are not validated, routed, linked to, queried or searched, and are not served from the collection's asset mount.",
+            "type": "object",
+            "propertyNames": {
+              "pattern": "^[^$]"
+            },
+            "additionalProperties": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "enum": ["$eq", "$ne", "$in", "$nin", "$exists", "$gt", "$gte", "$lt", "$lte"]
+                  },
+                  "minProperties": 1,
+                  "properties": {
+                    "$eq": {},
+                    "$ne": {},
+                    "$in": {
+                      "type": "array"
+                    },
+                    "$nin": {
+                      "type": "array"
+                    },
+                    "$exists": {
+                      "type": "boolean"
+                    },
+                    "$gt": {
+                      "type": ["string", "number"]
+                    },
+                    "$gte": {
+                      "type": ["string", "number"]
+                    },
+                    "$lt": {
+                      "type": ["string", "number"]
+                    },
+                    "$lte": {
+                      "type": ["string", "number"]
+                    }
+                  }
+                },
+                {
+                  "type": ["string", "number", "boolean", "null", "array"]
+                },
+                {
+                  "type": "object",
+                  "propertyNames": {
+                    "pattern": "^[^$]"
+                  }
+                }
+              ]
+            },
+            "examples": [
+              {
+                "publish": true,
+                "status": {
+                  "$ne": "draft"
+                }
+              }
+            ]
+          },
+          "idField": {
+            "description": "Frontmatter field whose value is the entry id, instead of the path-derived id. An entry without the field keeps its path id and is reported.",
+            "type": "string",
+            "minLength": 1,
+            "examples": ["slug"]
+          },
+          "route": {
+            "description": "A site-absolute path template. `{name}` inserts the entry id (`id`), the file's directory (`dir`), its name (`file`) or a frontmatter field (dotted paths allowed); `{name:slug}` slugifies it, and `lower`, `upper` and `raw` are also available.",
+            "examples": ["/kb/{category:slug}/{slug}/"],
+            "type": "string",
+            "pattern": "^/"
+          },
+          "indexRoute": {
+            "description": "The route template for a directory's `README.md` or `index.md`, the file a folder stands for, when it should differ from `route` (a section's page at `/kb/{dir:slug}/` rather than `/kb/{category:slug}/{slug}/`). It takes the same placeholders and transforms as `route`, and needs a `route` for every other entry.",
+            "examples": ["/kb/{dir:slug}/"],
+            "type": "string",
+            "pattern": "^/"
+          },
+          "links": {
+            "description": "How a relative link to an entry that has no page (excluded, filtered out by `where`, unrouted, or missing) is reported. The link renders as plain text in every mode. Relative links are only rewritten for content types that declare a `route`.",
+            "enum": ["warn", "error", "ignore"],
+            "default": "warn"
+          },
+          "alerts": {
+            "description": "How GitHub-style alerts (`> [!NOTE]`) in Markdown entries render. `false` turns callouts off for the whole type; `true`, or leaving the option out, renders NOTE, TIP, IMPORTANT, WARNING and CAUTION as built-in accessible markup. An object maps an alert type (case-insensitive) to the custom element that renders it, e.g. { \"NOTE\": \"doc-note\" }; `true` renders a type with the built-in markup (how a type beyond GitHub's five, such as Obsidian's `info`, is switched on); null or false leaves a type an ordinary blockquote. A well-formed marker of a type that is not enabled is reported when the file loads.",
+            "type": ["object", "boolean"],
+            "propertyNames": {
+              "pattern": "^[A-Za-z][\\w-]*$"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "string",
+                  "pattern": "^[A-Za-z][\\w.-]*$"
+                },
+                {
+                  "type": "null"
+                },
+                {
+                  "type": "boolean"
+                }
+              ]
+            },
+            "examples": [
+              {
+                "NOTE": "doc-note",
+                "TIP": "doc-tip",
+                "WARNING": "doc-warning"
+              }
+            ]
           }
         }
       }

package/src/Content.class.json

@@ -115,14 +115,17 @@
               "properties": {
                 "data": { "type": "object" },
                 "projectConfig": { "type": "object" },
-                "root": { "type": "string" }
+                "root": { "type": "string" },
+                "locale": { "type": ["string", "null"] },
+                "urlPattern": { "type": "string" },
+                "params": { "type": "array", "items": { "type": "string" } }
               }
             },
-            "description": "Host context: { data, projectConfig, root } where data is the projectData result"
+            "description": "Host context: { data, projectConfig, root, locale, urlPattern, params } where data is the projectData result and urlPattern/params describe the dynamic page being expanded"
           }
         ],
         "returnType": { "$ref": "#/$defs/returnTypes/PathEntries" },
-        "description": "Expand a content-type $paths source into one route-param object per entry (param defaults to \"slug\", field to \"id\")"
+        "description": "Expand a content-type $paths source into one route-param object per entry (param defaults to \"slug\", field to \"id\"); a content type with a route and no param or field derives each entry's parameters from the page's own URL pattern"
       },
       "assets": {
         "role": "assets",

package/src/Markdown.class.json

@@ -233,12 +233,19 @@
             "identifier": "options",
             "type": {
               "type": "object",
-              "properties": { "baseDir": { "type": "string" } }
+              "properties": {
+                "baseDir": { "type": "string" },
+                "exclude": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Glob patterns, relative to the source directory, for files and directories to leave out"
+                }
+              }
             }
           }
         ],
         "returnType": { "type": "array", "items": { "type": "string" } },
-        "description": "List markdown entry files for a content-type source"
+        "description": "List markdown entry files for a content-type source, in sorted order"
       },
       "load": {
         "role": "load",
@@ -259,7 +266,11 @@
               "type": "object",
               "properties": {
                 "directiveOptions": { "type": "object" },
-                "directives": { "type": "boolean" }
+                "directives": { "type": "boolean" },
+                "alerts": {
+                  "description": "GitHub alert type -> custom element name (or false to leave alerts as blockquotes); absent renders the built-in callouts",
+                  "oneOf": [{ "const": false }, { "type": "object" }]
+                }
               }
             }
           }

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);
+  }
+}