@jxsuite/parser 4.1.2 → 4.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "4.1.2",
+  "version": "4.3.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -48,11 +48,11 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@jxsuite/markup": "^1.0.2",
-    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/markup": "^1.0.4",
+    "@jxsuite/schema": "^5.2.0",
     "@shikijs/langs": "^4.5.0",
     "@shikijs/themes": "^4.5.0",
-    "glob": "^13.0.6",
+    "glob": "^14.0.3",
     "mdast-util-to-string": "^4.0.0",
     "remark-directive": "^4.0.0",
     "remark-frontmatter": "^5.0.0",
@@ -67,7 +67,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/runtime": "^6.0.1",
+    "@jxsuite/runtime": "^6.1.0",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4",
     "ajv": "^8.20.0"

package/schemas/project.fragment.schema.json

@@ -100,16 +100,76 @@
                       "type": "boolean"
                     },
                     "$gt": {
-                      "type": ["string", "number"]
+                      "anyOf": [
+                        {
+                          "type": ["string", "number"]
+                        },
+                        {
+                          "type": "object",
+                          "description": "The moment the rule is evaluated: the build machine's real clock.",
+                          "properties": {
+                            "$now": {
+                              "const": true
+                            }
+                          },
+                          "required": ["$now"],
+                          "additionalProperties": false
+                        }
+                      ]
                     },
                     "$gte": {
-                      "type": ["string", "number"]
+                      "anyOf": [
+                        {
+                          "type": ["string", "number"]
+                        },
+                        {
+                          "type": "object",
+                          "description": "The moment the rule is evaluated: the build machine's real clock.",
+                          "properties": {
+                            "$now": {
+                              "const": true
+                            }
+                          },
+                          "required": ["$now"],
+                          "additionalProperties": false
+                        }
+                      ]
                     },
                     "$lt": {
-                      "type": ["string", "number"]
+                      "anyOf": [
+                        {
+                          "type": ["string", "number"]
+                        },
+                        {
+                          "type": "object",
+                          "description": "The moment the rule is evaluated: the build machine's real clock.",
+                          "properties": {
+                            "$now": {
+                              "const": true
+                            }
+                          },
+                          "required": ["$now"],
+                          "additionalProperties": false
+                        }
+                      ]
                     },
                     "$lte": {
-                      "type": ["string", "number"]
+                      "anyOf": [
+                        {
+                          "type": ["string", "number"]
+                        },
+                        {
+                          "type": "object",
+                          "description": "The moment the rule is evaluated: the build machine's real clock.",
+                          "properties": {
+                            "$now": {
+                              "const": true
+                            }
+                          },
+                          "required": ["$now"],
+                          "additionalProperties": false
+                        }
+                      ]
                     }
                   }
                 },
@@ -133,6 +193,165 @@
               }
             ]
           },
+          "hold": {
+            "description": "What keeps an entry out of a production build while authors still see it. Any rule matching holds the entry, and the first names why. `jx build` leaves held entries out, `jx build --include-held`, `jx dev` and Studio keep them. Jx gives no field a meaning of its own: a project names its fields and says here what they imply.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["label", "when"],
+              "properties": {
+                "label": {
+                  "description": "The words every surface shows for an entry this rule holds.",
+                  "type": "string",
+                  "minLength": 1
+                },
+                "when": {
+                  "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": {
+                            "anyOf": [
+                              {
+                                "type": ["string", "number"]
+                              },
+                              {
+                                "type": "object",
+                                "description": "The moment the rule is evaluated: the build machine's real clock.",
+                                "properties": {
+                                  "$now": {
+                                    "const": true
+                                  }
+                                },
+                                "required": ["$now"],
+                                "additionalProperties": false
+                              }
+                            ]
+                          },
+                          "$gte": {
+                            "anyOf": [
+                              {
+                                "type": ["string", "number"]
+                              },
+                              {
+                                "type": "object",
+                                "description": "The moment the rule is evaluated: the build machine's real clock.",
+                                "properties": {
+                                  "$now": {
+                                    "const": true
+                                  }
+                                },
+                                "required": ["$now"],
+                                "additionalProperties": false
+                              }
+                            ]
+                          },
+                          "$lt": {
+                            "anyOf": [
+                              {
+                                "type": ["string", "number"]
+                              },
+                              {
+                                "type": "object",
+                                "description": "The moment the rule is evaluated: the build machine's real clock.",
+                                "properties": {
+                                  "$now": {
+                                    "const": true
+                                  }
+                                },
+                                "required": ["$now"],
+                                "additionalProperties": false
+                              }
+                            ]
+                          },
+                          "$lte": {
+                            "anyOf": [
+                              {
+                                "type": ["string", "number"]
+                              },
+                              {
+                                "type": "object",
+                                "description": "The moment the rule is evaluated: the build machine's real clock.",
+                                "properties": {
+                                  "$now": {
+                                    "const": true
+                                  }
+                                },
+                                "required": ["$now"],
+                                "additionalProperties": false
+                              }
+                            ]
+                          }
+                        }
+                      },
+                      {
+                        "type": ["string", "number", "boolean", "null", "array"]
+                      },
+                      {
+                        "type": "object",
+                        "propertyNames": {
+                          "pattern": "^[^$]"
+                        }
+                      }
+                    ]
+                  },
+                  "description": "The frontmatter that matches this rule, with the grammar of `where`.",
+                  "minProperties": 1
+                }
+              }
+            },
+            "examples": [
+              [
+                {
+                  "label": "Draft",
+                  "when": {
+                    "draft": true
+                  }
+                },
+                {
+                  "label": "Scheduled",
+                  "when": {
+                    "publishDate": {
+                      "$gt": {
+                        "$now": true
+                      }
+                    }
+                  }
+                }
+              ]
+            ]
+          },
           "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",

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/ContentCollection.class.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ContentCollection",
-  "description": "Query a project content type with filter, sort, and limit",
+  "description": "Query one or more project content types with filter, sort, and limit",
   "$prototype": "Class",
   "extends": "Object",
   "$implementation": "../dist/content.js",
@@ -11,7 +11,7 @@
       "contentType": {
         "identifier": "contentType",
         "type": { "type": "string", "enum": { "$ref": "#/$context/content" } },
-        "description": "Content type to query"
+        "description": "Content type to query. A list of types (written in JSON) is queried as one list, filtered, sorted and cut together"
       },
       "filter": {
         "identifier": "filter",
@@ -40,12 +40,14 @@
                   "not empty"
                 ]
               },
-              "value": {}
+              "value": {
+                "description": "The value to compare with, or a reference resolved for the page: { \"$ref\": \"#/$params/<name>\" } is a route parameter and { \"$ref\": \"#/state/<pointer>\" } a value in an entry declared earlier in state"
+              }
             },
             "required": ["field", "op"]
           }
         },
-        "description": "Filter rules"
+        "description": "Filter rules. A field may be a dotted path through the entry's data (terms.category.slug); a path that crosses an array collects every item's value"
       },
       "sort": {
         "identifier": "sort",
@@ -64,7 +66,7 @@
             "required": ["field"]
           }
         },
-        "description": "Sort rules"
+        "description": "Sort rules. A field may be a dotted path, as in a filter rule"
       },
       "limit": {
         "identifier": "limit",

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 ?? {},