@wxxb789/anc 0.0.2 → 0.0.3

package/src/lib/schema.js

@@ -7,6 +7,7 @@
  * loud build failure rather than a silent privacy leak.
  */
 import { compareSlugs, isNoteSlug, SLUG_MAX_BYTES } from "./route-path.js";
+import { isPositiveDimension, parseAssetUrl } from "./media.js";
 export const SCHEMA_VERSION = 1;
 /** Top-level route segments the site owns; a note slug may not collide with them. */
 export const RESERVED_SLUGS = new Set([
@@ -84,6 +85,23 @@ const KNOWN_FIELDS = new Set([
     ...REQUIRED_STRINGS,
     ...OPTIONAL_FIELDS,
 ]);
+/** Top-level artifact keys, for the one unknown-field check. */
+const ARTIFACT_FIELDS = new Set(['version', 'entries', 'assets']);
+/** One asset declaration's keys. */
+const ASSET_FIELDS = new Set(['url', 'width', 'height']);
+/**
+ * Refuse every key outside `allowed`, under the caller's own field label.
+ *
+ * The artifact, each entry, and each asset declaration each reject unknown
+ * fields as a producer defect. One helper keeps the message and the rule from
+ * being spelled three slightly different ways.
+ */
+function unknownFields(value, allowed, prefix, issues) {
+    for (const field of Object.keys(value)) {
+        if (!allowed.has(field))
+            issues.push(`${prefix}${field}: unknown field is not allowed`);
+    }
+}
 /**
  * Size ceilings, stated per field.
  *
@@ -405,10 +423,7 @@ function checkEntry(value, index, issues) {
     const slug = value['slug'];
     const label = typeof slug === 'string' ? `entries[${index}] (slug "${slug}")` : `entries[${index}]`;
     const before = issues.length;
-    for (const field of Object.keys(value)) {
-        if (!KNOWN_FIELDS.has(field))
-            issues.push(`${label}.${field}: unknown field is not allowed`);
-    }
+    unknownFields(value, KNOWN_FIELDS, `${label}.`, issues);
     for (const field of REQUIRED_STRINGS) {
         const item = value[field];
         if (typeof item !== 'string')
@@ -528,6 +543,68 @@ function checkCorpus(entries, issues, edges) {
         }
     }
 }
+/**
+ * The image assets this artifact publishes. Every entry names a canonical
+ * `/_assets/<sha256>-<name>` URL — one spelling per asset, so the emission step
+ * and the inventory cannot disagree about which file a URL names — and the list
+ * is sorted and unique, so two builds of the same corpus serialize the same
+ * bytes. A URL that is not canonical is a producer defect rather than an
+ * author's mistake, and it fails here rather than in a filename lookup.
+ *
+ * `width`/`height` are the **CSS layout size** of the published picture: the
+ * emitted header's pixel size for a raster, and the logical size for an SVG
+ * rasterized at 2× (a 600-pixel diagram publishes a 1,200-pixel WebP and lays out
+ * at 600). They are a pair or absent: one without the other describes no aspect
+ * ratio a browser can reserve, and the producer never writes a guess. Their only
+ * consumer is the renderer's layout attributes; they do not participate in
+ * identity.
+ */
+function checkAssets(rawAssets, issues) {
+    if (rawAssets === undefined)
+        return;
+    if (!Array.isArray(rawAssets)) {
+        issues.push('assets: must be an array of published asset declarations');
+        return;
+    }
+    const seen = new Set();
+    let previous;
+    for (const [index, value] of rawAssets.entries()) {
+        if (!isPlainObject(value)) {
+            issues.push(`assets[${index}]: must be an object with a url`);
+            continue;
+        }
+        unknownFields(value, ASSET_FIELDS, `assets[${index}].`, issues);
+        const url = value['url'];
+        if (typeof url !== 'string') {
+            issues.push(`assets[${index}].url: must be a string`);
+            continue;
+        }
+        if (parseAssetUrl(url) === undefined) {
+            issues.push(`assets[${index}].url: is not a canonical published asset path (/_assets/<sha256>-<name>)`);
+            continue;
+        }
+        const width = value['width'];
+        const height = value['height'];
+        if ((width === undefined) !== (height === undefined)) {
+            issues.push(`assets[${index}]: width and height must be declared together`);
+        }
+        for (const [field, dimension] of [
+            ['width', width],
+            ['height', height],
+        ]) {
+            if (dimension !== undefined && !isPositiveDimension(dimension)) {
+                issues.push(`assets[${index}].${field}: must be a positive integer`);
+            }
+        }
+        if (seen.has(url))
+            issues.push(`assets[${index}]: appears twice`);
+        seen.add(url);
+        if (previous !== undefined && !(previous < url)) {
+            issues.push(`assets: must be sorted in ascending order, at index ${index}`);
+        }
+        previous = url;
+    }
+}
 /**
  * Validate a parsed content artifact.
  *
@@ -538,13 +615,11 @@ export function validateArtifact(data, source = 'content artifact') {
     const issues = [];
     if (!isPlainObject(data))
         throw new ContentValidationError(source, ['artifact: must be an object']);
-    for (const field of Object.keys(data)) {
-        if (field !== 'version' && field !== 'entries')
-            issues.push(`${field}: unknown field is not allowed`);
-    }
+    unknownFields(data, ARTIFACT_FIELDS, '', issues);
     if (data['version'] !== SCHEMA_VERSION) {
         issues.push(`version: must be ${SCHEMA_VERSION}, got ${JSON.stringify(data['version'])}`);
     }
+    checkAssets(data['assets'], issues);
     const rawEntries = data['entries'];
     if (!Array.isArray(rawEntries))
         issues.push('entries: must be an array');