@aventara/core 1.0.0-rc.0 → 1.0.0-rc.2

package/dist/compiler/create-requirements.projector.d.ts

@@ -0,0 +1,49 @@
+import type { AvAdapterModel } from "../adapters/adapter-model.js";
+import type { AvConfigLayerName } from "../config/config-layer.js";
+import type { AvCreateRequirements } from "../contracts/create-requirements.js";
+import type { AvContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** A field of a projection, as far as this reader needs it. */
+type ProjectedField = {
+    readonly kind: "scalar" | "relation";
+    readonly [member: string]: unknown;
+};
+/** A Resource of a projection, as far as this reader needs it. */
+type ProjectedResource = {
+    readonly fields: Readonly<Record<string, ProjectedField>>;
+    createRequirements?: AvCreateRequirements;
+};
+/**
+ * Sets every Resource's `createRequirements` in one layer's projection to the
+ * Adapter's statement as that layer sees it, and removes it where nothing is
+ * left. Reads the projection's final fields: its exposure, and the lifecycle
+ * its compute stages gave them.
+ */
+export declare function projectCreateRequirements(model: AvAdapterModel, resources: Readonly<Record<string, ProjectedResource>>): void;
+/** A Resource's operations, as far as this check reads them. */
+type ResourceWithOperations = ProjectedResource & {
+    readonly operations: Readonly<Record<string, unknown>>;
+};
+/**
+ * Refuses, for one layer, every create requirement its exposure leaves no
+ * caller able to satisfy while the layer still creates the Resource: a
+ * required field hidden or not writable on create, or a group whose relation is
+ * not writable and one of whose reference fields is neither writable nor filled
+ * by a `compute.create`. Reported only where the parent could still satisfy it,
+ * so a hiding is reported once, by the layer that hides it; a nested create is
+ * exempt from what its parent supplies. A group every other create can satisfy
+ * but a bulk record cannot is {@link checkBulkGroup}'s refusal.
+ *
+ * `universe` is the layer's model with its chained compute applied (it holds
+ * every field, hidden or not), `parent` what the layer starts from, `projection`
+ * its final view.
+ */
+export declare function checkHiddenRequirements(model: AvAdapterModel, layer: AvConfigLayerName, universe: Readonly<Record<string, ProjectedResource>>, parent: Readonly<Record<string, ProjectedResource>>, projection: Readonly<Record<string, ResourceWithOperations>>, diagnostics: AvContractCompilerDiagnostic[]): void;
+/**
+ * Every name in the Adapter's create requirements that is not what its member
+ * says: a `required` name that is no field of the Resource, a group whose first
+ * name is no to-one relation or whose others are no scalar fields, or a
+ * `parentSupplies` entry naming no relation to the Resource or a field the
+ * statement does not require. An Adapter defect, refused at construction.
+ */
+export declare function checkCreateRequirements(model: AvAdapterModel, diagnostics: AvContractCompilerDiagnostic[]): void;
+export {};

package/dist/compiler/create-requirements.projector.js

@@ -0,0 +1,423 @@
+import { advertisedDirectives, advertisedDirectivesAt, } from "../contracts/field.js";
+import { isOperationVariantAvailable, writeScopeOf, } from "../contracts/resource-operations.js";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function own(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function creatable(resource, name) {
+    const field = own(resource.fields, name);
+    const capabilities = isRecord(field?.capabilities)
+        ? field.capabilities
+        : undefined;
+    if (field === undefined || capabilities === undefined) {
+        return false;
+    }
+    return field.kind === "scalar"
+        ? capabilities.create !== undefined
+        : advertisedDirectives(capabilities.create) !== undefined;
+}
+function creatableAt(resource, name, scope) {
+    const field = own(resource.fields, name);
+    if (field?.kind !== "relation") {
+        return creatable(resource, name);
+    }
+    const capabilities = isRecord(field.capabilities)
+        ? field.capabilities
+        : undefined;
+    return (advertisedDirectivesAt(capabilities?.create, scope) !== undefined);
+}
+function computedOnCreate(resource, name) {
+    const field = own(resource.fields, name);
+    return (field?.kind === "scalar" &&
+        Array.isArray(field.lifecycle) &&
+        field.lifecycle.includes("COMPUTED_ON_CREATE"));
+}
+function projectOne(stated, resource, resources) {
+    const required = [];
+    const requireOnce = (name) => {
+        if (!required.includes(name)) {
+            required.push(name);
+        }
+    };
+    for (const name of stated.required ?? []) {
+        if (creatable(resource, name) && !computedOnCreate(resource, name)) {
+            requireOnce(name);
+        }
+    }
+    const oneOf = [];
+    for (const [relation, ...references] of stated.oneOf ?? []) {
+        const left = references.filter((name) => !computedOnCreate(resource, name));
+        const [first, ...rest] = left;
+        if (first === undefined) {
+            continue;
+        }
+        const relationWritable = creatable(resource, relation);
+        const referencesWritable = left.every((name) => creatable(resource, name));
+        if (relationWritable && referencesWritable) {
+            oneOf.push([relation, first, ...rest]);
+        }
+        else if (relationWritable) {
+            requireOnce(relation);
+        }
+        else if (referencesWritable) {
+            for (const name of left) {
+                requireOnce(name);
+            }
+        }
+    }
+    const named = new Set([...required, ...oneOf.flat()]);
+    const parentSupplies = {};
+    for (const [parent, byRelation] of Object.entries(stated.parentSupplies ?? {})) {
+        const parentResource = own(resources, parent);
+        if (parentResource === undefined) {
+            continue;
+        }
+        for (const [relation, members] of Object.entries(byRelation)) {
+            if (own(parentResource.fields, relation)?.kind !== "relation") {
+                continue;
+            }
+            const [first, ...rest] = members.filter((name) => named.has(name));
+            if (first !== undefined) {
+                parentSupplies[parent] ??= {};
+                parentSupplies[parent][relation] = [first, ...rest];
+            }
+        }
+    }
+    const [firstRequired, ...restRequired] = required;
+    const [firstGroup, ...restGroups] = oneOf;
+    if (firstRequired === undefined && firstGroup === undefined) {
+        return undefined;
+    }
+    return {
+        ...(firstRequired === undefined
+            ? {}
+            : { required: [firstRequired, ...restRequired] }),
+        ...(firstGroup === undefined ? {} : { oneOf: [firstGroup, ...restGroups] }),
+        ...(Object.keys(parentSupplies).length === 0 ? {} : { parentSupplies }),
+    };
+}
+export function projectCreateRequirements(model, resources) {
+    for (const [name, resource] of Object.entries(resources)) {
+        delete resource.createRequirements;
+        const stated = own(model.resources, name)?.createRequirements;
+        if (stated === undefined) {
+            continue;
+        }
+        const projected = projectOne(stated, resource, resources);
+        if (projected !== undefined) {
+            resource.createRequirements = projected;
+        }
+    }
+}
+const CREATING_DIRECTIVES = [
+    "$create",
+    "$connectOrCreate",
+    "$upsert",
+];
+const UPDATING_DIRECTIVES = [
+    "$update",
+    "$upsert",
+];
+function variantsOf(resource, families) {
+    const variants = [];
+    for (const family of families) {
+        const entry = own(resource.operations, family);
+        if (!isRecord(entry)) {
+            continue;
+        }
+        for (const [variant, availability] of Object.entries(entry)) {
+            if (isOperationVariantAvailable(availability)) {
+                variants.push(`${family}.${variant}`);
+            }
+        }
+    }
+    return variants;
+}
+function advertises(field, stage, directives) {
+    const capabilities = isRecord(field.capabilities)
+        ? field.capabilities
+        : undefined;
+    const advertised = advertisedDirectives(capabilities?.[stage]);
+    return advertised?.some((name) => directives.includes(name)) ?? false;
+}
+function createVariantsOf(resource) {
+    const variants = [];
+    for (const family of ["create", "upsert"]) {
+        const entry = own(resource.operations, family);
+        if (!isRecord(entry)) {
+            continue;
+        }
+        for (const [variant, availability] of Object.entries(entry)) {
+            if (isOperationVariantAvailable(availability)) {
+                variants.push({
+                    name: `${family}.${variant}`,
+                    scope: writeScopeOf(availability),
+                });
+            }
+        }
+    }
+    return variants;
+}
+function createPaths(resources) {
+    const created = new Set();
+    const updated = new Set();
+    for (const [name, resource] of Object.entries(resources)) {
+        if (variantsOf(resource, ["create", "upsert"]).length > 0) {
+            created.add(name);
+        }
+        if (variantsOf(resource, ["update", "upsert"]).length > 0) {
+            updated.add(name);
+        }
+    }
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [parent, resource] of Object.entries(resources)) {
+            for (const field of Object.values(resource.fields)) {
+                const target = field.target;
+                if (field.kind !== "relation" ||
+                    typeof target !== "string" ||
+                    own(resources, target) === undefined) {
+                    continue;
+                }
+                const reachesCreate = (created.has(parent) &&
+                    advertises(field, "create", CREATING_DIRECTIVES)) ||
+                    (updated.has(parent) &&
+                        advertises(field, "update", CREATING_DIRECTIVES));
+                const reachesUpdate = updated.has(parent) &&
+                    advertises(field, "update", UPDATING_DIRECTIVES);
+                if (reachesCreate && !created.has(target)) {
+                    created.add(target);
+                    grew = true;
+                }
+                if (reachesUpdate && !updated.has(target)) {
+                    updated.add(target);
+                    grew = true;
+                }
+            }
+        }
+    }
+    const paths = new Map();
+    const add = (name, path) => {
+        const list = paths.get(name) ?? [];
+        list.push(path);
+        paths.set(name, list);
+    };
+    for (const [name, resource] of Object.entries(resources)) {
+        const variants = createVariantsOf(resource);
+        if (variants.length > 0) {
+            add(name, { kind: "operation", variants });
+        }
+    }
+    for (const [parent, resource] of Object.entries(resources)) {
+        for (const [relation, field] of Object.entries(resource.fields)) {
+            const target = field.target;
+            if (field.kind !== "relation" || typeof target !== "string") {
+                continue;
+            }
+            if ((created.has(parent) &&
+                advertises(field, "create", CREATING_DIRECTIVES)) ||
+                (updated.has(parent) &&
+                    advertises(field, "update", CREATING_DIRECTIVES))) {
+                add(target, { kind: "nested", parent, relation });
+            }
+        }
+    }
+    return paths;
+}
+function pathLabel(path) {
+    return path.kind === "operation"
+        ? path.variants.map((variant) => variant.name).join(", ")
+        : `nested through "${path.parent}.${path.relation}"`;
+}
+function alternatives(names, joiner) {
+    const quoted = names.map((name) => `"${name}"`);
+    const last = quoted.pop();
+    return quoted.length === 0
+        ? (last ?? "")
+        : `${quoted.join(", ")} ${joiner} ${last}`;
+}
+function satisfiable(members, resource, universe, scope) {
+    const filled = (name) => creatable(resource, name) || computedOnCreate(universe, name);
+    const [relation, ...references] = members;
+    if (relation === undefined) {
+        return true;
+    }
+    return references.length === 0
+        ? filled(relation)
+        : creatableAt(resource, relation, scope) || references.every(filled);
+}
+function listed(names) {
+    const rest = [...names];
+    const last = rest.pop();
+    return rest.length === 0 ? (last ?? "") : `${rest.join(", ")} and ${last}`;
+}
+function memberPhrase(members, blocked) {
+    const [relation, ...references] = members;
+    if (references.length === 0) {
+        return `its required field "${relation}"`;
+    }
+    const fields = references.filter((name) => blocked.includes(name));
+    const parts = [
+        ...(relation !== undefined && blocked.includes(relation)
+            ? [`its required relation "${relation}"`]
+            : []),
+        ...(fields.length === 0
+            ? []
+            : [
+                `its reference ${fields.length === 1 ? "field" : "fields"} ${alternatives(fields, "and")}`,
+            ]),
+    ];
+    return parts.join(" and ");
+}
+function checkBulkGroup(layer, name, members, routes, resource, universe, parent, diagnostics) {
+    const [relation, ...references] = members;
+    if (relation === undefined || references.length === 0) {
+        return;
+    }
+    const positioned = new Map();
+    for (const route of routes) {
+        if (route.kind !== "operation") {
+            continue;
+        }
+        for (const variant of route.variants) {
+            if (variant.scope !== "nested") {
+                const list = positioned.get(variant.scope) ?? [];
+                list.push(variant.name);
+                positioned.set(variant.scope, list);
+            }
+        }
+    }
+    for (const [scope, variants] of positioned) {
+        if (satisfiable(members, resource, universe, scope) ||
+            !satisfiable(members, parent, universe, scope)) {
+            continue;
+        }
+        const blocked = references.filter((member) => !creatable(resource, member) && !computedOnCreate(universe, member));
+        const absent = blocked.filter((member) => own(resource.fields, member) === undefined);
+        const locked = blocked.filter((member) => !absent.includes(member));
+        const phrase = (fields) => `its reference ${fields.length === 1 ? "field" : "fields"} ${alternatives(fields, "and")}`;
+        const clauses = [
+            ...(absent.length === 0 ? [] : [`hides ${phrase(absent)}`]),
+            ...(locked.length === 0
+                ? []
+                : [`${phrase(locked)} cannot be written on create`]),
+        ];
+        const fields = alternatives(blocked, "and");
+        diagnostics.push({
+            code: "COMPILER_HIDDEN_REQUIRED_FIELD",
+            path: `${layer}.exemptions.resources.${name}.fields.${blocked[0] ?? relation}`,
+            message: `the ${layer} layer still creates resource "${name}" in bulk (${variants.join(", ")}) but ${clauses.join(", and ")}, which every bulk create must write: a bulk record cannot write the relation "${relation}"; expose ${fields}, give ${fields} a compute.create, or exempt ${listed(variants)}`,
+        });
+    }
+}
+export function checkHiddenRequirements(model, layer, universe, parent, projection, diagnostics) {
+    const paths = createPaths(projection);
+    for (const [name, resource] of Object.entries(projection)) {
+        const stated = own(model.resources, name)?.createRequirements;
+        const routes = paths.get(name) ?? [];
+        const universeResource = own(universe, name);
+        const parentResource = own(parent, name);
+        if (stated === undefined ||
+            routes.length === 0 ||
+            universeResource === undefined ||
+            parentResource === undefined) {
+            continue;
+        }
+        const items = [
+            ...(stated.required ?? []).map((field) => [field]),
+            ...(stated.oneOf ?? []),
+        ];
+        for (const members of items) {
+            if (satisfiable(members, resource, universeResource, "nested") ||
+                !satisfiable(members, parentResource, universeResource, "nested")) {
+                checkBulkGroup(layer, name, members, routes, resource, universeResource, parentResource, diagnostics);
+                continue;
+            }
+            const unsupplied = routes.filter((route) => route.kind === "operation" ||
+                !(stated.parentSupplies?.[route.parent]?.[route.relation] ?? []).some((member) => members.includes(member)));
+            if (unsupplied.length === 0) {
+                continue;
+            }
+            const [relation = "", ...references] = members;
+            const blocked = members.filter((member, position) => !creatable(resource, member) &&
+                (position === 0 || !computedOnCreate(universeResource, member)));
+            const absent = blocked.filter((member) => own(resource.fields, member) === undefined);
+            const locked = blocked.filter((member) => !absent.includes(member));
+            const clauses = [
+                ...(absent.length === 0
+                    ? []
+                    : [`hides ${memberPhrase(members, absent)}`]),
+                ...(locked.length === 0
+                    ? []
+                    : [`${memberPhrase(members, locked)} cannot be written on create`]),
+            ];
+            const blockedReferences = references.filter((member) => blocked.includes(member));
+            const expose = references.length === 0
+                ? `"${relation}"`
+                : blockedReferences.length === 1
+                    ? `"${relation}" or "${blockedReferences[0]}"`
+                    : `"${relation}", or all of ${alternatives(blockedReferences, "and")}`;
+            const compute = alternatives(references.length === 0 ? [relation] : blockedReferences, "and");
+            diagnostics.push({
+                code: "COMPILER_HIDDEN_REQUIRED_FIELD",
+                path: `${layer}.exemptions.resources.${name}.fields.${relation}`,
+                message: `the ${layer} layer still creates resource "${name}" (${unsupplied.map(pathLabel).join("; ")}) but ${clauses.join(", and ")}, which every create must write; expose ${expose}, give ${compute} a compute.create, or exempt the create operation`,
+            });
+        }
+    }
+}
+function misnamed(path, message) {
+    return { code: "COMPILER_UNKNOWN_FIELD", path, message };
+}
+export function checkCreateRequirements(model, diagnostics) {
+    for (const [name, resource] of Object.entries(model.resources)) {
+        const stated = resource.createRequirements;
+        if (stated === undefined) {
+            continue;
+        }
+        const path = `adapter.model.resources.${name}.createRequirements`;
+        const field = (fieldName) => own(resource.fields, fieldName);
+        (stated.required ?? []).forEach((fieldName, index) => {
+            if (field(fieldName) === undefined) {
+                diagnostics.push(misnamed(`${path}.required[${index}]`, `"${fieldName}" is not a field of resource "${name}"`));
+            }
+        });
+        (stated.oneOf ?? []).forEach((group, index) => {
+            group.forEach((fieldName, position) => {
+                const found = field(fieldName);
+                const fits = position === 0
+                    ? found?.kind === "relation" && found.cardinality === "one"
+                    : found?.kind === "scalar";
+                if (!fits) {
+                    diagnostics.push(misnamed(`${path}.oneOf[${index}][${position}]`, position === 0
+                        ? `"${fieldName}" is not a to-one relation of resource "${name}"`
+                        : `"${fieldName}" is not a scalar field of resource "${name}"`));
+                }
+            });
+        });
+        const named = new Set([
+            ...(stated.required ?? []),
+            ...(stated.oneOf ?? []).flat(),
+        ]);
+        for (const [parent, byRelation] of Object.entries(stated.parentSupplies ?? {})) {
+            for (const [relation, members] of Object.entries(byRelation)) {
+                const parentResource = own(model.resources, parent);
+                const edge = parentResource === undefined
+                    ? undefined
+                    : own(parentResource.fields, relation);
+                if (edge?.kind !== "relation" || edge.target !== name) {
+                    diagnostics.push(misnamed(`${path}.parentSupplies.${parent}.${relation}`, `"${parent}.${relation}" is not a relation to resource "${name}"`));
+                    continue;
+                }
+                members.forEach((member, index) => {
+                    if (!named.has(member)) {
+                        diagnostics.push(misnamed(`${path}.parentSupplies.${parent}.${relation}[${index}]`, `"${member}" is not a requirement of resource "${name}"`));
+                    }
+                });
+            }
+        }
+    }
+}

package/dist/compiler/field-validator.compiler.d.ts

@@ -0,0 +1,47 @@
+import type { ResolvedPipelineTree } from "../config/pipeline-tree.resolver.js";
+import type { AvContract } from "../contracts/contract.js";
+import type { AvFieldCheck } from "../contracts/field-check.js";
+import { type FieldCheckSubject } from "../runtime/field-check.evaluator.js";
+import type { AvContractCompilerDiagnostic } from "./contract-compiler-diagnostic.js";
+/** A field as the compiler holds it while it builds a projection. */
+type ProjectedField = Readonly<Record<string, unknown>> & {
+    readonly kind: "scalar" | "relation";
+};
+/** The fields of each Resource of a projection, by name. */
+type ProjectedResources = Readonly<Record<string, {
+    readonly fields: Readonly<Record<string, ProjectedField>>;
+}>>;
+/** What the runtime needs to judge one field's value against its validators. */
+export type CompiledFieldValidators = {
+    readonly checks: readonly AvFieldCheck[];
+    readonly subject: FieldCheckSubject | undefined;
+    readonly list: boolean;
+};
+/** One layer's compiled validators, by Resource and field. */
+export type FieldValidatorTable = Readonly<Record<string, Readonly<Record<string, CompiledFieldValidators>>>>;
+/**
+ * Checks the validators one layer wrote, at the paths it wrote them: on a scalar
+ * field that is not Json, each one built with `AvZ` and fitting the field's
+ * type. A name the model lacks is `checkResourceTree`'s to report.
+ */
+export declare function checkLayerValidators(resources: ProjectedResources, layer: string, tree: unknown, diagnostics: AvContractCompilerDiagnostic[]): void;
+/**
+ * The compiled validators of one origin: every check its pipeline tree holds for
+ * a field of `resources`, root's then overlay's. A check
+ * {@link checkLayerValidators} refused is left out (the compilation fails anyway).
+ */
+export declare function compileValidatorTable(resources: ProjectedResources, tree: ResolvedPipelineTree): FieldValidatorTable;
+/**
+ * Writes each field's compiled validators onto the field a projection exposes: a
+ * field the layer hides carries none into its Contract.
+ */
+export declare function applyValidators(resources: Readonly<Record<string, {
+    readonly fields: Record<string, Record<string, unknown>>;
+}>>, table: FieldValidatorTable): void;
+/** Binds a final Contract to its origin's compiled validators. Compiler only. */
+export declare function bindFieldValidators(contract: AvContract, table: FieldValidatorTable): void;
+/** Whether `contract`'s origin has any validator at all: a check, or a Json Shape. */
+export declare function hasFieldValidators(contract: AvContract): boolean;
+/** `resource`'s fields with validators under `contract`'s origin, in field order. */
+export declare function validatedFieldsOf(contract: AvContract, resource: string): Readonly<Record<string, CompiledFieldValidators>>;
+export {};