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

package/README.md

@@ -0,0 +1,37 @@
+# @nubbin/core
+
+The contract every other Nubbin package is built around. It defines what a block is, keeps the
+catalog and the registry apart, and compiles a page document into an immutable artifact.
+
+It has one runtime dependency — [Standard Schema](https://standardschema.dev) — and imports no
+validator, no framework and no node builtin. A build gate fails on any of the three, so the
+claim that it runs in a browser, a worker and a build step is checked rather than asserted.
+
+```bash
+npm install @nubbin/core@rc
+```
+
+```ts
+import { defineBlock, defineCatalog, createRegistry, compile } from "@nubbin/core";
+import { z } from "zod";
+
+const heroSchema = z.object({ title: z.string() });
+
+export const heroBlock = defineBlock({
+  name: "Hero",
+  schema: heroSchema,
+  component: Hero,
+  version: 1,
+  slots: {},
+});
+
+const artifact = compile(documentVersion, catalog, registry, "/promotions/summer");
+```
+
+Props are inferred from the schema with `InferProps<typeof heroSchema>`, so nothing declares a
+block's shape twice.
+
+**Release candidate.** The API is settled enough to build against and not yet stable.
+
+The design record, including the paths not taken, is at
+<https://effekt.github.io/nubbin/>. MIT.

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
@@ -11,7 +32,7 @@ type UnknownProps = Record<string, unknown>;
  */
 type InferProps<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
 interface SlotConstraint {
-    /** Block names permitted here. Omitted means any registered block. */
+    /** Block names permitted here, each resolved at registration. Omitted means any registered block. */
     allow?: readonly string[];
     min?: number;
     max?: number;
@@ -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;
 } | {
@@ -179,6 +246,9 @@ declare function compile(version: DocumentVersion, catalog: Catalog, registry: R
  * Sorted by name so registration order cannot change the fingerprint, and built from name and
  * version alone so unrelated edits — a slot constraint, a deprecation — do not invalidate every
  * artifact compiled before them.
+ *
+ * Slot `allow` lists resolve once the whole array is ingested, so a block may name a sibling
+ * registered after it.
  */
 declare function createRegistry(blocks: readonly Block[]): Registry;
 
@@ -197,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
@@ -216,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.0.0";
+var NUBBIN_VERSION = "0.1.0-rc.5";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -423,6 +559,24 @@ function compile(version, catalog, registry, route) {
   return { ...content, hash: hashArtifact(content) };
 }
 
+// src/unknownAllowEntries.ts
+function unknownAllowEntries(block, known) {
+  return Object.entries(block.slots).flatMap(
+    ([slot, constraint]) => (constraint.allow ?? []).filter((allowed) => !known.has(allowed)).map((allowed) => `"${allowed}" (${block.name}.${slot})`)
+  );
+}
+
+// src/assertSlotAllows.ts
+function assertSlotAllows(blocks) {
+  const known = new Set(blocks.map((block) => block.name));
+  const unresolved = blocks.flatMap((block) => unknownAllowEntries(block, known));
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Slot allow lists name ${unresolved.join(", ")}, which no registered block defines. Registered blocks: ${[...known].sort().join(", ")}`
+    );
+  }
+}
+
 // src/createRegistry.ts
 function createRegistry(blocks) {
   const byName = /* @__PURE__ */ new Map();
@@ -434,6 +588,7 @@ function createRegistry(blocks) {
     }
     byName.set(block.name, block);
   }
+  assertSlotAllows([...byName.values()]);
   const signature = [...byName.values()].map((block) => `${block.name}@${block.version}`).sort().join("\n");
   const fingerprint = fnv1a(signature);
   return {
@@ -478,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));
@@ -597,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);
@@ -610,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);
@@ -618,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("/*")) {
@@ -628,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.0",
+  "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",