@yoyoboot/yoyo-admin-schema 10.5.5

package/dist/action-contract.d.ts

@@ -0,0 +1,50 @@
+import type { YoyoSchemaDiagnostic } from './diagnostics.js';
+export declare const YOYO_ACTION_CONTRACT_SCHEMA_VERSION = "1.0.0";
+export declare const YOYO_ACTION_CONTRACT_OPERATIONS: readonly ["create", "update", "setEnabled", "softDelete"];
+export type YoyoActionContractOperation = typeof YOYO_ACTION_CONTRACT_OPERATIONS[number];
+export declare const YOYO_ACTION_CONCURRENCY_POLICIES: readonly ["none", "required"];
+export type YoyoActionConcurrencyPolicy = typeof YOYO_ACTION_CONCURRENCY_POLICIES[number];
+export interface YoyoActionContract {
+    actionKey: string;
+    operation: YoyoActionContractOperation;
+    /** Generated backend/OpenAPI operation reference for create/update validation. */
+    validationOperationId?: string | null;
+    permission?: string | null;
+    feature?: string | null;
+    concurrencyPolicy: YoyoActionConcurrencyPolicy;
+    sourceModule: string;
+    schemaVersion: string;
+    generatorVersion: string;
+    sourceHash: string;
+    generatedCommand: string;
+}
+export interface YoyoActionContractCatalog {
+    schemaVersion: string;
+    generator: string;
+    generatorVersion: string;
+    sourceHash: string;
+    generatedAt: string;
+    generatedBy: string;
+    generatedCommand: string;
+    actions: readonly YoyoActionContract[];
+}
+export type YoyoActionContractManifest = Omit<YoyoActionContractCatalog, 'actions' | 'generatedAt'>;
+export interface YoyoLinkedActionContract extends YoyoActionContract {
+    catalogSchemaVersion: string;
+    catalogSourceHash: string;
+}
+export interface YoyoActionContractCapabilityRegistry {
+    permissions?: readonly string[];
+    features?: readonly string[];
+}
+export interface YoyoActionContractSnapshot {
+    readonly catalog: YoyoActionContractCatalog;
+    readonly manifest: YoyoActionContractManifest;
+}
+export declare function operationForYoyoActionKind(kind: string): YoyoActionContractOperation | undefined;
+export declare function isYoyoMutationActionKind(kind: string): boolean;
+export declare function linkYoyoActionContract(catalog: YoyoActionContractCatalog, actionKey: string): YoyoLinkedActionContract | undefined;
+export declare function validateYoyoActionContractCatalog(catalog: YoyoActionContractCatalog, capabilities?: YoyoActionContractCapabilityRegistry): readonly YoyoSchemaDiagnostic[];
+export declare function isYoyoActionContractSnapshotCompatible(linked: YoyoLinkedActionContract, catalog: YoyoActionContractCatalog): boolean;
+export declare function diagnoseYoyoActionContractSnapshot(linked: YoyoLinkedActionContract | undefined, catalog: YoyoActionContractCatalog | undefined, path?: string): readonly YoyoSchemaDiagnostic[];
+//# sourceMappingURL=action-contract.d.ts.map

package/dist/action-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-contract.d.ts","sourceRoot":"","sources":["../src/action-contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAE5D,eAAO,MAAM,mCAAmC,UAAU,CAAA;AAC1D,eAAO,MAAM,+BAA+B,2DAA4D,CAAA;AACxG,MAAM,MAAM,2BAA2B,GAAG,OAAO,+BAA+B,CAAC,MAAM,CAAC,CAAA;AAExF,eAAO,MAAM,gCAAgC,+BAAgC,CAAA;AAC7E,MAAM,MAAM,2BAA2B,GAAG,OAAO,gCAAgC,CAAC,MAAM,CAAC,CAAA;AAEzF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,2BAA2B,CAAA;IACtC,kFAAkF;IAClF,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,iBAAiB,EAAE,2BAA2B,CAAA;IAC9C,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;IACxB,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAA;CACvC;AAED,MAAM,MAAM,0BAA0B,GAAG,IAAI,CAAC,yBAAyB,EAAE,SAAS,GAAG,aAAa,CAAC,CAAA;AAEnG,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,oBAAoB,EAAE,MAAM,CAAA;IAC5B,iBAAiB,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,oCAAoC;IACnD,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAA;CAC9C;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,2BAA2B,GAAG,SAAS,CAiBhG;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,yBAAyB,EAClC,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,SAAS,CAStC;AAED,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,yBAAyB,EAClC,YAAY,GAAE,oCAAyC,GACtD,SAAS,oBAAoB,EAAE,CAsHjC;AAED,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,wBAAwB,EAChC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAeT;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,OAAO,EAAE,yBAAyB,GAAG,SAAS,EAC9C,IAAI,SAAmB,GACtB,SAAS,oBAAoB,EAAE,CAsBjC"}

package/dist/action-contract.js

@@ -0,0 +1,185 @@
+export const YOYO_ACTION_CONTRACT_SCHEMA_VERSION = '1.0.0';
+export const YOYO_ACTION_CONTRACT_OPERATIONS = ['create', 'update', 'setEnabled', 'softDelete'];
+export const YOYO_ACTION_CONCURRENCY_POLICIES = ['none', 'required'];
+export function operationForYoyoActionKind(kind) {
+    switch (kind) {
+        case 'create':
+            return 'create';
+        case 'edit':
+        case 'addChild':
+        case 'updateChild':
+        case 'removeChild':
+        case 'replaceRoles':
+            return 'update';
+        case 'disable':
+            return 'setEnabled';
+        case 'delete':
+            return 'softDelete';
+        default:
+            return undefined;
+    }
+}
+export function isYoyoMutationActionKind(kind) {
+    return operationForYoyoActionKind(kind) !== undefined;
+}
+export function linkYoyoActionContract(catalog, actionKey) {
+    const contract = catalog.actions.find((item) => item.actionKey === actionKey);
+    if (!contract)
+        return undefined;
+    return {
+        ...contract,
+        catalogSchemaVersion: catalog.schemaVersion,
+        catalogSourceHash: catalog.sourceHash,
+    };
+}
+export function validateYoyoActionContractCatalog(catalog, capabilities = {}) {
+    const diagnostics = [];
+    const keys = new Set();
+    const allowedContractKeys = new Set([
+        'actionKey',
+        'operation',
+        'validationOperationId',
+        'permission',
+        'feature',
+        'concurrencyPolicy',
+        'sourceModule',
+        'schemaVersion',
+        'generatorVersion',
+        'sourceHash',
+        'generatedCommand',
+    ]);
+    if (!catalog.schemaVersion || !catalog.generator || !catalog.generatorVersion || !catalog.sourceHash || !catalog.generatedBy || !catalog.generatedCommand) {
+        diagnostics.push({
+            code: 'YACT008',
+            path: 'catalog',
+            severity: 'blocking',
+            guidance: 'Regenerate the action contract catalog with complete provenance metadata.',
+            message: 'Action contract catalog provenance is incomplete.',
+        });
+    }
+    if (catalog.schemaVersion !== YOYO_ACTION_CONTRACT_SCHEMA_VERSION) {
+        diagnostics.push({
+            code: 'YACT005',
+            path: 'catalog.schemaVersion',
+            severity: 'blocking',
+            guidance: `Regenerate the catalog with schemaVersion ${YOYO_ACTION_CONTRACT_SCHEMA_VERSION}.`,
+            message: `Action contract catalog schemaVersion '${catalog.schemaVersion}' is incompatible.`,
+        });
+    }
+    for (const [index, contract] of catalog.actions.entries()) {
+        const path = `actionContracts.actions[${index}]`;
+        if (keys.has(contract.actionKey)) {
+            diagnostics.push({
+                code: 'YACT008',
+                path: `${path}.actionKey`,
+                severity: 'blocking',
+                guidance: 'Use one feature-scoped actionKey per backend action contract.',
+                message: `Action contract '${contract.actionKey}' is duplicated.`,
+            });
+        }
+        keys.add(contract.actionKey);
+        for (const key of Object.keys(contract)) {
+            if (!allowedContractKeys.has(key)) {
+                diagnostics.push({
+                    code: 'YACT010',
+                    path: `${path}.${key}`,
+                    severity: 'blocking',
+                    guidance: 'Keep grants, DTO fields, tokens and runtime state outside the static action contract catalog.',
+                    message: `Action contract contains unsupported field '${key}'.`,
+                });
+            }
+        }
+        if (!contract.actionKey || !contract.sourceModule || !contract.schemaVersion || !contract.generatorVersion || !contract.sourceHash || !contract.generatedCommand) {
+            diagnostics.push({
+                code: 'YACT008',
+                path,
+                severity: 'blocking',
+                guidance: 'Regenerate the action contract with a complete source and generator provenance.',
+                message: `Action contract '${contract.actionKey || '<unknown>'}' has incomplete provenance.`,
+            });
+        }
+        if (!YOYO_ACTION_CONTRACT_OPERATIONS.includes(contract.operation)) {
+            diagnostics.push({
+                code: 'YACT008',
+                path: `${path}.operation`,
+                severity: 'blocking',
+                guidance: 'Use create, update, setEnabled or softDelete.',
+                message: `Action contract operation '${String(contract.operation)}' is invalid.`,
+            });
+        }
+        if (!YOYO_ACTION_CONCURRENCY_POLICIES.includes(contract.concurrencyPolicy)) {
+            diagnostics.push({
+                code: 'YACT008',
+                path: `${path}.concurrencyPolicy`,
+                severity: 'blocking',
+                guidance: 'Declare concurrencyPolicy explicitly as none or required.',
+                message: `Action contract '${contract.actionKey}' has no valid concurrency policy.`,
+            });
+        }
+        if (contract.operation === 'create' && contract.concurrencyPolicy !== 'none') {
+            diagnostics.push({
+                code: 'YACT009',
+                path: `${path}.concurrencyPolicy`,
+                severity: 'blocking',
+                guidance: 'Create actions must explicitly declare concurrencyPolicy: none.',
+                message: `Create action '${contract.actionKey}' cannot require optimistic concurrency.`,
+            });
+        }
+        if (contract.permission && capabilities.permissions && !capabilities.permissions.includes(contract.permission)) {
+            diagnostics.push({
+                code: 'YACT006',
+                path: `${path}.permission`,
+                severity: 'blocking',
+                guidance: 'Register the permission in the capability catalog before linking the action contract.',
+                message: `Permission '${contract.permission}' is not registered.`,
+            });
+        }
+        if (contract.feature && capabilities.features && !capabilities.features.includes(contract.feature)) {
+            diagnostics.push({
+                code: 'YACT006',
+                path: `${path}.feature`,
+                severity: 'blocking',
+                guidance: 'Register the feature in the capability catalog before linking the action contract.',
+                message: `Feature '${contract.feature}' is not registered.`,
+            });
+        }
+    }
+    return diagnostics;
+}
+export function isYoyoActionContractSnapshotCompatible(linked, catalog) {
+    const current = linkYoyoActionContract(catalog, linked.actionKey);
+    return Boolean(current)
+        && current.operation === linked.operation
+        && current.validationOperationId === linked.validationOperationId
+        && current.permission === linked.permission
+        && current.feature === linked.feature
+        && current.concurrencyPolicy === linked.concurrencyPolicy
+        && current.sourceModule === linked.sourceModule
+        && current.schemaVersion === linked.schemaVersion
+        && current.generatorVersion === linked.generatorVersion
+        && current.sourceHash === linked.sourceHash
+        && current.generatedCommand === linked.generatedCommand
+        && current.catalogSchemaVersion === linked.catalogSchemaVersion
+        && current.catalogSourceHash === linked.catalogSourceHash;
+}
+export function diagnoseYoyoActionContractSnapshot(linked, catalog, path = 'actionContract') {
+    if (!linked || !catalog) {
+        return [{
+                code: 'YACT011',
+                path,
+                severity: 'blocking',
+                guidance: 'Bind the mutation to the current generated action-contract catalog before calling a datasource.',
+                message: 'The mutation action contract snapshot is unavailable.',
+            }];
+    }
+    if (!isYoyoActionContractSnapshotCompatible(linked, catalog)) {
+        return [{
+                code: 'YACT011',
+                path,
+                severity: 'blocking',
+                guidance: 'Regenerate and bind the same action-contract catalog snapshot used to compile the page.',
+                message: `Action contract '${linked.actionKey}' is stale or incompatible with the current catalog snapshot.`,
+            }];
+    }
+    return [];
+}

package/dist/action-registry.d.ts

@@ -0,0 +1,12 @@
+export interface YoyoActionDefinition {
+    key: string;
+}
+export interface YoyoActionRegistry {
+    has(key: string): boolean;
+    keys(): readonly string[];
+    resolve(key: string): YoyoActionDefinition;
+}
+export declare const yoyoV1ActionDefinitions: readonly YoyoActionDefinition[];
+export declare const yoyoV1ActionRegistry: YoyoActionRegistry;
+export declare function createYoyoActionRegistry(definitions: readonly YoyoActionDefinition[]): YoyoActionRegistry;
+//# sourceMappingURL=action-registry.d.ts.map

package/dist/action-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry.d.ts","sourceRoot":"","sources":["../src/action-registry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,IAAI,IAAI,SAAS,MAAM,EAAE,CAAA;IACzB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAAA;CAC3C;AAED,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAA8D,CAAA;AACjI,eAAO,MAAM,oBAAoB,oBAAoD,CAAA;AAErF,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,SAAS,oBAAoB,EAAE,GAAG,kBAAkB,CAiBzG"}

package/dist/action-registry.js

@@ -0,0 +1,23 @@
+import { YOYO_ACTION_KINDS } from './types.js';
+export const yoyoV1ActionDefinitions = YOYO_ACTION_KINDS.map((key) => ({ key }));
+export const yoyoV1ActionRegistry = createYoyoActionRegistry(yoyoV1ActionDefinitions);
+export function createYoyoActionRegistry(definitions) {
+    const entries = new Map();
+    for (const definition of definitions) {
+        if (!definition.key.trim())
+            throw new Error('Action registry does not accept an empty key.');
+        if (entries.has(definition.key))
+            throw new Error(`Action '${definition.key}' is already registered.`);
+        entries.set(definition.key, definition);
+    }
+    return {
+        has: (key) => entries.has(key),
+        keys: () => [...entries.keys()].sort(),
+        resolve: (key) => {
+            const definition = entries.get(key);
+            if (!definition)
+                throw new Error(`Action '${key}' is not registered.`);
+            return definition;
+        },
+    };
+}

package/dist/compiler.d.ts

@@ -0,0 +1,17 @@
+import { type YoyoPageIR, type YoyoPageSchema, type YoyoPageKind, type YoyoSchemaCompilerOptions, type YoyoSchemaDiffEntry, type YoyoSchemaUsageReport } from './types.js';
+import { type YoyoSchemaDiagnostic } from './diagnostics.js';
+export interface YoyoCompileResult {
+    ir: YoyoPageIR;
+    diagnostics: readonly YoyoSchemaDiagnostic[];
+    usageReport: YoyoSchemaUsageReport;
+}
+/**
+ * Declares a canonical V1 page schema while retaining its literal page kind.
+ * The historical name remains the single public authoring entry point.
+ */
+export declare function defineYoyoQueryPage<const TPage extends YoyoPageSchema>(page: TPage): TPage;
+export declare function compileYoyoPageSchema(input: unknown, options?: YoyoSchemaCompilerOptions): YoyoCompileResult;
+export declare function isPageKindAllowed(value: string): value is YoyoPageKind;
+export declare function diffYoyoPageIR(before: YoyoPageIR, after: YoyoPageIR): readonly YoyoSchemaDiffEntry[];
+export declare function formatYoyoSchemaDiff(entries: readonly YoyoSchemaDiffEntry[]): string;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,YAAY,EAKjB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EAExB,KAAK,qBAAqB,EAI3B,MAAM,YAAY,CAAA;AAiBnB,OAAO,EAA6B,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAkQvF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,UAAU,CAAA;IACd,WAAW,EAAE,SAAS,oBAAoB,EAAE,CAAA;IAC5C,WAAW,EAAE,qBAAqB,CAAA;CACnC;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,KAAK,SAAS,cAAc,EAAE,IAAI,EAAE,KAAK,GAAG,KAAK,CAE1F;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,yBAA8B,GACtC,iBAAiB,CAqgBnB;AAwDD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,YAAY,CAEtE;AAkSD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,UAAU,GAChB,SAAS,mBAAmB,EAAE,CA0BhC;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,UAY3E"}