@jxsuite/parser 4.2.0 → 4.3.0

package/src/Content.class.json

@@ -78,6 +78,10 @@
               "properties": {
                 "projectConfig": { "type": "object" },
                 "root": { "type": "string" },
+                "includeHeld": {
+                  "type": "boolean",
+                  "description": "Keep entries a type's `hold` rules match, labelled, rather than leaving them out"
+                },
                 "registry": { "type": "object" },
                 "io": { "type": "object" }
               }

package/src/content-loader.ts

@@ -55,8 +55,8 @@ import {
   traversalReason,
 } from "./content-routes.ts";
 import type { RouteSpec } from "./content-routes.ts";
-import { compileExclude, compileWhere } from "./content-rules.ts";
-import type { ExcludeMatcher, WherePredicate } from "./content-rules.ts";
+import { compileExclude, compileHold, compileWhere } from "./content-rules.ts";
+import type { ExcludeMatcher, HoldPredicate, WherePredicate } from "./content-rules.ts";
 import { coerceEntryDates, isCoercedDate, isDateFormat } from "./dates.ts";
 import type { ContentNodes } from "./inert.ts";
 import type { ContentLoaderEntry, ContentTypeDef } from "./types.ts";
@@ -260,16 +260,22 @@ const DOCUMENT_EXTENSIONS = new Set([".md", ".markdown", ".mdx"]);
  * What a content type's asset mount may serve, or `undefined` for "everything under the directory"
  * (today's behavior, which every type that declares none of the vault options keeps).
  *
- * A type that declares `exclude`, `where` or `route` is publishing a folder of notes, and there the
- * mount is the collection's front door, so it must not be a way around the collection's own rules:
- * a file `exclude` names is not served however a page refers to it, nothing whose path has a dot
- * segment is (`.git`, `.env` and `.obsidian` are what a source set to the repository root also
- * contains), and a document is not (a note `where` left out would otherwise leave as a raw
+ * A type that declares `exclude`, `where`, `hold` or `route` is publishing a folder of notes, and
+ * there the mount is the collection's front door, so it must not be a way around the collection's
+ * own rules: a file `exclude` names is not served however a page refers to it, nothing whose path
+ * has a dot segment is (`.git`, `.env` and `.obsidian` are what a source set to the repository root
+ * also contains), and a document is not (a note `where` left out would otherwise leave as a raw
  * download, frontmatter and all). The paths it is asked about are relative to the mount directory,
  * which is the source directory.
  */
 function mountFilterFor(def: ContentTypeDef | undefined): ((path: string) => boolean) | undefined {
-  if (!def || (def.exclude === undefined && def.where === undefined && def.route === undefined)) {
+  if (
+    !def ||
+    (def.exclude === undefined &&
+      def.where === undefined &&
+      def.hold === undefined &&
+      def.route === undefined)
+  ) {
     return undefined;
   }
   let exclude: ExcludeMatcher;
@@ -551,6 +557,8 @@ export function loadContentConfig(projectRoot: string, projectConfig?: ProjectCo
  * @param {ContentSection} section - The project.json `content` section value
  * @param {string} root - Project root directory
  * @param {FormatRegistry} formats - Format-dispatch view of the extension registry
+ * @param {ProjectConfig} [projectConfig]
+ * @param {boolean} [includeHeld] - Keep entries the `hold` rules match, labelled
  * @returns {Promise<Map<string, ContentLoaderEntry[]>>} Map of content type name → entries
  */
 export async function loadContentSection(
@@ -558,13 +566,14 @@ export async function loadContentSection(
   root: string,
   formats: FormatRegistry,
   projectConfig?: ProjectConfig,
+  includeHeld?: boolean,
 ): Promise<Map<string, ContentLoaderEntry[]>> {
   const contentTypes = new Map<string, ContentLoaderEntry[]>();
   const mounts = sectionMounts(section, root, projectConfig);
   for (const name of Object.keys(section)) {
     contentTypes.set(
       name,
-      await loadSectionType(name, { formats, mounts, projectConfig, root, section }),
+      await loadSectionType(name, { formats, includeHeld, mounts, projectConfig, root, section }),
     );
   }
   return contentTypes;
@@ -601,6 +610,8 @@ export interface SectionTypeSource {
   mounts: Map<string, AssetMount>;
   /** Leave entry bodies for later, reporting each deferred entry here. */
   onDeferred?: DeferredBodyHandler | undefined;
+  /** Keep entries the type's `hold` rules match, labelled, rather than leaving them out. */
+  includeHeld?: boolean | undefined;
 }
 
 /**
@@ -614,7 +625,7 @@ export async function loadSectionType(
   name: string,
   source: SectionTypeSource,
 ): Promise<ContentLoaderEntry[]> {
-  const { section, root, formats, projectConfig, mounts, onDeferred } = source;
+  const { section, root, formats, projectConfig, mounts, onDeferred, includeHeld } = source;
   const contentTypeDef = section[name];
   if (!contentTypeDef) {
     return [];
@@ -623,6 +634,7 @@ export async function loadSectionType(
   const typeSource = contentTypeDef.source;
   if (!isString(typeSource) || !typeSource.includes(LOCALE_PLACEHOLDER)) {
     return await loadContentType(name, contentTypeDef, root, formats, {
+      includeHeld,
       mount: mounts.get(name),
       projectConfig,
       ...deferral,
@@ -645,6 +657,7 @@ export async function loadSectionType(
   for (const locale of locales) {
     const localized = { ...contentTypeDef, source: localeSource(root, typeSource, locale) };
     const entries = await loadContentType(name, localized, root, formats, {
+      includeHeld,
       locale,
       mount: mounts.get(`${name}/${locale}`),
       projectConfig,
@@ -686,6 +699,7 @@ type LinkMode = "warn" | "error" | "ignore";
 interface TypeRules {
   exclude: ExcludeMatcher;
   where: WherePredicate | null;
+  hold: HoldPredicate | null;
   idField: string | undefined;
   route: RouteSpec | null;
   links: LinkMode;
@@ -706,6 +720,7 @@ const KNOWN_TYPE_KEYS = [
   "alerts",
   "exclude",
   "format",
+  "hold",
   "idField",
   "indexRoute",
   "links",
@@ -792,6 +807,7 @@ function compileTypeRules(name: string, def: ContentTypeDef): TypeRules {
       links,
       route: parseRouteConfig(def.route, def.indexRoute, name),
       where: def.where === undefined ? null : compileWhere(def.where),
+      hold: def.hold === undefined ? null : compileHold(def.hold),
     };
   } catch (error) {
     const message = errorMessage(error);
@@ -831,6 +847,8 @@ interface FinishContext {
   reload?: ((filePath: string) => Promise<ContentLoaderEntry[]>) | undefined;
   /** Told of each entry whose body was deferred, with what completes it. */
   onDeferred?: DeferredBodyHandler | undefined;
+  /** Keep entries `hold` matches, labelled, rather than leaving them out. */
+  includeHeld?: boolean | undefined;
 }
 
 /**
@@ -845,10 +863,11 @@ export type DeferredBodyHandler = (
 /**
  * The collection-wide pass every source kind goes through once its files are loaded.
  *
- * Order matters and is the whole design. `where` runs first, so an entry that is not published is
- * never validated, coerced, given a route or counted as a duplicate. Ids are settled before
- * anything keyed by id (relationships, duplicate checks, routes that read `{id}`). Routes are
- * computed before links, because a link can only be resolved once the page it points at has a URL.
+ * Order matters and is the whole design. `where` and `hold` run first, so an entry that is not
+ * published is never validated, coerced, given a route or counted as a duplicate. Ids are settled
+ * before anything keyed by id (relationships, duplicate checks, routes that read `{id}`). Routes
+ * are computed before links, because a link can only be resolved once the page it points at has a
+ * URL.
  *
  * @returns {ContentLoaderEntry[]} The kept entries, in load order
  */
@@ -858,6 +877,7 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
   // 1. where: split every file's entries into kept and left out.
   const kept: LoadedFile[] = [];
   const unpublished = new Map<string, string>();
+  const held: string[] = [];
   let loadedCount = 0;
   for (const file of files) {
     const keep: ContentLoaderEntry[] = [];
@@ -867,8 +887,19 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
         if (file.rel !== null && file.entries.length === 1) {
           unpublished.set(file.rel, `left out by where.${rules.where.why(entry.data) ?? "filter"}`);
         }
-      } else {
+        continue;
+      }
+      const hold = rules.hold?.(entry.data);
+      if (hold === undefined) {
         keep.push(entry);
+      } else if (ctx.includeHeld === true) {
+        entry._meta = { ...entry._meta, hold };
+        keep.push(entry);
+      } else {
+        held.push(`${file.rel ?? entry.id} (${hold})`);
+        if (file.rel !== null && file.entries.length === 1) {
+          unpublished.set(file.rel, `held: ${hold}`);
+        }
       }
     }
     if (keep.length > 0) {
@@ -886,6 +917,14 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
     );
   }
 
+  /* Said, not warned: holding an entry is the project's own rule working. It is still said, because
+     an entry that disappears from a site with no message reads as a bug. */
+  if (held.length > 0) {
+    console.info(
+      `Content type "${name}": holding ${held.length} from this build: ${held.join(", ")}`,
+    );
+  }
+
   // 2. Per kept entry: where it came from, and content-relative assets onto the mount.
   for (const file of kept) {
     for (const entry of file.entries) {
@@ -1302,6 +1341,8 @@ interface LoadOptions {
    */
   deferBody?: boolean | undefined;
   onDeferred?: DeferredBodyHandler | undefined;
+  /** Keep entries the type's `hold` rules match, labelled, rather than leaving them out. */
+  includeHeld?: boolean | undefined;
 }
 
 /**
@@ -1325,12 +1366,13 @@ async function loadContentType(
   if (!source) {
     return [];
   }
-  const { mount, projectConfig, locale, deferBody, onDeferred } = options;
+  const { mount, projectConfig, locale, deferBody, onDeferred, includeHeld } = options;
   const { schema } = contentTypeDef;
   const rules = compileTypeRules(name, contentTypeDef);
   const finishContext = (extra: Partial<FinishContext>): FinishContext => ({
     coerceDates: false,
     entryExtensions: new Set<string>(),
+    includeHeld,
     locale,
     mount,
     name,
@@ -1822,6 +1864,8 @@ export interface ContentStoreSource {
   root: string;
   formats: FormatRegistry;
   projectConfig: ProjectConfig | undefined;
+  /** Keep entries the type's `hold` rules match, labelled, rather than leaving them out. */
+  includeHeld?: boolean | undefined;
 }
 
 export class ContentStore extends Map<string, ContentLoaderEntry[]> implements ContentSectionData {
@@ -1852,6 +1896,7 @@ export class ContentStore extends Map<string, ContentLoaderEntry[]> implements C
       source.root,
       source.formats,
       source.projectConfig,
+      source.includeHeld,
     );
     for (const [name, entries] of loaded) {
       store.#adopt(name, entries);
@@ -1964,8 +2009,9 @@ export class ContentStore extends Map<string, ContentLoaderEntry[]> implements C
   #loadType(name: string): Promise<void> {
     let load = this.#loads.get(name);
     if (!load) {
-      const { section, root, formats, projectConfig } = this.#source;
+      const { section, root, formats, projectConfig, includeHeld } = this.#source;
       load = loadSectionType(name, {
+        includeHeld,
         formats,
         mounts: this.#mounts,
         onDeferred: (entry, completeBody) => {
@@ -2045,6 +2091,7 @@ export class Content {
   ): Promise<ContentStore> {
     const source = {
       formats: ctx.registry.formats,
+      includeHeld: ctx.includeHeld,
       projectConfig: ctx.projectConfig,
       root: ctx.root,
       section: sectionValue ?? {},

package/src/content-rules.ts

@@ -1,6 +1,8 @@
 /**
- * Content rules — the two declarative filters a content type can carry: `exclude` (which files are
- * never read) and `where` (which entries are kept once their frontmatter is known).
+ * Content rules — the declarative filters a content type can carry: `exclude` (which files are
+ * never read), here, and `where` and `hold` (what is kept once frontmatter is known), which live in
+ * `@jxsuite/schema/content-query` because Studio has to answer them too and a core package may not
+ * import an extension.
  *
  * Both are **data, never code**. A `project.json` is read by Studio, by the dev server and by CI,
  * so a filter that needed `eval` or a function would make every one of those a place that executes
@@ -16,8 +18,10 @@
  * @docs framework/site/content-collections
  */
 
-import { isBoolean, isNumber, isString } from "@jxsuite/schema/guards";
-import type { ContentFieldValue, ContentLoaderEntry, JsonValue } from "@jxsuite/schema/types";
+import { isString } from "@jxsuite/schema/guards";
+
+export { compileHold, compileWhere, readField } from "@jxsuite/schema/content-query";
+export type { HoldPredicate, HoldRule, WherePredicate } from "@jxsuite/schema/content-query";
 
 // ─── exclude: globs relative to the source root ─────────────────────────────
 
@@ -267,219 +271,3 @@ export function compileExclude(patterns?: readonly string[]): ExcludeMatcher {
     excludedBy: (path) => files.find((f) => f.re.test(path))?.pattern,
   };
 }
-
-// ─── where: a declarative frontmatter filter ────────────────────────────────
-
-/** An entry's frontmatter as a filter reads it: field name → value, absent when it is not set. */
-type FieldData = ContentLoaderEntry["data"];
-
-/** A field value, or an operand, in the form a filter compares; `undefined` is a missing field. */
-type FieldValue = ContentFieldValue | undefined;
-
-/** Whether an entry's frontmatter passes a compiled `where`. */
-export interface WherePredicate {
-  (data: FieldData): boolean;
-  /**
-   * The first field whose condition `data` fails, for a message that says why an entry was left
-   * out.
-   */
-  why: (data: FieldData) => string | undefined;
-}
-
-/** The query operators. Closed on purpose: see the module comment. */
-const OPERATORS = new Set(["$eq", "$ne", "$in", "$nin", "$exists", "$gt", "$gte", "$lt", "$lte"]);
-
-function isPlainObject(value: FieldValue | FieldData): value is FieldData {
-  return (
-    typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date)
-  );
-}
-
-/** A frontmatter value in the form a filter compares: YAML dates become RFC 3339 text. */
-function comparable(value: FieldValue): FieldValue {
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) {
-      return undefined;
-    }
-    const iso = value.toISOString();
-    return iso.endsWith("T00:00:00.000Z") ? iso.slice(0, 10) : iso.replace(/\.\d{3}Z$/, "Z");
-  }
-  return value;
-}
-
-function deepEqual(a: FieldValue, b: FieldValue): boolean {
-  if (a === b) {
-    return true;
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return (
-      a.length === b.length && a.every((item, i) => deepEqual(comparable(item), comparable(b[i])))
-    );
-  }
-  if (isPlainObject(a) && isPlainObject(b)) {
-    const keys = Object.keys(a);
-    return (
-      keys.length === Object.keys(b).length &&
-      keys.every((key) => key in b && deepEqual(comparable(a[key]), comparable(b[key])))
-    );
-  }
-  return false;
-}
-
-/**
- * Equality, with one convenience that earns its keep: a scalar matches an array field that CONTAINS
- * it, so `{"tags": "frappe"}` selects every entry tagged frappe without a second operator. An array
- * or object operand compares as a whole value.
- */
-function sameValue(actual: FieldValue, expected: JsonValue | undefined): boolean {
-  const a = comparable(actual);
-  if (Array.isArray(expected) || isPlainObject(expected)) {
-    return deepEqual(a, expected);
-  }
-  if (Array.isArray(a)) {
-    return a.some((item) => comparable(item) === expected);
-  }
-  return a === expected;
-}
-
-/** Read a frontmatter field: a literal key first, then a dotted path into nested data. */
-export function readField(data: FieldData, key: string): FieldValue {
-  // Own properties only: `constructor` and `toString` are not frontmatter, whatever `in` says.
-  if (Object.hasOwn(data, key)) {
-    return data[key];
-  }
-  if (!key.includes(".")) {
-    return undefined;
-  }
-  return readPath(data, key.split("."));
-}
-
-/** Follow a dotted path's parts through nested objects, own properties only like {@link readField}. */
-function readPath(holder: FieldValue | FieldData, [part, ...rest]: readonly string[]): FieldValue {
-  if (part === undefined || !isPlainObject(holder) || !Object.hasOwn(holder, part)) {
-    return undefined;
-  }
-  const value = holder[part];
-  return rest.length === 0 ? value : readPath(value, rest);
-}
-
-/** Order two comparable values; undefined when they are not the same kind of thing. */
-function order(actual: FieldValue, operand: string | number): number | undefined {
-  const a = comparable(actual);
-  if (isNumber(a) && isNumber(operand)) {
-    return a - operand;
-  }
-  if (isString(a) && isString(operand)) {
-    return a < operand ? -1 : a > operand ? 1 : 0;
-  }
-  return undefined;
-}
-
-type FieldTest = (actual: FieldValue) => boolean;
-
-function operatorTest(where: string, op: string, operand: JsonValue | undefined): FieldTest {
-  switch (op) {
-    case "$eq": {
-      return (actual) => sameValue(actual, operand);
-    }
-    case "$ne": {
-      return (actual) => !sameValue(actual, operand);
-    }
-    case "$in":
-    case "$nin": {
-      if (!Array.isArray(operand)) {
-        throw new TypeError(`${where}.${op}: expected an array, got ${JSON.stringify(operand)}`);
-      }
-      const hit: FieldTest = (actual) => operand.some((candidate) => sameValue(actual, candidate));
-      return op === "$in" ? hit : (actual) => !hit(actual);
-    }
-    case "$exists": {
-      if (!isBoolean(operand)) {
-        throw new TypeError(
-          `${where}.$exists: expected true or false, got ${JSON.stringify(operand)}`,
-        );
-      }
-      // An empty YAML key is null, and "set to nothing" is not a value an author means by "exists".
-      return (actual) => (actual !== undefined && actual !== null) === operand;
-    }
-    default: {
-      if (!isString(operand) && !isNumber(operand)) {
-        throw new TypeError(
-          `${where}.${op}: expected a string or number, got ${JSON.stringify(operand)}`,
-        );
-      }
-      const test = (diff: number) =>
-        op === "$gt" ? diff > 0 : op === "$gte" ? diff >= 0 : op === "$lt" ? diff < 0 : diff <= 0;
-      return (actual) => {
-        const diff = order(actual, operand);
-        return diff !== undefined && test(diff);
-      };
-    }
-  }
-}
-
-/** A condition object is an operator set when every key is `$`-prefixed. */
-function operatorKeys(condition: FieldData): string[] | null {
-  const keys = Object.keys(condition);
-  const dollars = keys.filter((key) => key.startsWith("$"));
-  if (dollars.length === 0) {
-    return null;
-  }
-  return dollars.length === keys.length ? keys : [];
-}
-
-function compileCondition(key: string, condition: JsonValue): FieldTest {
-  const where = `where.${key}`;
-  if (!isPlainObject(condition)) {
-    return (actual) => sameValue(actual, condition);
-  }
-  const ops = operatorKeys(condition);
-  if (ops === null) {
-    // A plain object with no operators is a literal value to compare whole.
-    return (actual) => deepEqual(comparable(actual), condition);
-  }
-  if (ops.length === 0) {
-    throw new TypeError(`${where}: cannot mix $operators with plain keys in one condition`);
-  }
-  const tests = ops.map((op) => {
-    if (!OPERATORS.has(op)) {
-      throw new TypeError(`${where}: unknown operator "${op}" (use ${[...OPERATORS].join(", ")})`);
-    }
-    return operatorTest(where, op, condition[op]);
-  });
-  return (actual) => tests.every((test) => test(actual));
-}
-
-/**
- * Compile a `where` filter into a predicate over an entry's frontmatter.
- *
- * Every key is a frontmatter field (a dotted path reaches into nested data), keys combine with AND,
- * and a value is either a literal to equal or an operator object (`$eq`, `$ne`, `$in`, `$nin`,
- * `$exists`, `$gt`, `$gte`, `$lt`, `$lte`; several in one object combine with AND too). There is no
- * OR and no evaluation of text: a project that needs "either" splits it into two content types.
- *
- * @param {JsonValue} [where]
- * @returns {WherePredicate}
- */
-export function compileWhere(where?: JsonValue): WherePredicate {
-  if (where === undefined) {
-    return Object.assign(() => true, { why: nothing });
-  }
-  if (!isPlainObject(where)) {
-    throw new TypeError(`"where" must be an object mapping frontmatter fields to conditions`);
-  }
-  const tests = Object.entries(where).map(([key, condition]) => {
-    if (key.startsWith("$")) {
-      throw new TypeError(
-        `where.${key}: top-level operators are not supported, conditions on different fields already combine with AND`,
-      );
-    }
-    return { key, test: compileCondition(key, condition) };
-  });
-  return Object.assign(
-    (data: FieldData) => tests.every(({ key, test }) => test(readField(data, key))),
-    {
-      why: (data: FieldData) => tests.find(({ key, test }) => !test(readField(data, key)))?.key,
-    },
-  );
-}

package/src/serialize.ts

@@ -27,6 +27,7 @@ import {
   isNumber,
   isRef,
   isString,
+  isTemplateString,
   tagNameCandidates,
 } from "@jxsuite/schema/guards";
 import type { TagNameSlot } from "@jxsuite/schema/guards";
@@ -561,6 +562,10 @@ function normalizeAllowlist(allowlist?: ReadonlySet<string> | string[]): Readonl
 
 /** Check if a Jx element has properties beyond the mdast-compatible ones. */
 function hasJxProps(el: JxElement) {
+  // A computed-children template has no Markdown spelling, so even a `p` needs a directive to hold it.
+  if (isTemplateString(el.children)) {
+    return true;
+  }
   for (const key of Object.keys(el)) {
     if (
       key === "tagName" ||
@@ -923,7 +928,11 @@ function collectDirectiveAttrs(el: JxElement) {
       continue;
     }
     if (key === "children") {
-      if (isJsonObject(value)) {
+      /* An array is the directive's body. A legacy repeater object and a computed-children template
+         (spec.md §8.4) have no body to be, so the attribute is the only place they can survive a
+         save. Dropping the template wrote `::div` for `::div{children="${item.$children ?? []}"}`,
+         and the element lost what it draws with no error anywhere. */
+      if (isJsonObject(value) || isTemplateString(value)) {
         propsObj.children = value;
       }
       continue;

package/src/types.ts

@@ -44,6 +44,11 @@ export interface ContentTypeDef {
   exclude?: string[];
   /** Declarative frontmatter filter: only entries that satisfy it are kept. */
   where?: JsonObject;
+  /**
+   * What keeps an entry out of a production build and shows it to authors (site-architecture.md
+   * §7.6). Any rule matching holds the entry, and the first names why.
+   */
+  hold?: JsonObject[];
   /** Frontmatter field whose value is the entry id (the path-derived id when absent). */
   idField?: string;
   /** Route template giving each entry its URL. */