@jxsuite/schema 0.34.0 → 1.0.0

package/src/schema.ts

@@ -90,7 +90,13 @@ import {
   formatDefSchema,
   studioHintsSchema,
 } from "../defs/class-def.schema";
-import { contentTypeDefSchema } from "../defs/content-type-def.schema";
+import { extensionManifestSchema } from "../defs/extension-manifest.schema";
+import {
+  DOCUMENT_PATHS_SCHEMA_ID,
+  PROJECT_FIELDS_SCHEMA_ID,
+  jxFieldSchemaDef,
+  relationshipRefSchema,
+} from "../defs/field-schema.schema";
 import { imageConfigSchema } from "../defs/image-config.schema";
 import { projectConfigSchema } from "../defs/project-config.schema";
 
@@ -261,7 +267,6 @@ export async function generateSchema() {
       JsonSchemaType: jsonSchemaTypeSchema,
       HeadEntry: headEntrySchema,
       ImageConfig: imageConfigSchema,
-      ContentTypeDef: contentTypeDefSchema,
     },
     $id: "https://jxsuite.com/schema/v1",
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -395,23 +400,97 @@ export async function generateSchema() {
 export function generateProjectSchema() {
   return {
     $defs: {
-      ContentTypeDef: contentTypeDefSchema,
       ImageConfig: imageConfigSchema,
     },
     $id: "https://jxsuite.com/schema/project/v1",
     $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.",
+      "declaring site metadata, default settings, global styles, extensions, " +
+      "and build configuration. Open by design: extension-contributed sections " +
+      "are opaque top-level keys; the generated per-project entry document " +
+      "(project.schema.json) closes the composition.",
     properties: projectConfigSchema.properties,
     title: "Jx Project",
     type: "object",
   };
 }
 
+// ─── Project Core Fragment Generator ─────────────────────────────────────────
+
+/**
+ * The core fragment of the composed per-project schema (specs/extensions.md §5.1): core
+ * project.json properties only — no extension sections — and deliberately open, because closure
+ * (`unevaluatedProperties: false`) happens in the generated entry document. Publishes the
+ * `JxFieldSchema` and `RelationshipRef` defs the entry document unions into the `jxFieldSchema`
+ * dynamic anchor.
+ */
+export function generateProjectCoreSchema() {
+  return {
+    $defs: {
+      ImageConfig: imageConfigSchema,
+      JxFieldSchema: jxFieldSchemaDef,
+      RelationshipRef: relationshipRefSchema,
+    },
+    $id: "https://jxsuite.com/schema/project/core/v2",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    description:
+      "Core fragment of the Jx project.json schema. Open by design: extension fragments " +
+      "contribute their own top-level sections and the generated per-project entry document " +
+      "(project.schema.json) closes the composition. See specs/extensions.md §5.",
+    properties: projectConfigSchema.properties,
+    title: "Jx Project Core",
+    type: "object",
+  };
+}
+
+// ─── Union Resource Generators ───────────────────────────────────────────────
+
+/**
+ * The shipped DEFAULT field-union resource. The generated per-project entry document re-embeds a
+ * resource under the same $id with the effective union (adding extension extras); by standard
+ * compound-document $id resolution the embed shadows this default wherever both are in play.
+ */
+export function generateProjectFieldsSchema() {
+  return {
+    $id: PROJECT_FIELDS_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    anyOf: [
+      { $ref: "https://jxsuite.com/schema/project/core/v2#/$defs/JxFieldSchema" },
+      { $ref: "https://jxsuite.com/schema/project/core/v2#/$defs/RelationshipRef" },
+    ],
+    description:
+      "Default field-schema union for section entry schemas: the core field shape plus " +
+      "relationship references. Per-project entry documents override this resource with the " +
+      "effective union. See specs/extensions.md §5.3.",
+    title: "Jx Project Field Union",
+  };
+}
+
+/** The shipped DEFAULT $paths-value resource: permissive until extensions contribute shapes. */
+export function generateDocumentPathsSchema() {
+  return {
+    $id: DOCUMENT_PATHS_SCHEMA_ID,
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    description:
+      "Default $paths-value union for documents. Per-project entry documents override this " +
+      "resource with the union of extension-contributed paths shapes.",
+    title: "Jx Document Paths Union",
+  };
+}
+
+// ─── Extension Manifest Schema Generator ─────────────────────────────────────
+
+export function generateExtensionManifestSchema() {
+  return {
+    $id: "https://jxsuite.com/schema/extension-manifest/v1",
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: "Jx Extension Manifest",
+    ...extensionManifestSchema,
+  };
+}
+
 // ─── Class Schema Generator ─────────────────────────────────────────────────
 
 export function generateClassSchema() {
@@ -545,7 +624,7 @@ export async function validateDocument(doc: Record<string, unknown>) {
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 async function runSchemaCli() {
-  const { writeFileSync } = await import("node:fs");
+  const { mkdirSync, writeFileSync } = await import("node:fs");
   const { resolve, dirname } = await import("node:path");
 
   const schemaDir = dirname(resolve(process.argv[1] as string, ".."));
@@ -553,10 +632,18 @@ async function runSchemaCli() {
   const componentSchema = await generateSchema();
   const projectSchema = generateProjectSchema();
   const classSchema = generateClassSchema();
+  const projectCoreSchema = generateProjectCoreSchema();
+  const manifestSchema = generateExtensionManifestSchema();
+  const fieldsSchema = generateProjectFieldsSchema();
+  const pathsSchema = generateDocumentPathsSchema();
 
   const componentStr = JSON.stringify(componentSchema, null, 2);
   const projectStr = JSON.stringify(projectSchema, null, 2);
   const classStr = JSON.stringify(classSchema, null, 2);
+  const projectCoreStr = JSON.stringify(projectCoreSchema, null, 2);
+  const manifestStr = JSON.stringify(manifestSchema, null, 2);
+  const fieldsStr = JSON.stringify(fieldsSchema, null, 2);
+  const pathsStr = JSON.stringify(pathsSchema, null, 2);
 
   const [out] = process.argv.slice(2);
 
@@ -567,10 +654,23 @@ async function runSchemaCli() {
     writeFileSync(resolve(schemaDir, "schema.json"), componentStr, "utf8");
     writeFileSync(resolve(schemaDir, "project-schema.json"), projectStr, "utf8");
     writeFileSync(resolve(schemaDir, "class-schema.json"), classStr, "utf8");
+    mkdirSync(resolve(schemaDir, "schemas"), { recursive: true });
+    writeFileSync(
+      resolve(schemaDir, "schemas", "project.core.schema.json"),
+      projectCoreStr,
+      "utf8",
+    );
+    writeFileSync(resolve(schemaDir, "schemas", "project.fields.schema.json"), fieldsStr, "utf8");
+    writeFileSync(resolve(schemaDir, "schemas", "document.paths.schema.json"), pathsStr, "utf8");
+    writeFileSync(resolve(schemaDir, "extension-manifest.schema.json"), manifestStr, "utf8");
     console.error("Generated:");
     console.error("  schema.json (component)");
     console.error("  project-schema.json");
     console.error("  class-schema.json");
+    console.error("  schemas/project.core.schema.json");
+    console.error("  schemas/project.fields.schema.json");
+    console.error("  schemas/document.paths.schema.json");
+    console.error("  extension-manifest.schema.json");
   }
 }
 

package/src/validate-project.ts

@@ -0,0 +1,144 @@
+/**
+ * Validate-project — project.json validation against the generated per-project entry schema
+ * (specs/extensions.md §5.4).
+ *
+ * Node-only by design (mirrors the dynamic-ajv-import pattern of `validateDocument`): reads
+ * `<root>/project.json` and `<root>/project.schema.json`, compiles the entry document with
+ * ajv-2020, and resolves its relative `$ref`s through a file loader restricted to the project root
+ * and its node_modules. The entry file's URL is injected as `$id` at load time so the committed,
+ * machine-path-free relative refs resolve.
+ *
+ * When a `./node_modules/...` ref does not exist on disk (workspace hoisting leaves in-repo
+ * starters without their own node_modules), the loader falls back to host resolution of the bare
+ * specifier — the same project-first-then-host order as createNodeFormatIO.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export interface ProjectValidationResult {
+  valid: boolean;
+  errors: unknown[] | null;
+}
+
+// Minimal structural types for the optional `ajv` peer dependency (no direct dependency, and it
+// Ships no types usable from here) — same pattern as validateDocument in src/schema.ts.
+interface AjvValidateFn {
+  (doc: unknown): boolean;
+  errors?: unknown[] | null;
+}
+interface AjvInstance {
+  compileAsync: (schema: unknown) => Promise<AjvValidateFn>;
+}
+type AjvCtor = new (opts: {
+  allErrors: boolean;
+  strict: boolean;
+  loadSchema: (uri: string) => Promise<Record<string, unknown>>;
+}) => AjvInstance;
+
+/**
+ * Validate `<projectRoot>/project.json` against `<projectRoot>/project.schema.json`.
+ *
+ * Validation failures are data (`{ valid: false, errors }`); infrastructure failures — missing
+ * files, unresolvable refs, refs escaping the project root — throw.
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Promise<ProjectValidationResult>}
+ */
+export async function validateProjectFile(projectRoot: string): Promise<ProjectValidationResult> {
+  const root = resolve(projectRoot);
+  const projectPath = resolve(root, "project.json");
+  const schemaPath = resolve(root, "project.schema.json");
+
+  if (!existsSync(projectPath)) {
+    throw new Error(`project.json not found in ${root}`);
+  }
+  if (!existsSync(schemaPath)) {
+    throw new Error(
+      `project.schema.json not found in ${root} — run \`jx schema\` to generate it from ` +
+        `project.json#/extensions`,
+    );
+  }
+
+  const project = JSON.parse(readFileSync(projectPath, "utf8")) as Record<string, unknown>;
+  const entrySchema = JSON.parse(readFileSync(schemaPath, "utf8")) as Record<string, unknown>;
+  // The committed entry document is machine-path-free; injecting its file URL as $id makes its
+  // Relative ./node_modules/... refs resolve against the project root.
+  entrySchema.$id = pathToFileURL(schemaPath).href;
+
+  let Ajv: AjvCtor;
+  try {
+    // The entry document is JSON Schema 2020-12, so use the matching Ajv build.
+    ({ default: Ajv } = (await import("ajv/dist/2020")) as { default: AjvCtor });
+  } catch (error) {
+    throw new Error("Project validation requires ajv: bun add ajv", { cause: error });
+  }
+
+  const ajv = new Ajv({
+    allErrors: true,
+    loadSchema: (uri) => loadProjectSchemaRef(uri, root),
+    strict: false,
+  });
+
+  const validate = await ajv.compileAsync(entrySchema);
+  const valid = validate(project);
+  return { errors: validate.errors ?? null, valid };
+}
+
+/**
+ * Restricted schema loader: only `file:` URLs inside the project root are served. Missing files
+ * under `<root>/node_modules/` fall back to host resolution of the corresponding bare specifier
+ * (in-repo starters have no local node_modules; the fragments still ship with the host).
+ *
+ * @param {string} uri - The `$ref` target ajv could not resolve from already-loaded resources
+ * @param {string} root - Absolute project root
+ * @returns {Promise<Record<string, unknown>>}
+ */
+async function loadProjectSchemaRef(uri: string, root: string): Promise<Record<string, unknown>> {
+  if (!uri.startsWith("file:")) {
+    throw new Error(
+      `Cannot resolve schema ref "${uri}": only project-relative file refs are loadable ` +
+        `(canonical URIs must resolve from already-loaded fragments)`,
+    );
+  }
+
+  const filePath = fileURLToPath(uri);
+  const rel = relative(root, filePath);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new Error(`Schema ref "${uri}" escapes the project root ${root}`);
+  }
+
+  if (existsSync(filePath)) {
+    return JSON.parse(readFileSync(filePath, "utf8")) as Record<string, unknown>;
+  }
+
+  // Host fallback: <root>/node_modules/<specifier> is absent — resolve the specifier through the
+  // Project's own resolution first, then the host's (workspace symlinks resolve transparently).
+  const posixRel = rel.split("\\").join("/");
+  const marker = "node_modules/";
+  const markerIndex = posixRel.lastIndexOf(marker);
+  if (markerIndex === -1) {
+    throw new Error(`Schema ref "${uri}" does not exist`);
+  }
+  const specifier = posixRel.slice(markerIndex + marker.length);
+
+  let resolved: string;
+  try {
+    const projRequire = createRequire(resolve(root, "package.json"));
+    resolved = projRequire.resolve(specifier);
+  } catch {
+    try {
+      const selfRequire = createRequire(import.meta.url);
+      resolved = selfRequire.resolve(specifier);
+    } catch (error) {
+      throw new Error(
+        `Schema ref "${uri}" does not exist and "${specifier}" is not resolvable from the ` +
+          `project or the host`,
+        { cause: error },
+      );
+    }
+  }
+  return JSON.parse(readFileSync(resolved, "utf8")) as Record<string, unknown>;
+}

package/types.ts

@@ -3,7 +3,6 @@ import type { FromSchema } from "json-schema-to-ts";
 import type { headEntrySchema } from "./defs/head-entry.schema";
 import type { imageConfigSchema } from "./defs/image-config.schema";
 import type { cemEventSchema, cemParameterSchema } from "./defs/cem.schema";
-import type { contentTypeDefSchema } from "./defs/content-type-def.schema";
 import type { projectConfigSchema } from "./defs/project-config.schema";
 import type { refObjectSchema } from "./defs/ref-object.schema";
 import type { styleObjectSchema } from "./defs/style-object.schema";
@@ -32,7 +31,6 @@ export namespace Strict {
   export type ImageConfig = FromSchema<typeof imageConfigSchema>;
   export type CemParameter = FromSchema<typeof cemParameterSchema>;
   export type CemEvent = FromSchema<typeof cemEventSchema>;
-  export type ContentTypeDef = FromSchema<typeof contentTypeDefSchema>;
   export type RefObject = FromSchema<typeof refObjectSchema>;
   export type Style = FromSchema<typeof styleObjectSchema>;
   export type Element = FromSchema<typeof elementDefSchema>;
@@ -186,8 +184,6 @@ export interface CemEvent {
   deprecated?: boolean | string;
 }
 
-export type ContentTypeDef = FromSchema<typeof contentTypeDefSchema>;
-
 export type RefObject = FromSchema<typeof refObjectSchema>;
 
 export interface JxStyle {
@@ -429,7 +425,24 @@ export interface JxClassDef {
   [key: string]: unknown;
 }
 
+/** The adapters the compiler actually implements (site-loader VALID_ADAPTERS + "static"). */
+export type AdapterId = "static" | "cloudflare-pages" | "cloudflare-workers" | "node" | "bun";
+
+/**
+ * Deployment tracking (project.json `build.deploy`): the hosting project this repo publishes to.
+ * Identifiers only — no secrets — so it travels with the repo and any Studio (local or cloud) can
+ * tell whether publishing is set up.
+ */
+export interface DeployConfig {
+  provider: "cloudflare-pages";
+  accountId: string;
+  projectName: string;
+  productionUrl?: string | undefined;
+}
+
 export interface ProjectConfig {
+  /** Relative path to the generated per-project schema (written by `jx schema`). */
+  $schema?: string;
   name?: string;
   url?: string;
   state?: Record<string, unknown>;
@@ -437,10 +450,20 @@ export interface ProjectConfig {
   $elements?: (string | JxElement)[];
   $head?: JxHeadEntry[];
   $defs?: Record<string, unknown>;
-  build?: { adapter?: string; sitemap?: boolean; [key: string]: unknown };
+  build?: {
+    adapter?: AdapterId | (string & Record<never, never>);
+    deploy?: DeployConfig;
+    sitemap?: boolean;
+    [key: string]: unknown;
+  };
   images?: ImageConfig;
   imports?: Record<string, string>;
-  contentTypes?: Record<string, ContentTypeDef>;
+  /**
+   * Extension packages: bare package names (resolved project-first) or relative paths. Each must
+   * export jx-extension.json. Extension-contributed sections (e.g. `content`) are opaque top-level
+   * keys absorbed by the index signature.
+   */
+  extensions?: string[];
   /** Redirect map: source path → destination (or destination with HTTP status). */
   redirects?: Record<string, string | { destination: string; status?: number }>;
   defaults?: {
@@ -460,13 +483,15 @@ export interface ProjectConfig {
 export type JxAttributeValue = Bindable<string | number | boolean>;
 
 /**
- * A dynamic-route path source (spec §4.3): content-type based, explicit values, data-file ref, or a
- * legacy array of param objects.
+ * A dynamic-route path source (spec §4.3): explicit values, data-file ref, a legacy array of param
+ * objects, or an extension-discriminated source (an object carrying a `resolvePaths` discriminator
+ * key registered by an enabled extension, e.g. the parser's `contentType` — the extension owns the
+ * narrow shape).
  */
 export type JxPathsDef =
-  | { contentType: string; param?: string; field?: string }
   | { values: JsonValue[]; param?: string }
   | { $ref: string; param?: string; field?: string }
+  | { param?: string; field?: string; [discriminator: string]: unknown }
   | Record<string, JsonValue>[];
 
 /**
@@ -521,6 +546,8 @@ export interface JxMutableNode {
 export type JxPath = (string | number)[];
 
 // ─── Content Type Schema ────────────────────────────────────────────────────────
+// Part-3 cleanup: move to parser — the parser extension owns the content-section shapes now; these
+// Stay here only while the studio still imports them from @jxsuite/schema/types.
 
 /** One field within a content-type JSON schema; recursive for nested objects. */
 export interface ContentTypeSchemaField {
@@ -538,3 +565,29 @@ export interface ContentTypeSchema {
   required?: string[];
   [key: string]: unknown;
 }
+
+// ─── Content Wire Types ─────────────────────────────────────────────────────────
+// Core wire shapes for content loading (specs/extensions.md §8): format classes' `load`
+// Capabilities return ContentLoaderEntry[], and hosts pass the entries through untouched.
+// Extensions implement them; core only threads them.
+
+/** A table-of-contents entry extracted from a loaded content document. */
+export interface TocEntry {
+  depth: number;
+  text: string;
+  id: string;
+}
+
+/** One loaded content entry, as produced by a format class's `load` capability. */
+export interface ContentLoaderEntry {
+  id: string;
+  data: Record<string, unknown>;
+  body: string | null;
+  $children?: (JxElement | string)[];
+  _meta?: {
+    excerpt?: string;
+    toc?: TocEntry[];
+    readingTime?: number;
+    wordCount?: number;
+  };
+}

package/defs/content-type-def.schema.ts

@@ -1,37 +0,0 @@
-export const contentTypeDefSchema = {
-  description:
-    "Content type definition. Defines the source directory, frontmatter schema, and element dependencies.",
-  properties: {
-    $elements: {
-      description: "Custom elements available in markdown directives for this content type.",
-      items: {
-        oneOf: [
-          {
-            properties: { $ref: { type: "string" } },
-            required: ["$ref"],
-            type: "object",
-          },
-          { type: "string" },
-        ],
-      },
-      type: "array",
-    },
-    format: {
-      description:
-        "Import name of a format class declared in the project imports map " +
-        '(e.g. "Markdown", "Csv"). When omitted, the format is derived from the ' +
-        'source file extension via the format registry. "json" is the only built-in.',
-      type: "string",
-    },
-    schema: {
-      description: "JSON Schema for validating frontmatter of content type entries.",
-      type: "object",
-    },
-    source: {
-      description: "Path to the content directory relative to the project root.",
-      examples: ["./content/blog/", "./content/docs/"],
-      type: "string",
-    },
-  },
-  type: "object",
-} as const;