@jxsuite/schema 1.5.0 → 1.8.0

package/src/parse.ts

@@ -4,10 +4,20 @@
  * Raw `JSON.parse()` returns `any`, which silently disables checking for everything downstream.
  * These helpers are the single sanctioned crossing point: they parse, structurally verify, and
  * return the domain type — failures carry the source path.
+ *
+ * Being the single crossing point is also what makes it the right place to enforce I-JSON (RFC
+ * 7493). `JSON.parse` accepts documents that mean something other than what they say — a repeated
+ * key whose first value it discards, an integer it rounds — and a Jx document does not stay JSON:
+ * it round-trips through markdown frontmatter and a CRDT, each rebuilding the object from the
+ * parsed value. Whatever was dropped here is dropped for good.
+ *
+ * It is also where identifiers are normalized (UAX #31 §R4), for the same reason: a name that means
+ * one thing on one keyboard and another thing on another is a defect nothing downstream can see.
  */
 
 import type { JxClassDef, JxDocument, ProjectConfig } from "../types";
 import { isJsonObject } from "./guards";
+import { describeIJsonProblem, findIJsonProblems } from "./ijson";
 
 // ─── Error helpers ──────────────────────────────────────────────────────────────
 
@@ -21,6 +31,63 @@ export function toError(e: unknown): Error {
   return e instanceof Error ? e : new Error(String(e));
 }
 
+// ─── Unicode normalization ──────────────────────────────────────────────────────
+
+/**
+ * Text outside ASCII, which is the only text whose normalization form can differ. Testing for it
+ * first keeps this walk close to free on the pure-ASCII documents that are almost all of them.
+ */
+const NON_ASCII = /[^\p{ASCII}]/u;
+
+/**
+ * Recursively put every key and every string value into Normalization Form C.
+ *
+ * **The defect this fixes.** A state name is an identifier: `"état"` declared in `state`,
+ * referenced as `${state.état}` in a template and as `#/state/état` in a `$ref`. Typed on macOS it
+ * arrives decomposed (`e` + U+0301); typed on Windows or pasted from most of the web it arrives
+ * precomposed (U+00E9). Those are two different JavaScript property names, so a document whose
+ * declaration and reference were typed on different machines builds cleanly, emits a valid bundle,
+ * and renders nothing — `state.état` is simply `undefined`. There is no error to see and no symptom
+ * to search for. UAX #31 §R4 exists for exactly this, and NFC is the form the web platform assumes
+ * everywhere else.
+ *
+ * **Why values are normalized too, and why that is not a content change.** Two canonically
+ * equivalent strings are, by the definition in UAX #15, the same text: a conforming renderer must
+ * display them identically, and no process may distinguish them. So normalizing a `textContent` is
+ * a no-op for meaning. It is also unavoidable, because Jx has no syntactic boundary between content
+ * and code — `"Café ${state.été}"` is one string carrying both, and normalizing only "identifier
+ * positions" would mean parsing every template to find them.
+ *
+ * **Why here and not on the source text.** `"état"` is pure ASCII until `JSON.parse` turns the
+ * escape into a combining mark, so normalizing the raw text would miss exactly the documents a
+ * generator wrote.
+ *
+ * @param {unknown} value - Any parsed JSON value
+ * @returns {unknown} The same shape, with all text in NFC
+ */
+function normalizeIdentifiers(value: unknown): unknown {
+  if (typeof value === "string") {
+    return NON_ASCII.test(value) ? value.normalize("NFC") : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => normalizeIdentifiers(item));
+  }
+  if (isJsonObject(value)) {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+      /*
+       * A later key wins on collision, matching what `JSON.parse` does with a literal duplicate.
+       * It cannot happen through this boundary — I-JSON already rejected duplicate keys, and two
+       * keys differing only by normalization form are not duplicates to `JSON.parse` — so this is
+       * a statement about which is authoritative rather than a branch anything reaches.
+       */
+      out[NON_ASCII.test(key) ? key.normalize("NFC") : key] = normalizeIdentifiers(entry);
+    }
+    return out;
+  }
+  return value;
+}
+
 // ─── Parse helpers ──────────────────────────────────────────────────────────────
 
 function parseObject(text: string, sourcePath: string, what: string): Record<string, unknown> {
@@ -35,7 +102,17 @@ function parseObject(text: string, sourcePath: string, what: string): Record<str
   if (!isJsonObject(parsed)) {
     throw new Error(`Invalid ${what} at ${sourcePath}: expected a JSON object`);
   }
-  return parsed;
+  /*
+   * An error rather than a warning, because both problems are silent data loss and neither has a
+   * reading under which the author got what they wrote. The whole repository — 375 documents —
+   * was already clean when this landed, so this rejects mistakes rather than existing work.
+   */
+  const problems = findIJsonProblems(text);
+  if (problems.length > 0) {
+    const described = problems.map((problem) => describeIJsonProblem(problem)).join("; ");
+    throw new Error(`Invalid ${what} at ${sourcePath}: ${described}`);
+  }
+  return normalizeIdentifiers(parsed) as Record<string, unknown>;
 }
 
 /** Parse a Jx document (.json page/layout/component source). */

package/src/schema.ts

@@ -26,6 +26,7 @@ import { listAll as listElements } from "@webref/elements";
 import css from "@webref/css";
 import idl from "@webref/idl";
 
+import { elementTagNameSchema, tagExpressionSchema } from "../defs/tag-expression.schema";
 import { tagNameSchema } from "../defs/tag-name.schema";
 import {
   boolOrRefSchema,
@@ -287,6 +288,8 @@ export async function generateSchema() {
         ...tagNameSchema,
         examples: [...tagExamples, "my-counter", "todo-app", "user-card"],
       },
+      TagExpression: tagExpressionSchema,
+      ElementTagName: elementTagNameSchema,
       JsonSchemaType: jsonSchemaTypeSchema,
       HeadEntry: headEntrySchema,
       ImageConfig: imageConfigSchema,
@@ -342,9 +345,16 @@ export async function generateSchema() {
       },
       $head: {
         description:
-          "Page-level <head> entries. Array of element definitions for meta tags, " +
+          "Page-level <head> entries. Array of head entries for meta tags, " +
           "link tags, script tags, etc. Merged with layout and site-level $head entries.",
-        items: { $ref: "#/$defs/ElementDef" },
+        /* `HeadEntry`, NOT `ElementDef`. These were typed as elements, which was harmless only
+           while an element's tagName was a plain name — the moment it could be chosen at creation,
+           a head tag could be too, and `head-merger.ts` splices one straight into the built page as
+           `<${tag} …>`. A head tag is static by nature (the runtime's `injectHead` builds a CSS
+           selector out of it before it ever creates anything), and `HeadEntry` already says so.
+           It had been an orphan def until now: its only inbound `$ref` was its own recursive
+           `children`. */
+        items: { $ref: "#/$defs/HeadEntry" },
         type: "array",
       },
       $id: {
@@ -352,6 +362,30 @@ export async function generateSchema() {
         examples: ["Counter", "TodoApp", "UserCard"],
         type: "string",
       },
+      $dir: {
+        description:
+          "Base direction for this page's <html> element, overriding `defaults.dir`. " +
+          "Right-to-left content renders left-to-right without it.",
+        enum: ["ltr", "rtl", "auto"],
+        type: "string",
+      },
+      $lang: {
+        description:
+          "Language tag for this page's <html> element, overriding `defaults.lang` " +
+          "(site-architecture.md §8.4).",
+        examples: ["en", "fr", "ar-EG"],
+        type: "string",
+      },
+      $translationKey: {
+        description:
+          "This page's identity across languages, overriding the one its path implies " +
+          "(site-architecture.md §13.5). Two routes are translations when their keys match; " +
+          "the default key is the path with the locale prefix removed, which is right whenever " +
+          "the paths are parallel and wrong for a localized slug — /fr-ca/a-propos/ shares " +
+          "nothing with /about/ until one of them says so.",
+        examples: ["about", "blog/hello-world"],
+        type: "string",
+      },
       $layout: {
         description:
           "Layout reference for pages. String path to a layout JSON file, " +
@@ -359,6 +393,24 @@ export async function generateSchema() {
         examples: ["./layouts/base.json"],
         oneOf: [{ type: "string" }, { const: false, type: "boolean" }],
       },
+      $shadow: {
+        description:
+          "Render this component into a shadow root instead of the light DOM (spec.md §16.6). " +
+          "Off unless set: a shadow root isolates the component's styles from the page and " +
+          "replaces the <slot> emulation with real slot distribution, so it changes how the " +
+          "component composes. Overrides `defaults.shadow` in both directions — `false` opts " +
+          "one component out of a project that opted in.",
+        oneOf: [
+          { enum: ["open", "closed"], type: "string" },
+          { const: false, type: "boolean" },
+        ],
+      },
+      $sitemap: {
+        description:
+          "Set false to exclude this page from sitemap.xml (site-architecture.md §8.4.1). " +
+          "Every other page with a URL is included.",
+        type: "boolean",
+      },
       $media: {
         additionalProperties: { type: "string" },
         description:
@@ -668,7 +720,8 @@ export async function validateWithSchema(
   doc: Record<string, unknown>,
   schema: Record<string, unknown>,
 ) {
-  let Ajv: AjvCtor, addFormats: AddFormatsFn;
+  let Ajv: AjvCtor;
+  let addFormats: AddFormatsFn;
   try {
     // The generated schema is JSON Schema 2020-12, so use the matching Ajv build
     // (the default `ajv` export is draft-07 and can't compile a 2020-12 schema).

package/types.ts

@@ -200,7 +200,11 @@ export interface JxServerFnDef {
 export interface JxHeadEntry {
   tagName: string;
   attributes?: Record<string, string | boolean>;
-  textContent?: string;
+  /**
+   * Element content. An **object** is a structured data block — the compiler serializes it to JSON
+   * inside the tag, which is how JSON-LD is authored (site-architecture.md §8.5).
+   */
+  textContent?: string | Record<string, unknown>;
   children?: (JxHeadEntry | string)[];
   [key: string]: unknown;
 }
@@ -212,6 +216,8 @@ export interface ImageConfig {
   quality?: { webp?: number; avif?: number; jpeg?: number; png?: number };
   sizes?: string;
   lazyLoad?: boolean;
+  /** Wrap a multi-format image in a `<picture>` with one `<source>` per format. Default true. */
+  picture?: boolean;
   service?: "build" | "cloudflare";
   remoteDomains?: string[];
 }
@@ -240,8 +246,26 @@ export interface JxStyle {
   [property: string]: string | number | JxStyle | undefined;
 }
 
+/**
+ * A tag chosen when the element is created, from a set the schema enumerates.
+ *
+ * Both branches resolve to a `TagName`, so the candidates are readable without evaluating anything
+ * — which is what lets the compiler emit one template per candidate and `jx validate` refuse an
+ * illegal name at authoring time. See `defs/tag-expression.schema.ts` for why this is not a `${…}`
+ * template and not a third `$switch` spelling.
+ */
+export type JxTagExpression =
+  | { operator: "?:"; target: unknown; value: string; initial: string }
+  | { operator: "switch"; target: unknown; cases: Record<string, string>; default: string };
+
+/**
+ * An ELEMENT's tag. The document root's and a head entry's stay `string` — see
+ * `defs/tag-expression.schema.ts`.
+ */
+export type JxElementTagName = string | { $expression: JxTagExpression };
+
 export interface JxElement {
-  tagName?: string;
+  tagName?: JxElementTagName;
   textContent?: string | null | JxRef;
   innerHTML?: string;
   /**
@@ -285,8 +309,19 @@ export interface JxMappedArray {
 }
 
 export interface JxDocument extends JxElement {
+  /**
+   * The custom element's NAME, always a literal.
+   *
+   * Narrowed from {@link JxElement.tagName} deliberately: this string becomes
+   * `customElements.define(…)`, the emitted module's file name and a CSS selector prefix, none of
+   * which can be chosen per instance. Carrying the rule in the type means `defineElement` and the
+   * compiler keep receiving a string without a positional guard anyone can forget to write.
+   */
+  tagName?: string;
   state?: Record<string, JxStateDefinition>;
   $layout?: string | false;
+  /** This page's identity across languages, overriding the one its path implies (§13.5). */
+  $translationKey?: string;
   $paths?: JxPathsDef;
   $elements?: (JxElement | string)[];
   $head?: JxHeadEntry[];
@@ -483,6 +518,114 @@ export type AdapterId = "static" | "cloudflare-pages" | "cloudflare-workers" | "
  * Identifiers only — no secrets — so it travels with the repo and any Studio (local or cloud) can
  * tell whether publishing is set up.
  */
+/** `dist/_headers` output — the response headers only the build can know (RFC 9111, RFC 8246). */
+/**
+ * CSP Level 3, as far as a static build can go.
+ *
+ * Off by default. Every other security header the build emits is safe to turn on for a site that
+ * has never seen one; a policy is the one that can leave a page blank, because it governs code the
+ * build cannot see — a third-party script that loads a second script, a widget that opens a frame.
+ * Turning it on is one line and one look at the browser console.
+ */
+export interface CspConfig {
+  /** `"report-only"` sends `Content-Security-Policy-Report-Only`. Default `"enforce"`. */
+  mode?: "enforce" | "report-only";
+  /**
+   * Replace or remove a computed directive. `false` removes it; a string replaces it wholesale, so
+   * an addition means restating the default's sources alongside the new one.
+   */
+  directives?: Record<string, string | false>;
+  /** Where violation reports go. Emits `report-to`, `report-uri` and `Reporting-Endpoints`. */
+  reportUri?: string;
+}
+
+/**
+ * W3C Web App Manifest. Off unless declared — a manifest is a claim that a site is meant to be
+ * installed, and most are not.
+ */
+export interface ManifestConfig {
+  enabled?: boolean;
+  /** Defaults to the project `name`. */
+  name?: string;
+  shortName?: string;
+  description?: string;
+  /** Defaults to `/`. */
+  startUrl?: string;
+  scope?: string;
+  display?: "fullscreen" | "standalone" | "minimal-ui" | "browser";
+  orientation?: string;
+  themeColor?: string;
+  backgroundColor?: string;
+  lang?: string;
+  dir?: "ltr" | "rtl" | "auto";
+  categories?: string[];
+  icons?: { src: string; sizes?: string; type?: string; purpose?: string }[];
+}
+
+/**
+ * W3C Service Worker. **Off unless declared, and turning it off means `false`, not deleting the
+ * key** — a worker is sticky, so a site that once had one must keep serving something at that URL
+ * to tell previous visitors to stop.
+ */
+export interface ServiceWorkerConfig {
+  enabled?: boolean;
+  /** Registration scope. Cannot exceed the worker's own path. Default `"/"`. */
+  scope?: string;
+  /** URLs fetched and cached at install time. */
+  precache?: string[];
+  /** Page served for a failed navigation. Added to `precache` if it is not already there. */
+  offlineFallback?: string;
+}
+
+/**
+ * RFC 9116 `security.txt`. `expires` is required by §2.5.5 and an absent or past one is a build
+ * error: an expired file advertises a reporting channel while telling the reporter not to trust
+ * it.
+ */
+export interface SecurityTxtConfig {
+  enabled?: boolean;
+  /** At least one is required (§2.5.3): a `mailto:`, `https:` or `tel:` URI. */
+  contact?: string[];
+  /** RFC 3339 date-time; §2.5.5. */
+  expires?: string;
+  encryption?: string[];
+  acknowledgments?: string[];
+  /** BCP 47 tags, validated and canonicalized like `i18n.locales`. */
+  preferredLanguages?: string[];
+  canonical?: string;
+  policy?: string[];
+  hiring?: string[];
+}
+
+export interface HeadersConfig {
+  /** Emit the file at all. Default true. */
+  enabled?: boolean;
+  /**
+   * `"auto"` marks the content-addressed image variants immutable and revalidates everything else.
+   * `"off"` emits no `Cache-Control` at all, for a host that manages caching itself.
+   */
+  cache?: "auto" | "off";
+  security?: {
+    /** `X-Content-Type-Options: nosniff`. Default true. */
+    contentTypeOptions?: boolean;
+    /** `X-Frame-Options`, or false to omit. Default `"SAMEORIGIN"`. */
+    frameOptions?: "DENY" | "SAMEORIGIN" | false;
+    /** `Referrer-Policy`, or false to omit. Default `"strict-origin-when-cross-origin"`. */
+    referrerPolicy?: string | false;
+    /** `Permissions-Policy`, or false to omit. */
+    permissionsPolicy?: string | false;
+    /**
+     * RFC 6797. **Off by default**: a wrong `max-age` locks an apex domain to HTTPS for that long,
+     * and the mistake is not visible until a certificate lapses.
+     */
+    hsts?: boolean | { maxAge?: number; includeSubDomains?: boolean; preload?: boolean };
+    /** CSP Level 3. Off by default — see {@link CspConfig}. */
+    csp?: boolean | "report-only" | CspConfig;
+  };
+  /** Verbatim rules, merged after the generated block. Keys are path patterns. */
+  rules?: Record<string, Record<string, string>>;
+}
+
 export interface DeployConfig {
   provider: "cloudflare-pages";
   accountId: string;
@@ -504,6 +647,7 @@ export interface ProjectConfig {
     adapter?: AdapterId | (string & Record<never, never>);
     deploy?: DeployConfig;
     sitemap?: boolean;
+    headers?: HeadersConfig;
     [key: string]: unknown;
   };
   images?: ImageConfig;
@@ -515,11 +659,39 @@ export interface ProjectConfig {
    */
   extensions?: string[];
   /** Redirect map: source path → destination (or destination with HTTP status). */
-  redirects?: Record<string, string | { destination: string; status?: number }>;
+  redirects?: Record<
+    string,
+    string | { destination: string; status?: number } | { destination: string; rewrite: true }
+  >;
+  /** W3C Web App Manifest, emitted as `manifest.webmanifest`. */
+  manifest?: ManifestConfig;
+  /** RFC 9116, emitted as `.well-known/security.txt`. */
+  securityTxt?: SecurityTxtConfig;
+  /**
+   * W3C Service Worker, emitted as `sw.js`. Off unless declared; `false` emits a tombstone that
+   * unregisters a previously deployed worker (site-architecture.md §14.6).
+   */
+  serviceWorker?: ServiceWorkerConfig | boolean;
+  /**
+   * Locale routing. Tags are BCP 47; a malformed one is a build error, since a locale is a URL
+   * prefix, an `hreflang` value and an `<html lang>` at once.
+   */
+  i18n?: {
+    defaultLocale?: string;
+    locales?: string[];
+    routing?: "prefix-except-default" | "prefix-always";
+  };
   defaults?: {
     /** Default layout path; `null` means explicitly no layout. */
     layout?: string | null;
     lang?: string;
+    /** Base direction for `<html dir>`. A page's `$dir` overrides it. */
+    dir?: "ltr" | "rtl" | "auto";
+    /**
+     * Default shadow-DOM mode for components. `false` (light DOM) unless set; a component's own
+     * `$shadow` overrides it in both directions.
+     */
+    shadow?: "open" | "closed" | false;
     charset?: string;
     [key: string]: unknown;
   };
@@ -550,7 +722,7 @@ export type JxPathsDef =
  * `@jxsuite/schema/guards` before use.
  */
 export interface JxMutableNode {
-  tagName?: string;
+  tagName?: JxElementTagName;
   textContent?: string | null | JxRef;
   innerHTML?: string;
   /**
@@ -639,5 +811,20 @@ export interface ContentLoaderEntry {
     toc?: TocEntry[];
     readingTime?: number;
     wordCount?: number;
+    /**
+     * The source file's modification time, RFC 3339. The fallback a feed uses when an entry carries
+     * no authored date, and what lets the sitemap give a generated page its own `<lastmod>` rather
+     * than its template's.
+     */
+    mtime?: string;
+    /** Authored text of a field the date-coercion pass rewrote, keyed by field name. */
+    rawDates?: Record<string, unknown>;
+    /**
+     * The locale this entry was loaded for, set only when its content type's `source` carried a
+     * `{locale}` placeholder. It is what lets a `[slug]` route under `/fr/` expand the French
+     * entries and not the English ones — without it, two translations of one post share an id and
+     * the second silently overwrites the first's route.
+     */
+    locale?: string;
   };
 }