@texuli/spec 0.7.0 → 0.8.0

package/dist/validate.d.ts

@@ -2,6 +2,7 @@ import type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation, SpecWarning }
 import type { SpecCatalog } from './catalog.js';
 import { type SpecStateType } from './contract.js';
 import { type Schema } from './dialect.js';
+import { type SpecSourceDescriptor } from './source.js';
 export type { SpecDiagnostic, SpecDiagnosticCode, SpecValidation, SpecWarning };
 /**
  * Checks one workflow graph against the workflow schema:
@@ -20,6 +21,12 @@ export interface SpecDocuments {
     workflowSchema?: Schema;
     /** `validateWorkflowGraph` from `@texuli/spec/workflow`, for hosts that render workflows. */
     validateWorkflowGraph?: WorkflowGraphValidator;
+    /**
+     * The host's data sources (spec 0.8.0), as `registry.describe()` from
+     * `@texuli/core/data-source` returns them. A `$source` binding is checked
+     * against them; without them every binding is refused (`source`).
+     */
+    sources?: readonly SpecSourceDescriptor[];
 }
 /** The workflow schema and its validator, when the host supplied both. */
 export interface WorkflowSupport {
@@ -58,6 +65,8 @@ export interface TreeOptions {
     warnings?: SpecWarning[];
     /** Checks `workflowGraph` positions; without it they fail closed. */
     workflow?: WorkflowSupport;
+    /** The host's data sources; without them `$source` bindings fail closed. */
+    sources?: readonly SpecSourceDescriptor[];
 }
 /**
  * Validate a blueprint envelope against the spec alone: the envelope schema,

package/dist/validate.js

@@ -1,5 +1,6 @@
 import { ACTION_FIELDS, contractRoot, DATA_BINDING_KEY, SPEC_ACTION_OPS, SPEC_LIMITS, SPEC_REGEX, SPEC_STATE_TYPES, STATE_BINDING_KEY, STATE_FIELDS, toDialectSchema, } from "./contract.js";
 import { isRecord, validateInstance } from "./dialect.js";
+import { checkSourceBinding, isSourceBinding, SOURCE_BINDING_KEY, } from "./source.js";
 import { checkStateSurface, surfaceInputs } from "./surface.js";
 const MAX_TREE_DEPTH = 64;
 const ACTION_KEYS = new Set(Object.values(ACTION_FIELDS).flatMap((f) => f.allowed));
@@ -53,6 +54,7 @@ export function validateBlueprint(input, documents, options = {}) {
             root: contractRoot(documents.blueprintSchema, workflow?.schema),
             workflow,
             warnings,
+            ...(documents.sources ? { sources: documents.sources } : {}),
         }));
     }
     return {
@@ -301,6 +303,7 @@ export function validateTree(tree, catalog, options = {}) {
             insideForm,
             out,
             workflow: options.workflow,
+            sources: options.sources,
         });
         if (!component) {
             context.fail('unknown-id', `${path}.id`, `"${node.id}" is not in the catalog.`);
@@ -418,6 +421,10 @@ function checkProps(given, bind, component, path, context) {
             fail('extension-prop', here, `"${name}" is a ${prop.extension} extension (${prop.kind}) and cannot come from data.`);
             continue;
         }
+        if (isSourceBinding(value)) {
+            checkPropSource(value, prop, component, here, context);
+            continue;
+        }
         if (isBindingShaped(value)) {
             checkPropBinding(value, prop, here, context);
             continue;
@@ -443,6 +450,38 @@ function checkProps(given, bind, component, path, context) {
         }
     }
 }
+/**
+ * A whole prop read from a host data source (spec 0.8.0): a sourceable prop,
+ * the closed `$defs.sourceBinding` shape, then the binding against the
+ * host's sources (fail closed without them).
+ */
+function checkPropSource(value, prop, component, path, context) {
+    const fail = (code, at, message) => context.fail(code, `${path}${at}`, message);
+    if (!(component.sourceable ?? []).includes(prop.name)) {
+        fail('source', '', `"${prop.name}" of "${component.id}" cannot read a data source.`);
+        return;
+    }
+    const shape = context.root.$defs?.sourceBinding;
+    if (!shape) {
+        fail('source', '', 'The blueprint schema has no data-source binding.');
+        return;
+    }
+    const issues = validateInstance(shape, value, context.root);
+    const first = issues[0];
+    if (first) {
+        fail('source', first.path.slice(1), `A data-source binding is ${SHAPE_HINT}: ${first.message}`);
+        return;
+    }
+    const itemSchema = prop.schema?.items;
+    const itemFields = itemSchema?.properties ? Object.keys(itemSchema.properties) : undefined;
+    for (const issue of checkSourceBinding(value, {
+        ...(context.sources ? { sources: context.sources } : {}),
+        ...(itemFields ? { itemFields } : {}),
+    })) {
+        fail(issue.code, issue.at, issue.message);
+    }
+}
+const SHAPE_HINT = `{"${SOURCE_BINDING_KEY}": name, "query": {...}, "map": {...}}`;
 /** Whether `value` is a legal value of `prop` (kind, enum and property schema). */
 function fits(prop, value, root) {
     if (kindProblem(prop, value) !== null)
@@ -494,6 +533,10 @@ function walkOpaque(value, path, depth, context) {
     }
     if (!isRecord(value))
         return;
+    if (isSourceBinding(value)) {
+        context.fail('source', path, 'A data-source binding reads only a whole top-level prop.');
+        return;
+    }
     if (isBindingShaped(value)) {
         nestedBinding(value, path, context, undefined);
         return;
@@ -577,6 +620,10 @@ function checkPropSchemaValue(name, propSchema, value, path, context) {
                 }
                 return schemaIssues;
             }
+            if (isSourceBinding(current)) {
+                sub.fail('source', at(relative), 'A data-source binding reads only a whole top-level prop.');
+                return [];
+            }
             if (isBindingShaped(current)) {
                 nestedBinding(current, at(relative), sub, node);
                 return [];

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export declare const SPEC_VERSION = "0.7.0";
+export declare const SPEC_VERSION = "0.8.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** The semantic version of the spec documents in this package. */
-export const SPEC_VERSION = '0.7.0';
+export const SPEC_VERSION = '0.8.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texuli/spec",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The schema-first blueprint contract: JSON schemas, the catalog vocabulary, deterministic TypeScript and Kotlin projections, and the conformance harness.",
   "keywords": [
     "svelte",
@@ -50,6 +50,10 @@
     "./stream": {
       "types": "./dist/stream/index.d.ts",
       "default": "./dist/stream/index.js"
+    },
+    "./source": {
+      "types": "./dist/source.d.ts",
+      "default": "./dist/source.js"
     }
   },
   "files": [