@backmatter/core 0.0.6

package/src/sync-schema.ts

@@ -0,0 +1,52 @@
+// packages/core/src/sync-schema.ts
+import {
+  serializeSchema,
+  type ModelDef,
+  type ModelSnapshot,
+} from "./model";
+import type { BlockDef } from "./block";
+
+export function detectGitBranch(
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  const override = env.BACKMATTER_GIT_BRANCH?.trim();
+  if (override) return override;
+  const vercel = env.VERCEL_GIT_COMMIT_REF?.trim();
+  if (vercel) return vercel;
+  return null;
+}
+
+export type SyncSchemaOptions = {
+  apiUrl: string;
+  workspaceId: string;
+  hostToken: string;
+  models: Array<ModelDef | ModelSnapshot>;
+  blocks?: BlockDef[];
+  branch?: string;
+  siteUrl?: string;
+};
+
+export async function syncSchema(options: SyncSchemaOptions): Promise<void> {
+  const branch = options.branch ?? detectGitBranch() ?? "main";
+  const payload = serializeSchema(options.models as ModelDef[], options.blocks);
+  const body: { payload: ReturnType<typeof serializeSchema>; branch: string; siteUrl?: string } = {
+    payload,
+    branch,
+  };
+  if (options.siteUrl) body.siteUrl = options.siteUrl;
+  const res = await fetch(
+    `${options.apiUrl.replace(/\/$/, "")}/workspaces/${options.workspaceId}/schema`,
+    {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${options.hostToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`schema sync failed: ${res.status} ${text}`);
+  }
+}

package/src/validate.ts

@@ -0,0 +1,149 @@
+// packages/core/src/validate.ts
+import { modelFormat, parseDoc } from "./doc-format";
+import type { Frontmatter } from "./mdx";
+import { parseMdx } from "./mdx";
+import type { ModelSnapshot } from "./model";
+import type { BlockInstance, BlockSnapshot } from "./block";
+import { matchAnyModelPath } from "./path";
+import { expectedTypeFor, frontmatterZod, normalizeFrontmatter } from "./zod";
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; errors: string[] };
+
+/**
+ * Frontmatter must satisfy the model: required fields present and non-blank,
+ * every declared field of the right primitive type. Unknown keys are ignored.
+ */
+export function validateFrontmatter(
+  model: Pick<ModelSnapshot, "fields">,
+  frontmatter: Frontmatter,
+): ValidationResult {
+  const data = normalizeFrontmatter(frontmatter);
+  const result = frontmatterZod(model).safeParse(data);
+  if (result.success) return { ok: true };
+
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const issue of result.error.issues) {
+    const name = String(issue.path[0] ?? "");
+    const field = model.fields[name];
+    if (!field || seen.has(name)) continue;
+    seen.add(name);
+    const missing = data[name] === undefined;
+    if (issue.code === "too_small" || (issue.code === "invalid_type" && missing)) {
+      errors.push(`${name} is required`);
+    } else {
+      errors.push(`${name} must be a ${expectedTypeFor(field.kind)}`);
+    }
+  }
+  // Never fail open: if every issue was filtered above, still report invalid.
+  // Unreachable through the public API today (normalizeFrontmatter always yields
+  // a plain object and looseObject only raises issues on declared fields), so
+  // there is no test exercising this branch.
+  if (errors.length === 0) return { ok: false, errors: ["frontmatter is invalid"] };
+  return { ok: false, errors };
+}
+
+function asBlockList(value: unknown): BlockInstance[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is BlockInstance => {
+    if (!item || typeof item !== "object") return false;
+    const row = item as Record<string, unknown>;
+    return typeof row.id === "string" && typeof row.type === "string";
+  });
+}
+
+/** Validate each block instance against the blocks catalog. */
+export function validateBlocks(
+  blocks: unknown,
+  catalog: BlockSnapshot[],
+  prefix = "blocks",
+): ValidationResult {
+  if (!Array.isArray(blocks)) return { ok: true };
+  const byName = new Map(catalog.map((b) => [b.name, b]));
+  const errors: string[] = [];
+  asBlockList(blocks).forEach((block, i) => {
+    const def = byName.get(block.type);
+    if (!def) {
+      errors.push(`${prefix}[${i}]: unknown type "${block.type}"`);
+      return;
+    }
+    const props = block.props && typeof block.props === "object" ? block.props : {};
+    const result = validateFrontmatter({ fields: def.fields }, props);
+    if (!result.ok) {
+      for (const err of result.errors) {
+        errors.push(`${prefix}[${i}].${err}`);
+      }
+    }
+  });
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true };
+}
+
+/**
+ * Parse a raw MDX string and validate its frontmatter. Never throws on
+ * malformed frontmatter (an unknown field kind in `model` still throws).
+ */
+export function validateMdxFile(
+  model: Pick<ModelSnapshot, "fields">,
+  raw: string,
+): ValidationResult {
+  let frontmatter: Frontmatter;
+  try {
+    frontmatter = parseMdx(raw).frontmatter;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "invalid";
+    return { ok: false, errors: [`frontmatter: ${msg}`] };
+  }
+  return validateFrontmatter(model, frontmatter);
+}
+
+export function validateDocFile(
+  model: Pick<ModelSnapshot, "fields" | "format">,
+  raw: string,
+  catalog: BlockSnapshot[] = [],
+): ValidationResult {
+  const format = modelFormat(model);
+  let frontmatter: Frontmatter;
+  try {
+    frontmatter = parseDoc(raw, format).frontmatter;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "invalid";
+    const label = format === "page" ? "JSON" : "frontmatter";
+    return { ok: false, errors: [msg.startsWith("JSON:") ? msg : `${label}: ${msg}`] };
+  }
+  const base = validateFrontmatter(model, frontmatter);
+  if (format !== "page") return base;
+  const blockField = Object.entries(model.fields).find(([, f]) => f.kind === "blocks");
+  if (!blockField) return base;
+  const blockResult = validateBlocks(frontmatter[blockField[0]], catalog, blockField[0]);
+  if (base.ok && blockResult.ok) return { ok: true };
+  return {
+    ok: false,
+    errors: [...(base.ok ? [] : base.errors), ...(blockResult.ok ? [] : blockResult.errors)],
+  };
+}
+
+export type ContentFileResult =
+  | { path: string; type: string; ok: true }
+  | { path: string; type: string; ok: false; errors: string[] }
+  | { path: string; type: null; ok: true; skipped: true };
+
+/** Validate many repo-relative files against a model set. Order is preserved. */
+export function validateContentTree(input: {
+  models: ModelSnapshot[];
+  files: Array<{ path: string; raw: string }>;
+  catalog?: BlockSnapshot[];
+}): ContentFileResult[] {
+  const catalog = input.catalog ?? [];
+  return input.files.map((file) => {
+    const hit = matchAnyModelPath(input.models, file.path);
+    if (!hit) return { path: file.path, type: null, ok: true, skipped: true };
+    const model = input.models.find((m) => m.type === hit.type);
+    if (!model) return { path: file.path, type: null, ok: true, skipped: true };
+    const result = validateDocFile(model, file.raw, catalog);
+    if (result.ok) return { path: file.path, type: model.type, ok: true };
+    return { path: file.path, type: model.type, ok: false, errors: result.errors };
+  });
+}

package/src/zod.ts

@@ -0,0 +1,111 @@
+// packages/core/src/zod.ts
+import { z } from "zod";
+import type { FieldKind, FieldSnapshot } from "./fields";
+import type { Frontmatter } from "./mdx";
+import type { ModelSnapshot } from "./model";
+
+/** Primitive a field kind is stored as in frontmatter; used in error messages. */
+export function expectedTypeFor(kind: FieldKind): "string" | "number" | "boolean" | "array" {
+  switch (kind) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "blocks":
+      return "array";
+    case "text":
+    case "slug":
+    case "locale":
+    case "image":
+    case "relation":
+      return "string";
+    default: {
+      const _exhaustive: never = kind;
+      throw new Error(`unknown field kind: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/** Example JSON value for prompts and docs; image is always a URL string. */
+export function exampleValueFor(kind: FieldKind): unknown {
+  switch (kind) {
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "blocks":
+      return [];
+    case "image":
+      return "https://example.com/image.jpg";
+    case "slug":
+      return "example-slug";
+    case "locale":
+      return "en";
+    case "relation":
+      return "related-slug";
+    case "text":
+      return "";
+    default: {
+      const _exhaustive: never = kind;
+      throw new Error(`unknown field kind: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+function fieldZod(field: FieldSnapshot): z.ZodType {
+  if (field.kind === "blocks") {
+    const item = z.object({
+      id: z.string().min(1),
+      type: z.string().min(1),
+      props: z.record(z.string(), z.unknown()).optional().default({}),
+    });
+    const arr = field.required ? z.array(item).min(1) : z.array(item).optional();
+    return arr;
+  }
+  let base: z.ZodType;
+  switch (expectedTypeFor(field.kind)) {
+    case "number":
+      base = z.number();
+      break;
+    case "boolean":
+      base = z.boolean();
+      break;
+    default:
+      // Required strings must be non-blank; trim happens before min(1).
+      base = field.required ? z.string().trim().min(1) : z.string();
+  }
+  return field.required ? base : base.optional();
+}
+
+/**
+ * Zod object for a model's frontmatter.
+ * Loose: keys not in the model pass through untouched (drift is not an error).
+ */
+export function frontmatterZod(model: Pick<ModelSnapshot, "fields">) {
+  const shape: Record<string, z.ZodType> = {};
+  for (const [name, field] of Object.entries(model.fields)) {
+    shape[name] = fieldZod(field);
+  }
+  return z.looseObject(shape);
+}
+
+/** YAML `key:` with no value parses to null; treat null as "not set". */
+export function normalizeFrontmatter(frontmatter: Frontmatter): Frontmatter {
+  const out: Frontmatter = {};
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (value !== null) out[key] = value;
+  }
+  return out;
+}
+
+export type FrontmatterJsonSchema = z.core.JSONSchema.BaseSchema & {
+  title: string;
+};
+
+/** JSON Schema (draft 2020-12) for editor tooling. */
+export function frontmatterJsonSchema(model: ModelSnapshot): FrontmatterJsonSchema {
+  const schema = z.toJSONSchema(frontmatterZod(model), {
+    target: "draft-2020-12",
+  });
+  return { ...schema, title: model.type };
+}