@jxsuite/schema 0.28.0 → 0.28.3

package/src/schema.ts

@@ -1,5 +1,5 @@
 /**
- * jx-schema.ts — Jx JSON Schema 2020-12 meta-schema generator
+ * Jx-schema.ts — Jx JSON Schema 2020-12 meta-schema generator
  * @version 2.0.0
  * @license MIT
  *
@@ -28,65 +28,65 @@ import idl from "@webref/idl";
 
 import { tagNameSchema } from "../defs/tag-name.schema";
 import {
-  stringOrRefSchema,
   boolOrRefSchema,
   numberOrRefSchema,
+  stringOrRefSchema,
 } from "../defs/string-or-ref.schema";
 import { headEntrySchema } from "../defs/head-entry.schema";
-import { cemParameterSchema, cemEventSchema } from "../defs/cem.schema";
+import { cemEventSchema, cemParameterSchema } from "../defs/cem.schema";
 import { jsonSchemaTypeSchema } from "../defs/json-schema-type.schema";
 import {
-  internalRefSchema,
-  stateRefSchema,
+  anyRefSchema,
+  externalComponentRefSchema,
   externalRefSchema,
   globalRefSchema,
-  parentRefSchema,
+  internalRefSchema,
   mapRefSchema,
-  anyRefSchema,
+  parentRefSchema,
   refObjectSchema,
-  externalComponentRefSchema,
+  stateRefSchema,
 } from "../defs/ref-object.schema";
 import { styleObjectSchema } from "../defs/style-object.schema";
 import { arrayNamespaceSchema, childrenValueSchema } from "../defs/children-value.schema";
 import {
   attributesObjectSchema,
-  propsObjectSchema,
+  elementDefSchema,
   elementPropertyValueSchema,
+  propsObjectSchema,
   switchDefSchema,
   switchNodeSchema,
-  elementDefSchema,
 } from "../defs/element-def.schema";
 import { typedStateDefSchema } from "../defs/typed-state-def.schema";
 import { functionDefSchema } from "../defs/function-def.schema";
 import { externalClassDefSchema } from "../defs/external-class-def.schema";
 import { pureTypeDefSchema } from "../defs/pure-type-def.schema";
 import {
-  expressionPointerSchema,
+  assignmentOperatorSchema,
+  binaryOperatorSchema,
+  expressionEntrySchema,
   expressionLiteralSchema,
-  expressionOperandSchema,
   expressionNodeSchema,
-  expressionEntrySchema,
-  unaryOperatorSchema,
-  binaryOperatorSchema,
-  assignmentOperatorSchema,
+  expressionOperandSchema,
+  expressionPointerSchema,
+  mapFilterMethodSchema,
   noArgMethodSchema,
   oneArgMethodSchema,
-  spliceMethodSchema,
   reduceMethodSchema,
-  mapFilterMethodSchema,
+  spliceMethodSchema,
+  unaryOperatorSchema,
 } from "../defs/expression-node.schema";
 import {
+  defsMapSchema,
   stateEntrySchema,
   stateMapSchema,
-  defsMapSchema,
   typeDefEntrySchema,
 } from "../defs/state-entry.schema";
 import {
-  classParameterDefSchema,
-  classFieldDefSchema,
   classConstructorDefSchema,
-  classMethodDefSchema,
   classDefSchema,
+  classFieldDefSchema,
+  classMethodDefSchema,
+  classParameterDefSchema,
   formatDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
@@ -106,10 +106,12 @@ async function loadWebData() {
   const tagSet = new Set<string>();
   for (const { elements } of Object.values(elementsData)) {
     for (const el of elements) {
-      if (!el.obsolete) tagSet.add(el.name);
+      if (!el.obsolete) {
+        tagSet.add(el.name);
+      }
     }
   }
-  const tagExamples = [...tagSet].sort();
+  const tagExamples = [...tagSet].toSorted();
 
   const cssSet = new Set<string>();
   for (const prop of cssData.properties) {
@@ -117,13 +119,17 @@ async function loadWebData() {
       cssSet.add(decl);
     }
   }
-  const cssProps = [...cssSet].sort();
+  const cssProps = [...cssSet].toSorted();
 
   const handlerSet = new Set<string>();
   for (const ast of Object.values(idlData)) {
     for (const def of ast) {
-      if (def.type !== "interface" && def.type !== "interface mixin") continue;
-      if (!def.members) continue;
+      if (def.type !== "interface" && def.type !== "interface mixin") {
+        continue;
+      }
+      if (!def.members) {
+        continue;
+      }
       for (const member of def.members) {
         if (
           member.type === "attribute" &&
@@ -136,15 +142,15 @@ async function loadWebData() {
       }
     }
   }
-  const eventHandlers = [...handlerSet].sort();
+  const eventHandlers = [...handlerSet].toSorted();
 
-  return { tagExamples, cssProps, eventHandlers };
+  return { cssProps, eventHandlers, tagExamples };
 }
 
 // ─── Injection helpers ─────────────────────────────────────────────────────────
 
 function buildEventHandlerProperties(eventHandlers: string[]) {
-  const properties: Record<string, any> = {};
+  const properties: Record<string, unknown> = {};
   for (const name of eventHandlers) {
     properties[name] = {
       description: `Event handler for the "${name.slice(2)}" event.`,
@@ -155,7 +161,7 @@ function buildEventHandlerProperties(eventHandlers: string[]) {
 }
 
 function buildCssProperties(cssProps: string[]) {
-  const properties: Record<string, any> = {};
+  const properties: Record<string, unknown> = {};
   for (const name of cssProps) {
     properties[name] = { oneOf: [{ type: "string" }, { type: "number" }] };
   }
@@ -168,132 +174,6 @@ export async function generateSchema() {
   const { tagExamples, cssProps, eventHandlers } = await loadWebData();
 
   return {
-    $schema: "https://json-schema.org/draft/2020-12/schema",
-    $id: "https://jxsuite.com/schema/v1",
-    title: "Jx Document",
-    description:
-      "Schema for Jx component files. " +
-      "A Jx document is a JSON object that declaratively describes a reactive " +
-      "web component: its structure (DOM tree), styling, type definitions ($defs), " +
-      "runtime state, and inline or external functions. Reactivity is powered by @vue/reactivity.",
-    type: "object",
-
-    properties: {
-      $schema: {
-        description: "URI identifying the Jx dialect version. Enables schema-aware IDE tooling.",
-        type: "string",
-        examples: ["https://jxsuite.com/schema/v1"],
-      },
-      $id: {
-        description: "Component identifier string. Used by tooling and the builder.",
-        type: "string",
-        examples: ["Counter", "TodoApp", "UserCard"],
-      },
-      $defs: {
-        description:
-          "Pure JSON Schema type definitions for this component. " +
-          "All entries are reusable type schemas — no runtime artifacts are produced. " +
-          "Referenced from state entries via $ref. Naming convention: PascalCase.",
-        $ref: "#/$defs/DefsMap",
-      },
-      state: {
-        description:
-          "Runtime variables for this component. All entries are reactive by default. " +
-          "Entry shape is determined by value type: " +
-          "scalar/array → reactive property, string with ${} → computed, " +
-          "object with $prototype → function or data source, " +
-          "object with type and default → typed reactive property.",
-        $ref: "#/$defs/StateMap",
-      },
-      $media: {
-        description:
-          "Named media breakpoints following CSS @custom-media convention. " +
-          "Keys use the CSS custom property -- prefix.",
-        type: "object",
-        additionalProperties: { type: "string" },
-        examples: [
-          {
-            "--sm": "(min-width: 640px)",
-            "--md": "(min-width: 768px)",
-            "--dark": "(prefers-color-scheme: dark)",
-          },
-        ],
-      },
-      $elements: {
-        description:
-          "Custom element dependencies. Items are either $ref objects pointing to JX " +
-          "element definitions, or bare npm package name strings for web component libraries.",
-        type: "array",
-        items: {
-          oneOf: [
-            {
-              type: "object",
-              required: ["$ref"],
-              properties: { $ref: { type: "string" } },
-              additionalProperties: false,
-            },
-            {
-              type: "string",
-              description: "npm package specifier (must declare customElements in package.json)",
-            },
-          ],
-        },
-      },
-      $head: {
-        description:
-          "Page-level <head> entries. Array of element definitions for meta tags, " +
-          "link tags, script tags, etc. Merged with layout and site-level $head entries.",
-        type: "array",
-        items: { $ref: "#/$defs/ElementDef" },
-      },
-      $layout: {
-        description:
-          "Layout reference for pages. String path to a layout JSON file, " +
-          "or false to opt out of the default layout.",
-        oneOf: [{ type: "string" }, { type: "boolean", const: false }],
-        examples: ["./layouts/base.json"],
-      },
-      $paths: {
-        description:
-          "Dynamic route parameters. Maps parameter names to data sources " +
-          "for generating one page per entry at build time.",
-        type: "object",
-      },
-      title: {
-        description:
-          "Page title. Can be a static string or a template string with ${} expressions.",
-        $ref: "#/$defs/StringOrRef",
-      },
-      imports: {
-        description:
-          "Import map: $prototype names to .class.json file paths. " +
-          "Allows state entries to reference external classes by name without $src.",
-        type: "object",
-        additionalProperties: { type: "string" },
-      },
-      observedAttributes: {
-        description:
-          "HTML attributes the custom element watches for changes. " +
-          "Follows the Web Components observedAttributes convention.",
-        type: "array",
-        items: { type: "string" },
-      },
-      cases: {
-        description:
-          "Switch cases object. Maps case values to element definitions or external " +
-          "component refs. Used alongside $switch for dynamic component rendering.",
-        type: "object",
-        additionalProperties: {
-          oneOf: [{ $ref: "#/$defs/ElementDef" }, { $ref: "#/$defs/ExternalComponentRef" }],
-        },
-      },
-      tagName: { $ref: "#/$defs/TagName" },
-      children: { $ref: "#/$defs/ChildrenValue" },
-      style: { $ref: "#/$defs/StyleObject" },
-      attributes: { $ref: "#/$defs/AttributesObject" },
-    },
-    additionalProperties: { $ref: "#/$defs/ElementPropertyValue" },
-
     $defs: {
       DefsMap: defsMapSchema,
       TypeDefEntry: typeDefEntrySchema,
@@ -366,6 +246,130 @@ export async function generateSchema() {
       ImageConfig: imageConfigSchema,
       ContentTypeDef: contentTypeDefSchema,
     },
+    $id: "https://jxsuite.com/schema/v1",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: { $ref: "#/$defs/ElementPropertyValue" },
+    description:
+      "Schema for Jx component files. " +
+      "A Jx document is a JSON object that declaratively describes a reactive " +
+      "web component: its structure (DOM tree), styling, type definitions ($defs), " +
+      "runtime state, and inline or external functions. Reactivity is powered by @vue/reactivity.",
+    properties: {
+      $defs: {
+        $ref: "#/$defs/DefsMap",
+        description:
+          "Pure JSON Schema type definitions for this component. " +
+          "All entries are reusable type schemas — no runtime artifacts are produced. " +
+          "Referenced from state entries via $ref. Naming convention: PascalCase.",
+      },
+      $elements: {
+        description:
+          "Custom element dependencies. Items are either $ref objects pointing to JX " +
+          "element definitions, or bare npm package name strings for web component libraries.",
+        items: {
+          oneOf: [
+            {
+              additionalProperties: false,
+              properties: { $ref: { type: "string" } },
+              required: ["$ref"],
+              type: "object",
+            },
+            {
+              description: "npm package specifier (must declare customElements in package.json)",
+              type: "string",
+            },
+          ],
+        },
+        type: "array",
+      },
+      $head: {
+        description:
+          "Page-level <head> entries. Array of element definitions for meta tags, " +
+          "link tags, script tags, etc. Merged with layout and site-level $head entries.",
+        items: { $ref: "#/$defs/ElementDef" },
+        type: "array",
+      },
+      $id: {
+        description: "Component identifier string. Used by tooling and the builder.",
+        examples: ["Counter", "TodoApp", "UserCard"],
+        type: "string",
+      },
+      $layout: {
+        description:
+          "Layout reference for pages. String path to a layout JSON file, " +
+          "or false to opt out of the default layout.",
+        examples: ["./layouts/base.json"],
+        oneOf: [{ type: "string" }, { const: false, type: "boolean" }],
+      },
+      $media: {
+        additionalProperties: { type: "string" },
+        description:
+          "Named media breakpoints following CSS @custom-media convention. " +
+          "Keys use the CSS custom property -- prefix.",
+        examples: [
+          {
+            "--dark": "(prefers-color-scheme: dark)",
+            "--md": "(min-width: 768px)",
+            "--sm": "(min-width: 640px)",
+          },
+        ],
+        type: "object",
+      },
+      $paths: {
+        description:
+          "Dynamic route parameters. Maps parameter names to data sources " +
+          "for generating one page per entry at build time.",
+        type: "object",
+      },
+      $schema: {
+        description: "URI identifying the Jx dialect version. Enables schema-aware IDE tooling.",
+        examples: ["https://jxsuite.com/schema/v1"],
+        type: "string",
+      },
+      attributes: { $ref: "#/$defs/AttributesObject" },
+      cases: {
+        additionalProperties: {
+          oneOf: [{ $ref: "#/$defs/ElementDef" }, { $ref: "#/$defs/ExternalComponentRef" }],
+        },
+        description:
+          "Switch cases object. Maps case values to element definitions or external " +
+          "component refs. Used alongside $switch for dynamic component rendering.",
+        type: "object",
+      },
+      children: { $ref: "#/$defs/ChildrenValue" },
+      imports: {
+        additionalProperties: { type: "string" },
+        description:
+          "Import map: $prototype names to .class.json file paths. " +
+          "Allows state entries to reference external classes by name without $src.",
+        type: "object",
+      },
+      observedAttributes: {
+        description:
+          "HTML attributes the custom element watches for changes. " +
+          "Follows the Web Components observedAttributes convention.",
+        items: { type: "string" },
+        type: "array",
+      },
+      state: {
+        $ref: "#/$defs/StateMap",
+        description:
+          "Runtime variables for this component. All entries are reactive by default. " +
+          "Entry shape is determined by value type: " +
+          "scalar/array → reactive property, string with ${} → computed, " +
+          "object with $prototype → function or data source, " +
+          "object with type and default → typed reactive property.",
+      },
+      style: { $ref: "#/$defs/StyleObject" },
+      tagName: { $ref: "#/$defs/TagName" },
+      title: {
+        $ref: "#/$defs/StringOrRef",
+        description:
+          "Page title. Can be a static string or a template string with ${} expressions.",
+      },
+    },
+    title: "Jx Document",
+    type: "object",
   };
 }
 
@@ -373,21 +377,21 @@ export async function generateSchema() {
 
 export function generateProjectSchema() {
   return {
-    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $defs: {
+      ContentTypeDef: contentTypeDefSchema,
+      ImageConfig: imageConfigSchema,
+    },
     $id: "https://jxsuite.com/schema/project/v1",
-    title: "Jx Project",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: false,
     description:
       "Schema for Jx project.json files. " +
       "A project.json file is the root anchor file for a Jx project, " +
       "declaring site metadata, default settings, global styles, content types, " +
       "and build configuration.",
-    type: "object",
     properties: projectConfigSchema.properties,
-    additionalProperties: false,
-    $defs: {
-      ImageConfig: imageConfigSchema,
-      ContentTypeDef: contentTypeDefSchema,
-    },
+    title: "Jx Project",
+    type: "object",
   };
 }
 
@@ -395,85 +399,85 @@ export function generateProjectSchema() {
 
 export function generateClassSchema() {
   return {
-    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $defs: {
+      ClassConstructorDef: classConstructorDefSchema,
+      ClassFieldDef: classFieldDefSchema,
+      ClassMethodDef: classMethodDefSchema,
+      ClassParameterDef: classParameterDefSchema,
+      FormatDef: formatDefSchema,
+      StudioHints: studioHintsSchema,
+    },
     $id: "https://jxsuite.com/schema/class/v1",
-    title: "Jx Class Definition",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    additionalProperties: false,
     description:
       "Schema for Jx .class.json files. A class definition describes a schema-defined " +
       "class with fields, constructor, methods, and type parameters. Optionally points " +
       "to a JS module via $implementation for hybrid execution.",
-    type: "object",
-    required: ["$prototype", "title"],
     properties: {
-      $schema: { type: "string" },
+      $defs: {
+        description: "Class members: parameters, returnTypes, fields, constructor, methods.",
+        properties: {
+          constructor: { $ref: "#/$defs/ClassConstructorDef" },
+          fields: {
+            additionalProperties: { $ref: "#/$defs/ClassFieldDef" },
+            description: "Class fields with role, access, scope, and type information.",
+            type: "object",
+          },
+          methods: {
+            additionalProperties: { $ref: "#/$defs/ClassMethodDef" },
+            description: "Class methods and accessors.",
+            type: "object",
+          },
+          parameters: {
+            additionalProperties: { $ref: "#/$defs/ClassParameterDef" },
+            description: "Reusable typed parameter schemas, keyed by name.",
+            type: "object",
+          },
+          returnTypes: {
+            additionalProperties: { type: "object" },
+            description: "Output type schemas, keyed by name.",
+            type: "object",
+          },
+        },
+        type: "object",
+      },
       $id: { type: "string" },
-      $prototype: {
-        description: 'Must be "Class" for class definition files.',
+      $implementation: {
+        description: "Relative path to a JS module containing the actual class implementation.",
+        examples: ["./md.js", "./lib/calculator.js"],
         type: "string",
-        const: "Class",
       },
-      title: {
-        description: "PascalCase class name, used as the export name.",
+      $prototype: {
+        const: "Class",
+        description: 'Must be "Class" for class definition files.',
         type: "string",
-        examples: ["MarkdownFile", "DataSource", "Calculator"],
       },
+      $schema: { type: "string" },
+      $studio: { $ref: "#/$defs/StudioHints" },
       description: { type: "string" },
       extends: {
         description: "Base class — string name or $ref to another .class.json.",
         oneOf: [
           { type: "string" },
           {
-            type: "object",
-            required: ["$ref"],
-            properties: { $ref: { type: "string" } },
             additionalProperties: false,
+            properties: { $ref: { type: "string" } },
+            required: ["$ref"],
+            type: "object",
           },
         ],
       },
-      $implementation: {
-        description: "Relative path to a JS module containing the actual class implementation.",
-        type: "string",
-        examples: ["./md.js", "./lib/calculator.js"],
-      },
       format: { $ref: "#/$defs/FormatDef" },
-      $studio: { $ref: "#/$defs/StudioHints" },
-      $defs: {
-        description: "Class members: parameters, returnTypes, fields, constructor, methods.",
-        type: "object",
-        properties: {
-          parameters: {
-            description: "Reusable typed parameter schemas, keyed by name.",
-            type: "object",
-            additionalProperties: { $ref: "#/$defs/ClassParameterDef" },
-          },
-          returnTypes: {
-            description: "Output type schemas, keyed by name.",
-            type: "object",
-            additionalProperties: { type: "object" },
-          },
-          fields: {
-            description: "Class fields with role, access, scope, and type information.",
-            type: "object",
-            additionalProperties: { $ref: "#/$defs/ClassFieldDef" },
-          },
-          constructor: { $ref: "#/$defs/ClassConstructorDef" },
-          methods: {
-            description: "Class methods and accessors.",
-            type: "object",
-            additionalProperties: { $ref: "#/$defs/ClassMethodDef" },
-          },
-        },
+      title: {
+        description: "PascalCase class name, used as the export name.",
+        examples: ["MarkdownFile", "DataSource", "Calculator"],
+        type: "string",
       },
     },
-    additionalProperties: false,
-    $defs: {
-      ClassParameterDef: classParameterDefSchema,
-      ClassFieldDef: classFieldDefSchema,
-      ClassConstructorDef: classConstructorDefSchema,
-      ClassMethodDef: classMethodDefSchema,
-      FormatDef: formatDefSchema,
-      StudioHints: studioHintsSchema,
-    },
+    required: ["$prototype", "title"],
+    title: "Jx Class Definition",
+    type: "object",
   };
 }
 
@@ -486,22 +490,22 @@ export async function generateSchemaString() {
 export async function validateDocument(doc: Record<string, unknown>) {
   let Ajv, addFormats;
   try {
-    // @ts-ignore — optional peer dependency
+    // @ts-expect-error — optional peer dependency
     ({ default: Ajv } = await import("ajv"));
-    // @ts-ignore — optional peer dependency
+    // @ts-expect-error — optional peer dependency
     ({ default: addFormats } = await import("ajv-formats"));
   } catch {
     throw new Error("Schema validation requires ajv and ajv-formats: bun add ajv ajv-formats");
   }
 
-  const ajv = new Ajv({ allErrors: true, strict: false, ownProperties: true });
+  const ajv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
   addFormats(ajv);
 
   const schema = await generateSchema();
   const validate = ajv.compile(schema);
   const valid = validate(doc);
 
-  return { valid, errors: validate.errors ?? null };
+  return { errors: validate.errors ?? null, valid };
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────
@@ -520,7 +524,7 @@ if (process.argv[1] && process.argv[1].endsWith("schema.ts")) {
   const projectStr = JSON.stringify(projectSchema, null, 2);
   const classStr = JSON.stringify(classSchema, null, 2);
 
-  const [, , out] = process.argv;
+  const [out] = process.argv.slice(2);
 
   if (out) {
     writeFileSync(out, componentStr, "utf8");