@nubbin/core 0.1.0-rc.4 → 0.1.0-rc.5

package/dist/index.d.ts

@@ -1,5 +1,26 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
+type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
+interface FieldNode {
+    /** Dotted path from the schema root, with `[]` for array members: `cta.label`, `items[].title`. */
+    path: string;
+    kind: FieldKind;
+    optional: boolean;
+    /** Present only for `enum`. */
+    members?: readonly string[];
+}
+interface SchemaAdapter {
+    describe(schema: unknown): FieldNode[];
+}
+
+/**
+ * Reads a zod schema for the studio and hint resolution, entirely through the Standard JSON
+ * Schema converter the schema itself carries — `core` imports nothing from zod to do it.
+ * Validation never runs against this projection; it always runs `schema["~standard"].validate()`
+ * on the real schema.
+ */
+declare const zodAdapter: SchemaAdapter;
+
 type UnknownProps = Record<string, unknown>;
 /**
  * A block's props, derived from its schema. The whole of invariant 1 in one type: there is no
@@ -148,6 +169,41 @@ declare class CompileError extends Error {
     constructor(issues: readonly CompileIssue[]);
 }
 
+/** One route pointer and the artifact it names, as an adapter read them. */
+interface LiveRoute {
+    pointer: RoutePointer;
+    /** `null` when the store holds no artifact at the pointer's hash — a pointer into nothing. */
+    artifact: Artifact | null;
+}
+/** One block's version delta between what a live artifact needs and what is registered now. */
+interface BlockDrift {
+    block: string;
+    /** The version the artifact was compiled against. */
+    live: number;
+    /** The version registered now — `null` when the registry no longer holds the block at all. */
+    registered: number | null;
+}
+/**
+ * Why one live route would not render. `unreadable-artifact` is a pointer whose hash the store
+ * cannot resolve, which breaks the route without any registry change at all.
+ */
+type RouteIncompatibility = {
+    route: string;
+    hash: string;
+    reason: "unreadable-artifact";
+} | {
+    route: string;
+    hash: string;
+    reason: "block-drift";
+    drifted: BlockDrift[];
+};
+/** The verdict over every live pointer. `checked` is reported so a run over nothing cannot read as a pass. */
+interface CompatibilityReport {
+    checked: number;
+    compatible: boolean;
+    incompatible: RouteIncompatibility[];
+}
+
 interface Registry {
     get(name: string): Block | undefined;
     names(): string[];
@@ -155,6 +211,17 @@ interface Registry {
     fingerprint(): string;
 }
 
+/**
+ * The guardrail's whole question: would this registry fail to render an artifact a live route
+ * pointer currently references? `checkRollback` decides each route — one artifact against the
+ * registry is the same comparison whether a pointer is moving or a registry is — and this walks
+ * every pointer the caller read, so publishing and merging are held to one rule.
+ *
+ * Pure, and synchronous: the caller reads the store and hands over what it found, so this runs
+ * in CI, in a worker, or in a browser studio unchanged.
+ */
+declare function checkCompatibility(live: readonly LiveRoute[], registry: Registry): CompatibilityReport;
+
 type RollbackCheck = {
     compatible: true;
 } | {
@@ -200,18 +267,12 @@ declare function defineBlock<Schema extends StandardSchemaV1, Component>(block:
  */
 declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
 
-type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
-interface FieldNode {
-    /** Dotted path from the schema root, with `[]` for array members: `cta.label`, `items[].title`. */
-    path: string;
-    kind: FieldKind;
-    optional: boolean;
-    /** Present only for `enum`. */
-    members?: readonly string[];
-}
-interface SchemaAdapter {
-    describe(schema: unknown): FieldNode[];
-}
+/**
+ * The report as a CI log reads it. `checked` leads every line, including the passing one: a run
+ * that found no pointers and a run that cleared eight are the same word otherwise, and the first
+ * of those is a gate certifying nothing.
+ */
+declare function formatCompatibilityReport(report: CompatibilityReport): string;
 
 /**
  * matchKind is parsed from the route at publish, never caller-supplied. It lives in core so
@@ -219,4 +280,19 @@ interface SchemaAdapter {
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
-export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDocs, type BlockUi, type Catalog, type CatalogEntry, CompileError, type CompileIssue, type CompileIssueCode, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type Manifest, type Node, type Registry, type RollbackCheck, type RoutePointer, type SchemaAdapter, type SlotConstraint, type UnknownProps, checkRollback, compile, createRegistry, defineBlock, defineCatalog, parseMatchKind };
+/** Copy-on-write down one dotted path. Paths address object fields only; `[]` has no single target. */
+declare function setAtPath(target: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+
+/**
+ * The first document operation: a new `DocumentVersion` with one prop set on one node,
+ * copy-on-write, every other node untouched by reference. It lives beside `compile` so any
+ * caller — an editor, a script, an agent — writes a document the same way
+ * ([#134](https://github.com/effekt/nubbin/issues/134)).
+ *
+ * It does not validate the value (that is `compile`'s job at the next compile) and does not
+ * bump `version` — appending a version is the authoring store's concern
+ * ([#11](https://github.com/effekt/nubbin/issues/11)), not a property of one edit.
+ */
+declare function setNodeProp(version: DocumentVersion, nodeId: string, path: string, value: unknown): DocumentVersion;
+
+export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDocs, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, CompileError, type CompileIssue, type CompileIssueCode, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, type Registry, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type UnknownProps, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, parseMatchKind, setAtPath, setNodeProp, zodAdapter };

package/dist/index.js

@@ -1,3 +1,111 @@
+// src/adapters/isStandardJsonSchemaCapable.ts
+function isStandardJsonSchemaCapable(value) {
+  if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
+  const props = value["~standard"];
+  if (typeof props !== "object" || props === null || !("jsonSchema" in props)) return false;
+  const converter = props.jsonSchema;
+  if (typeof converter !== "object" || converter === null || !("input" in converter)) return false;
+  return typeof converter.input === "function";
+}
+
+// src/adapters/projectJsonSchema.ts
+var OPTIONS = {
+  target: "draft-2020-12",
+  /** zod's option name: a type JSON Schema cannot express throws here, at registration. */
+  libraryOptions: { unrepresentable: "throw" }
+};
+function projectJsonSchema(schema) {
+  if (!isStandardJsonSchemaCapable(schema)) {
+    throw new Error("Schema does not expose the Standard JSON Schema converter (spec >= 1.1)");
+  }
+  return schema["~standard"].jsonSchema.input(OPTIONS);
+}
+
+// src/adapters/kindOfJsonSchema.ts
+function kindOfJsonSchema(node) {
+  if (Array.isArray(node.enum)) return "enum";
+  if (Array.isArray(node.oneOf) || Array.isArray(node.anyOf)) return "union";
+  switch (node.type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+
+// src/adapters/fieldNodeAt.ts
+function fieldNodeAt(path, node, optional) {
+  const kind = kindOfJsonSchema(node);
+  if (kind === "enum" && Array.isArray(node.enum)) {
+    return { path, kind, optional, members: node.enum.map(String) };
+  }
+  return { path, kind, optional };
+}
+
+// src/adapters/isJsonSchemaNode.ts
+function isJsonSchemaNode(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/adapters/walkArrayItems.ts
+function walkArrayItems(arrayNode, path, descend) {
+  if (!isJsonSchemaNode(arrayNode.items)) return [];
+  const itemPath = `${path}[]`;
+  return [fieldNodeAt(itemPath, arrayNode.items, false), ...descend(arrayNode.items, itemPath)];
+}
+
+// src/adapters/walkObjectProperties.ts
+function walkObjectProperties(objectNode, basePath, descend) {
+  const { properties, required } = objectNode;
+  if (!isJsonSchemaNode(properties)) return [];
+  const requiredNames = Array.isArray(required) ? required : [];
+  const fields = [];
+  for (const [name, child] of Object.entries(properties)) {
+    if (!isJsonSchemaNode(child)) continue;
+    const path = basePath === "" ? name : `${basePath}.${name}`;
+    fields.push(fieldNodeAt(path, child, !requiredNames.includes(name)));
+    fields.push(...descend(child, path));
+  }
+  return fields;
+}
+
+// src/adapters/walkUnionBranches.ts
+function walkUnionBranches(unionNode, path, descend) {
+  const branches = [unionNode.oneOf, unionNode.anyOf].filter(Array.isArray).flat();
+  return branches.flatMap((branch) => isJsonSchemaNode(branch) ? descend(branch, path) : []);
+}
+
+// src/adapters/walkJsonSchema.ts
+function walkJsonSchema(node, basePath) {
+  const kind = kindOfJsonSchema(node);
+  if (kind === "object") return walkObjectProperties(node, basePath, walkJsonSchema);
+  if (kind === "array") return walkArrayItems(node, basePath, walkJsonSchema);
+  if (kind === "union") return walkUnionBranches(node, basePath, walkJsonSchema);
+  return [];
+}
+
+// src/adapters/zodAdapter.ts
+var zodAdapter = {
+  describe(schema) {
+    const fields = walkJsonSchema(projectJsonSchema(schema), "");
+    const seen = /* @__PURE__ */ new Set();
+    return fields.filter((field) => {
+      if (seen.has(field.path)) return false;
+      seen.add(field.path);
+      return true;
+    });
+  }
+};
+
 // src/CompileError.ts
 var CompileError = class extends Error {
   issues;
@@ -16,6 +124,34 @@ function checkRollback(artifact, registry) {
   return drifted.length === 0 ? { compatible: true } : { compatible: false, drifted };
 }
 
+// src/describeDrift.ts
+function describeDrift(artifact, registry, drifted) {
+  return drifted.flatMap((block) => {
+    const live = artifact.blockVersions[block];
+    return live === void 0 ? [] : [{ block, live, registered: registry.get(block)?.version ?? null }];
+  });
+}
+
+// src/checkCompatibility.ts
+function checkCompatibility(live, registry) {
+  const incompatible = live.flatMap(({ pointer, artifact }) => {
+    const { route, hash } = pointer;
+    if (artifact === null) {
+      return [{ route, hash, reason: "unreadable-artifact" }];
+    }
+    const check = checkRollback(artifact, registry);
+    return check.compatible ? [] : [
+      {
+        route,
+        hash,
+        reason: "block-drift",
+        drifted: describeDrift(artifact, registry, check.drifted)
+      }
+    ];
+  });
+  return { checked: live.length, compatible: incompatible.length === 0, incompatible };
+}
+
 // src/artifactNodeOf.ts
 function artifactNodeOf(node, resolve) {
   const { props, holes } = resolve(node);
@@ -401,7 +537,7 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.1.0-rc.4";
+var NUBBIN_VERSION = "0.1.0-rc.5";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -497,114 +633,6 @@ function defineBlock(block) {
   return block;
 }
 
-// src/adapters/isStandardJsonSchemaCapable.ts
-function isStandardJsonSchemaCapable(value) {
-  if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
-  const props = value["~standard"];
-  if (typeof props !== "object" || props === null || !("jsonSchema" in props)) return false;
-  const converter = props.jsonSchema;
-  if (typeof converter !== "object" || converter === null || !("input" in converter)) return false;
-  return typeof converter.input === "function";
-}
-
-// src/adapters/projectJsonSchema.ts
-var OPTIONS = {
-  target: "draft-2020-12",
-  /** zod's option name: a type JSON Schema cannot express throws here, at registration. */
-  libraryOptions: { unrepresentable: "throw" }
-};
-function projectJsonSchema(schema) {
-  if (!isStandardJsonSchemaCapable(schema)) {
-    throw new Error("Schema does not expose the Standard JSON Schema converter (spec >= 1.1)");
-  }
-  return schema["~standard"].jsonSchema.input(OPTIONS);
-}
-
-// src/adapters/kindOfJsonSchema.ts
-function kindOfJsonSchema(node) {
-  if (Array.isArray(node.enum)) return "enum";
-  if (Array.isArray(node.oneOf) || Array.isArray(node.anyOf)) return "union";
-  switch (node.type) {
-    case "string":
-      return "string";
-    case "number":
-    case "integer":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "array":
-      return "array";
-    case "object":
-      return "object";
-    default:
-      return "unknown";
-  }
-}
-
-// src/adapters/fieldNodeAt.ts
-function fieldNodeAt(path, node, optional) {
-  const kind = kindOfJsonSchema(node);
-  if (kind === "enum" && Array.isArray(node.enum)) {
-    return { path, kind, optional, members: node.enum.map(String) };
-  }
-  return { path, kind, optional };
-}
-
-// src/adapters/isJsonSchemaNode.ts
-function isJsonSchemaNode(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-// src/adapters/walkArrayItems.ts
-function walkArrayItems(arrayNode, path, descend) {
-  if (!isJsonSchemaNode(arrayNode.items)) return [];
-  const itemPath = `${path}[]`;
-  return [fieldNodeAt(itemPath, arrayNode.items, false), ...descend(arrayNode.items, itemPath)];
-}
-
-// src/adapters/walkObjectProperties.ts
-function walkObjectProperties(objectNode, basePath, descend) {
-  const { properties, required } = objectNode;
-  if (!isJsonSchemaNode(properties)) return [];
-  const requiredNames = Array.isArray(required) ? required : [];
-  const fields = [];
-  for (const [name, child] of Object.entries(properties)) {
-    if (!isJsonSchemaNode(child)) continue;
-    const path = basePath === "" ? name : `${basePath}.${name}`;
-    fields.push(fieldNodeAt(path, child, !requiredNames.includes(name)));
-    fields.push(...descend(child, path));
-  }
-  return fields;
-}
-
-// src/adapters/walkUnionBranches.ts
-function walkUnionBranches(unionNode, path, descend) {
-  const branches = [unionNode.oneOf, unionNode.anyOf].filter(Array.isArray).flat();
-  return branches.flatMap((branch) => isJsonSchemaNode(branch) ? descend(branch, path) : []);
-}
-
-// src/adapters/walkJsonSchema.ts
-function walkJsonSchema(node, basePath) {
-  const kind = kindOfJsonSchema(node);
-  if (kind === "object") return walkObjectProperties(node, basePath, walkJsonSchema);
-  if (kind === "array") return walkArrayItems(node, basePath, walkJsonSchema);
-  if (kind === "union") return walkUnionBranches(node, basePath, walkJsonSchema);
-  return [];
-}
-
-// src/adapters/zodAdapter.ts
-var zodAdapter = {
-  describe(schema) {
-    const fields = walkJsonSchema(projectJsonSchema(schema), "");
-    const seen = /* @__PURE__ */ new Set();
-    return fields.filter((field) => {
-      if (seen.has(field.path)) return false;
-      seen.add(field.path);
-      return true;
-    });
-  }
-};
-
 // src/adapters/resolveHintPaths.ts
 function resolveHintPaths(blockName, schema, fields) {
   const known = new Set(zodAdapter.describe(schema).map((field) => field.path));
@@ -616,6 +644,17 @@ function resolveHintPaths(blockName, schema, fields) {
   }
 }
 
+// src/assertDataHintAddressable.ts
+function assertDataHintAddressable(blockName, fields) {
+  for (const [path, hint] of Object.entries(fields)) {
+    if (hint.data !== void 0 && path.includes("[]")) {
+      throw new Error(
+        `${blockName}: ui.fields["${path}"] sets \`data\`, but a hole cannot address an array member \u2014 "[]" has no single target`
+      );
+    }
+  }
+}
+
 // src/assertValidDefaults.ts
 function assertValidDefaults(blockName, schema, defaults) {
   const result = standardValidate(schema, defaults);
@@ -629,6 +668,7 @@ function defineCatalog(entries) {
   for (const [blockName, entry] of Object.entries(entries)) {
     if (entry.ui?.fields !== void 0) {
       resolveHintPaths(blockName, entry.schema, entry.ui.fields);
+      assertDataHintAddressable(blockName, entry.ui.fields);
     }
     if (entry.defaults !== void 0) {
       assertValidDefaults(blockName, entry.schema, entry.defaults);
@@ -637,6 +677,27 @@ function defineCatalog(entries) {
   return entries;
 }
 
+// src/formatBlockDrift.ts
+function formatBlockDrift(drift) {
+  return drift.registered === null ? `${drift.block}: page needs v${drift.live}, no longer in the registry` : `${drift.block}: page needs v${drift.live}, registry has v${drift.registered}`;
+}
+
+// src/formatRouteIncompatibility.ts
+function formatRouteIncompatibility(incompatibility) {
+  const heading = `  ${incompatibility.route}  (artifact ${incompatibility.hash})`;
+  const reasons = incompatibility.reason === "unreadable-artifact" ? ["the store holds no artifact at this hash"] : incompatibility.drifted.map(formatBlockDrift);
+  return [heading, ...reasons.map((reason) => `    ${reason}`)].join("\n");
+}
+
+// src/formatCompatibilityReport.ts
+function formatCompatibilityReport(report) {
+  if (report.compatible) {
+    return `${report.checked} live route pointer(s) checked; every one is compatible with this registry.`;
+  }
+  const summary = `${report.incompatible.length} of ${report.checked} live route pointer(s) are incompatible with this registry:`;
+  return [summary, ...report.incompatible.map(formatRouteIncompatibility)].join("\n");
+}
+
 // src/parseMatchKind.ts
 function parseMatchKind(route) {
   if (route.endsWith("/*")) {
@@ -647,12 +708,41 @@ function parseMatchKind(route) {
   }
   return "exact";
 }
+
+// src/setAtPath.ts
+function setAtPath(target, path, value) {
+  const [head, ...rest] = path.split(".");
+  if (head === void 0 || head === "" || head.includes("[]")) {
+    throw new Error(`path "${path}" is not addressable`);
+  }
+  if (rest.length === 0) {
+    return { ...target, [head]: value };
+  }
+  const child = target[head];
+  const base = typeof child === "object" && child !== null ? child : {};
+  return { ...target, [head]: setAtPath(base, rest.join("."), value) };
+}
+
+// src/setNodeProp.ts
+function setNodeProp(version, nodeId, path, value) {
+  const node = version.elements[nodeId];
+  if (node === void 0) {
+    throw new Error(`no node "${nodeId}" in document "${version.documentId}"`);
+  }
+  const edited = { ...node, props: setAtPath(node.props, path, value) };
+  return { ...version, elements: { ...version.elements, [nodeId]: edited } };
+}
 export {
   CompileError,
+  checkCompatibility,
   checkRollback,
   compile,
   createRegistry,
   defineBlock,
   defineCatalog,
-  parseMatchKind
+  formatCompatibilityReport,
+  parseMatchKind,
+  setAtPath,
+  setNodeProp,
+  zodAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/core",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.5",
   "description": "The Nubbin contract: define blocks, split catalog from registry, and compile a page document into an immutable artifact.",
   "keywords": [
     "nubbin",