@refrakt-md/content 0.33.0 → 0.35.0

package/dist/validate.js

@@ -0,0 +1,154 @@
+import Markdoc from '@markdoc/markdoc';
+/**
+ * Error ids reported out of the box — SPEC-132 phases 1 and 2.
+ *
+ * An explicit allow-list rather than a deny-list, so enabling an id is a
+ * deliberate act rather than a side effect of Markdoc adding one.
+ *
+ * `variable-undefined` is absent and must stay that way. Markdoc validates the
+ * *full path*, has no scope model, and most variable use in real content is
+ * scope-local — `$item` and `$row` bound per-iteration inside rune body
+ * templates, with valid paths depending on author-defined frontmatter. Enabling
+ * it flags every collection template. See SPEC-132 D4: it is out of scope
+ * entirely rather than deferred, and needs its own spec.
+ */
+export const DEFAULT_VALIDATION_IDS = [
+    // Phase 1 (WORK-556). `tag-undefined` is the one the milestone is sold on:
+    // a mistyped rune drops its tag and renders its children as prose, so the
+    // block silently vanishes from the page.
+    'tag-undefined',
+    'attribute-undefined',
+    // Phase 2 (WORK-558), gated on WORK-557's blast-radius measurement. These
+    // are what make `required` and `matches` mean something across ~175 tags,
+    // and they are the ids that wake the custom attribute validators in
+    // `packages/runes/src/attributes.ts` and `plugins/media/src/attributes.ts`
+    // — which had never executed in a build, because `transform()` does not
+    // invoke a custom type's `validate()`.
+    'attribute-value-invalid',
+    'attribute-missing-required',
+    'attribute-type-invalid',
+];
+/** How a finding's Markdoc level maps onto `PipelineWarning.severity`.
+ *
+ *  `critical` and `error` both land on `'error'` because `PipelineWarning` has
+ *  no fifth level; the distinction that matters (D11) is not severity but
+ *  suppressibility, which {@link isSuppressible} keeps separate. */
+function severityFor(level) {
+    switch (level) {
+        case 'critical':
+        case 'error':
+            return 'error';
+        case 'warning':
+            return 'warning';
+        default:
+            return 'info';
+    }
+}
+/**
+ * Whether a finding may be silenced by configuration (SPEC-132 D5 / D11).
+ *
+ * `critical` means the document could not be *understood* — a parse error, an
+ * unclosed tag, a tag in an impossible position. That is not a matter of
+ * preference, so no config switch turns it off. Everything else is the
+ * configurable band.
+ */
+export function isSuppressible(level) {
+    return level !== 'critical';
+}
+export const DEFAULT_VALIDATION_SETTINGS = { enabled: true };
+/** Resolve the effective id allow-list for a site. */
+export function resolveValidationIds(settings) {
+    const base = settings?.ids ?? DEFAULT_VALIDATION_IDS;
+    const disabled = new Set(settings?.disableIds ?? []);
+    return new Set(base.filter((id) => !disabled.has(id)));
+}
+/** Ids the site asked to stop treating as problems, as distinct from ids that
+ *  were never enabled. The two are handled differently: a disabled id is
+ *  demoted, an id outside the allow-list is dropped. */
+function demotedIds(settings) {
+    return new Set(settings?.disableIds ?? []);
+}
+/**
+ * Validate one page's AST against the config its transform will use.
+ *
+ * Returns `PipelineWarning`s and nothing else — no node is injected into the
+ * page and no content is replaced (D9). A validation finding annotates content
+ * that rendered perfectly well, so it belongs beside the page, not in it;
+ * display is WORK-395's editor validation rail.
+ *
+ * Never throws: a validator that breaks the build it was added to protect is
+ * worse than no validator. A failure inside `Markdoc.validate` is itself
+ * reported as a finding.
+ *
+ * Three dispositions, and the difference between them is the point:
+ *
+ * | case | outcome |
+ * |---|---|
+ * | `critical` level | always reported; no configuration silences it (D11) |
+ * | id in `disableIds` | **demoted to `info`** |
+ * | id outside the allow-list, or `enabled: false` | dropped |
+ *
+ * Demotion rather than deletion is WORK-559's recorded decision. An id someone
+ * has actively judged unimportant should stop adding noise to the build
+ * summary, but it should not become invisible: a reader who goes looking — or
+ * the editor's validation rail — can still see what was set aside, and turning
+ * the id back on is then an informed choice rather than a leap. Ids that were
+ * never enabled are a different thing and are simply not reported; there is no
+ * value in an `info` stream of every check the project has decided against.
+ */
+export function validatePage(ast, config, opts) {
+    const settings = opts.settings ?? DEFAULT_VALIDATION_SETTINGS;
+    const allowed = resolveValidationIds(settings);
+    const demoted = demotedIds(settings);
+    const pluginName = opts.contributedBy ?? 'core';
+    let findings;
+    try {
+        findings = Markdoc.validate(ast, config);
+    }
+    catch (err) {
+        return [
+            {
+                severity: 'warning',
+                phase: 'validate',
+                pluginName,
+                url: opts.url,
+                message: `content validation could not run: ${err.message}`,
+            },
+        ];
+    }
+    const out = [];
+    for (const finding of findings) {
+        const level = finding.error.level;
+        const id = finding.error.id;
+        let severity = severityFor(level);
+        // `critical` is reported unconditionally — neither the master switch, the
+        // allow-list, nor `disableIds` can touch it.
+        if (isSuppressible(level)) {
+            if (!settings.enabled)
+                continue;
+            if (demoted.has(id)) {
+                severity = 'info';
+            }
+            else if (!allowed.has(id)) {
+                continue;
+            }
+        }
+        out.push({
+            severity,
+            phase: 'validate',
+            pluginName,
+            url: opts.url,
+            message: formatFinding(finding, opts.contributedBy),
+        });
+    }
+    return out;
+}
+/** Render one finding as a single line: what is wrong, where, and — for a
+ *  generated page — who generated it. */
+function formatFinding(finding, contributedBy) {
+    const line = finding.lines?.[0];
+    const at = typeof line === 'number' ? ` (line ${line + 1})` : '';
+    const origin = contributedBy ? ` [generated by ${contributedBy}]` : '';
+    return `${finding.error.id}: ${finding.error.message}${at}${origin}`;
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/frontmatter.schema.json

@@ -1,83 +1,83 @@
 {
-	"$schema": "http://json-schema.org/draft-07/schema#",
-	"$id": "https://refrakt.md/frontmatter.schema.json",
-	"title": "Frontmatter",
-	"description": "YAML frontmatter for a refrakt content page. Describes the fields refrakt itself consumes; the set is deliberately open, since runes and pipeline hooks read arbitrary author fields. The unversioned URL https://refrakt.md/frontmatter.schema.json is a 'latest' alias that always serves the most recently published schema.",
-	"type": "object",
-	"properties": {
-		"title": {
-			"description": "Page title. Used for the document title, navigation labels and social cards; falls back to the page's first H1 when omitted.",
-			"type": "string"
-		},
-		"description": {
-			"description": "Short summary, used for the meta description, social cards and the blurb on link cards.",
-			"type": "string"
-		},
-		"slug": {
-			"description": "Override the URL segment derived from the filename.",
-			"type": "string"
-		},
-		"draft": {
-			"description": "Exclude the page from the built site and from navigation.",
-			"type": "boolean"
-		},
-		"redirect": {
-			"description": "Redirect this URL elsewhere instead of rendering a page.",
-			"type": "string"
-		},
-		"order": {
-			"description": "Sort position among sibling pages in generated navigation. Lower sorts first.",
-			"type": "number"
-		},
-		"date": {
-			"description": "Publication date (ISO 8601). Used for ordering and display by blog-style listings.",
-			"type": "string"
-		},
-		"author": {
-			"description": "Author name, used in article metadata and structured data.",
-			"type": "string"
-		},
-		"tags": {
-			"description": "Free-form labels, filterable with the `field:value` grammar `collection` and `aggregate` share.",
-			"type": "array",
-			"items": { "type": "string" }
-		},
-		"image": {
-			"description": "Page image, used for social cards and as the media for link cards.",
-			"type": "string"
-		},
-		"icon": {
-			"description": "Icon name resolvable by the `icon` rune. `nav layout=\"cards\"` renders it on each child page's card.",
-			"type": "string"
-		},
-		"tint": {
-			"description": "Named tint preset for this page, or for the whole subtree when set in a `_layout.md`. Cascades down the layout chain; an explicit null resets to inherit from the layer above.",
-			"type": ["string", "null"]
-		},
-		"tint-mode": {
-			"description": "Initial colour-scheme behaviour. `auto` follows the user's preference; `light` / `dark` lock the server-rendered mode. Cascades down the layout chain.",
-			"type": "string",
-			"enum": ["auto", "light", "dark"]
-		},
-		"tint-lock": {
-			"description": "Ignore the user's theme preference and hide the theme toggle — for surfaces that should look the same to every visitor. Cascades down the layout chain.",
-			"type": "boolean"
-		},
-		"type": {
-			"description": "Register this page as an entity of the named type, so `collection`, `aggregate` and `xref` can find it. This is what drives the entity registry. A `routeRules` entry can set it for a whole subtree instead of per page.",
-			"type": "string"
-		},
-		"id": {
-			"description": "Explicit entity ID for this page. Defaults to the page's slug.",
-			"type": "string"
-		},
-		"created": {
-			"description": "Creation date (ISO 8601), overriding what git history or the filesystem reports.",
-			"type": "string"
-		},
-		"modified": {
-			"description": "Last-modified date (ISO 8601), overriding what git history or the filesystem reports.",
-			"type": "string"
-		}
-	}
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://refrakt.md/frontmatter.schema.json",
+  "title": "Frontmatter",
+  "description": "YAML frontmatter for a refrakt content page. Describes the fields refrakt itself consumes; the set is deliberately open, since runes and pipeline hooks read arbitrary author fields. The unversioned URL https://refrakt.md/frontmatter.schema.json is a 'latest' alias that always serves the most recently published schema.",
+  "type": "object",
+  "properties": {
+    "title": {
+      "description": "Page title. Used for the document title, navigation labels and social cards; falls back to the page's first H1 when omitted.",
+      "type": "string"
+    },
+    "description": {
+      "description": "Short summary, used for the meta description, social cards and the blurb on link cards.",
+      "type": "string"
+    },
+    "slug": {
+      "description": "Override the URL segment derived from the filename.",
+      "type": "string"
+    },
+    "draft": {
+      "description": "Exclude the page from the built site and from navigation.",
+      "type": "boolean"
+    },
+    "redirect": {
+      "description": "Redirect this URL elsewhere instead of rendering a page.",
+      "type": "string"
+    },
+    "order": {
+      "description": "Sort position among sibling pages in generated navigation. Lower sorts first.",
+      "type": "number"
+    },
+    "date": {
+      "description": "Publication date (ISO 8601). Used for ordering and display by blog-style listings.",
+      "type": "string"
+    },
+    "author": {
+      "description": "Author name, used in article metadata and structured data.",
+      "type": "string"
+    },
+    "tags": {
+      "description": "Free-form labels, filterable with the `field:value` grammar `collection` and `aggregate` share.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "image": {
+      "description": "Page image, used for social cards and as the media for link cards.",
+      "type": "string"
+    },
+    "icon": {
+      "description": "Icon name resolvable by the `icon` rune. `nav layout=\"cards\"` renders it on each child page's card.",
+      "type": "string"
+    },
+    "tint": {
+      "description": "Named tint preset for this page, or for the whole subtree when set in a `_layout.md`. Cascades down the layout chain; an explicit null resets to inherit from the layer above.",
+      "type": ["string", "null"]
+    },
+    "tint-mode": {
+      "description": "Initial colour-scheme behaviour. `auto` follows the user's preference; `light` / `dark` lock the server-rendered mode. Cascades down the layout chain.",
+      "type": "string",
+      "enum": ["auto", "light", "dark"]
+    },
+    "tint-lock": {
+      "description": "Ignore the user's theme preference and hide the theme toggle — for surfaces that should look the same to every visitor. Cascades down the layout chain.",
+      "type": "boolean"
+    },
+    "type": {
+      "description": "Register this page as an entity of the named type, so `collection`, `aggregate` and `xref` can find it. This is what drives the entity registry. A `routeRules` entry can set it for a whole subtree instead of per page.",
+      "type": "string"
+    },
+    "id": {
+      "description": "Explicit entity ID for this page. Defaults to the page's slug.",
+      "type": "string"
+    },
+    "created": {
+      "description": "Creation date (ISO 8601), overriding what git history or the filesystem reports.",
+      "type": "string"
+    },
+    "modified": {
+      "description": "Last-modified date (ISO 8601), overriding what git history or the filesystem reports.",
+      "type": "string"
+    }
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/content",
   "description": "Content loading and transformation pipeline",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -30,10 +30,10 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/highlight": "0.33.0",
-    "@refrakt-md/runes": "0.33.0",
-    "@refrakt-md/transform": "0.33.0",
-    "@refrakt-md/types": "0.33.0",
+    "@refrakt-md/highlight": "0.35.0",
+    "@refrakt-md/runes": "0.35.0",
+    "@refrakt-md/transform": "0.35.0",
+    "@refrakt-md/types": "0.35.0",
     "@markdoc/markdoc": "0.4.0",
     "yaml": "^2.4.0"
   }