@astrale-os/kernel-dsl 0.2.0-beta.9 → 1.0.0-beta.1

package/dist/v1/schema/compatibility/meaning.js

@@ -1,605 +0,0 @@
-import { json } from '@astrale-os/kernel-dsl/value';
-import { Key, MethodKey, PropertyKey } from '../../addressing/index.js';
-import { compareDefinitionRefs, compareUnicode, definitionRefIndex, } from '../../addressing/ordering.js';
-import { isValueObject as isJsonObject } from '../../language/value/model/object.js';
-import { SCHEMA_ARRAY_KEYWORDS, SCHEMA_MAP_KEYWORDS, SCHEMA_SINGLE_KEYWORDS, } from '../../language/value/syntax/keywords.js';
-import { digestDomainSchemaBytes } from '../canonical/domain.digest.js';
-import { revisionOfDomainSchema } from '../canonical/revision.js';
-import { SchemaError, diagnostic } from '../diagnostic.js';
-import { knownDomainClosure, lookupForDomainClosure } from '../resolution/closure.js';
-import { resolve } from '../resolution/domain.js';
-import { collectCallableRefs, collectClassRefs, collectPolicyDefinitionRefs, collectValueDefinitionRefs, } from '../resolution/origins.js';
-import { validateDomainSchemaSemantics } from '../validation/domain.js';
-const VALUE_SCHEMA_ANNOTATIONS = new Set([
-    '$comment',
-    'contentEncoding',
-    'contentMediaType',
-    'contentSchema',
-    'default',
-    'deprecated',
-    'description',
-    'examples',
-    'format',
-    'readOnly',
-    'title',
-    'writeOnly',
-]);
-/**
- * Compare the exact V1 meaning one accepted Domain used from a retained dependency with a
- * candidate revision of that same dependency origin. This operation is pure and makes no
- * lifecycle-compatibility decision.
- */
-export function compareDependencyMeaning(dependent, target) {
-    resolve(dependent);
-    const closure = knownDomainClosure(dependent) ?? [];
-    const source = closure.find((candidate) => candidate.schema.origin === target.origin)?.schema;
-    if (source === undefined) {
-        throw new SchemaError([
-            diagnostic('DM_DEPENDENCY_NOT_RETAINED', '/target/origin', `Domain ${dependent.origin} was not admitted with a dependency at ${target.origin}.`),
-        ]);
-    }
-    const schemas = new Map([
-        [dependent.origin, dependent],
-        ...closure.map(({ schema: candidate }) => [candidate.origin, candidate]),
-    ]);
-    const sourceMeanings = collectDependencyMeanings(dependent, source.origin, schemas);
-    return compareSourceMeanings(source, target, sourceMeanings);
-}
-/** Compare one explicit non-empty source member surface and its reachable V1 meaning. */
-export function compareMemberMeaning(source, target, roots) {
-    if (source.origin !== target.origin) {
-        throw new SchemaError([
-            diagnostic('DM_MEMBER_ORIGIN_MISMATCH', '/target/origin', `Member comparison target ${target.origin} does not match source ${source.origin}.`),
-        ]);
-    }
-    if (!Array.isArray(roots) || roots.length === 0 || new Set(roots).size !== roots.length) {
-        throw new SchemaError([
-            diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', 'Member comparison roots must be one non-empty duplicate-free Key set.'),
-        ]);
-    }
-    resolve(source);
-    const closure = knownDomainClosure(source) ?? [];
-    const schemas = new Map([
-        [source.origin, source],
-        ...closure.map(({ schema: candidate }) => [candidate.origin, candidate]),
-    ]);
-    const coordinates = roots.map((key, index) => coordinateForKey(source, key, index));
-    const sourceMeanings = collectReachableMeanings(coordinates, source.origin, schemas);
-    return compareSourceMeanings(source, target, sourceMeanings);
-}
-function compareSourceMeanings(source, target, sourceMeanings) {
-    // Prove the candidate still has an exact accepted semantic context before comparing it.
-    resolve(target);
-    const footprint = Object.freeze([...sourceMeanings.keys()].sort(compareUnicode));
-    const changes = [];
-    const comparisonCoordinates = [];
-    for (const key of footprint) {
-        const sourceMeaning = sourceMeanings.get(key);
-        const targetMeaning = meaningForCoordinate(target, sourceMeaning.coordinate);
-        const targetFingerprint = targetMeaning === undefined ? undefined : fingerprintMeaning(targetMeaning);
-        comparisonCoordinates.push([
-            key,
-            sourceMeaning.fingerprint,
-            targetFingerprint ?? null,
-        ]);
-        if (targetFingerprint === undefined) {
-            changes.push(Object.freeze({
-                key,
-                kind: 'missing',
-                sourceFingerprint: sourceMeaning.fingerprint,
-            }));
-        }
-        else if (targetFingerprint !== sourceMeaning.fingerprint) {
-            changes.push(Object.freeze({
-                key,
-                kind: 'changed',
-                sourceFingerprint: sourceMeaning.fingerprint,
-                targetFingerprint,
-            }));
-        }
-    }
-    const sourceRevision = revisionOfDomainSchema(source);
-    const targetRevision = revisionOfDomainSchema(target);
-    const immutableChanges = Object.freeze(changes);
-    const fingerprint = fingerprintMeaning({
-        version: 1,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        coordinates: comparisonCoordinates,
-    });
-    return Object.freeze({
-        version: 1,
-        dependency: source.origin,
-        source: sourceRevision,
-        target: targetRevision,
-        footprint,
-        changes: immutableChanges,
-        fingerprint,
-    });
-}
-function collectDependencyMeanings(dependent, dependencyOrigin, schemas) {
-    return collectReachableMeanings(collectSchemaSemanticRefs(dependent).map(memberCoordinate), dependencyOrigin, schemas);
-}
-function collectReachableMeanings(roots, selectedOrigin, schemas) {
-    const meanings = new Map();
-    const pending = [];
-    const visited = new Set();
-    for (const coordinate of roots) {
-        if (coordinate.kind === 'member') {
-            pending.push(coordinate.ref);
-            continue;
-        }
-        const owner = schemas.get(Key.origin(coordinate.key));
-        const meaning = owner === undefined ? undefined : meaningForCoordinate(owner, coordinate);
-        if (owner === undefined || meaning === undefined) {
-            throw new SchemaError([
-                diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Member comparison root ${coordinate.key} does not exist in its source context.`, coordinate.key),
-            ]);
-        }
-        retainMeaning(meanings, selectedOrigin, coordinate, meaning);
-        collectCoordinateSemanticRefs(owner, coordinate, (candidate) => pending.push(requireMemberRef(candidate)));
-    }
-    for (let index = 0; index < pending.length; index += 1) {
-        const ref = pending[index];
-        const refIndex = definitionRefIndex(ref);
-        if (visited.has(refIndex))
-            continue;
-        visited.add(refIndex);
-        const owner = schemas.get(ref.origin);
-        if (owner === undefined) {
-            throw new SchemaError([
-                diagnostic('DM_DEPENDENCY_CONTEXT_INVALID', '', `Retained acceptance context cannot resolve ${keyForDefinitionRef(ref)}.`, keyForDefinitionRef(ref)),
-            ]);
-        }
-        const primary = memberCoordinate(ref);
-        const primaryMeaning = meaningForCoordinate(owner, primary);
-        if (primaryMeaning === undefined) {
-            throw new SchemaError([
-                diagnostic('DM_DEPENDENCY_CONTEXT_INVALID', '', `Retained acceptance context has no meaning for ${primary.key}.`, primary.key),
-            ]);
-        }
-        retainMeaning(meanings, selectedOrigin, primary, primaryMeaning);
-        collectMemberSemanticRefs(owner, ref, (candidate) => pending.push(requireMemberRef(candidate)));
-        if (!isDefinitionRef(ref))
-            continue;
-        const analysis = effectiveDefinition(owner, ref);
-        if (analysis === undefined)
-            continue;
-        collectEffectiveMeanings(analysis, selectedOrigin, meanings, (candidate) => pending.push(requireMemberRef(candidate)));
-    }
-    return meanings;
-}
-function collectCoordinateSemanticRefs(owner, coordinate, add) {
-    const analysis = effectiveDefinition(owner, coordinate.owner);
-    if (analysis === undefined)
-        return;
-    if (coordinate.kind === 'property') {
-        const field = analysis.properties.get(coordinate.key);
-        if (field !== undefined)
-            collectValueDefinitionRefs(semanticValueSchema(field.schema), add);
-        return;
-    }
-    const method = [...analysis.methods.values()].find((candidate) => MethodKey.of(candidate.owner, candidate.name) === coordinate.key);
-    if (method !== undefined)
-        collectCallableRefs(semanticMethod(method.declaration), add);
-}
-function collectEffectiveMeanings(analysis, dependencyOrigin, meanings, add) {
-    for (const field of analysis.properties.values()) {
-        const coordinate = propertyCoordinate(field.owner, field.name);
-        retainMeaning(meanings, dependencyOrigin, coordinate, propertyMeaning(field));
-        add(field.owner);
-        collectValueDefinitionRefs(semanticValueSchema(field.schema), add);
-    }
-    for (const method of analysis.methods.values()) {
-        const coordinate = methodCoordinate(method.owner, method.name);
-        retainMeaning(meanings, dependencyOrigin, coordinate, methodMeaning(method));
-        add(method.owner);
-        collectCallableRefs(semanticMethod(method.declaration), add);
-    }
-}
-function retainMeaning(meanings, dependencyOrigin, coordinate, meaning) {
-    if (Key.origin(coordinate.key) !== dependencyOrigin)
-        return;
-    const fingerprint = fingerprintMeaning(meaning);
-    const previous = meanings.get(coordinate.key);
-    if (previous !== undefined && previous.fingerprint !== fingerprint) {
-        throw new SchemaError([
-            diagnostic('DM_MEANING_INCONSISTENT', '', `Semantic coordinate ${coordinate.key} produced inconsistent effective meaning.`, coordinate.key),
-        ]);
-    }
-    meanings.set(coordinate.key, Object.freeze({ coordinate, fingerprint }));
-}
-function collectSchemaSemanticRefs(owner) {
-    const refs = new Map();
-    const add = (ref) => {
-        const member = requireMemberRef(ref);
-        refs.set(definitionRefIndex(member), member);
-    };
-    for (const declaration of Object.values(owner.classes)) {
-        collectClassRefs(semanticDefinition(declaration), add);
-    }
-    for (const declaration of Object.values(owner.functions)) {
-        collectCallableRefs(semanticFunction(declaration), add);
-    }
-    for (const declaration of Object.values(owner.policies)) {
-        collectPolicyDefinitionRefs(semanticPolicy(declaration), add);
-    }
-    for (const declaration of Object.values(owner.views)) {
-        if (declaration.target.kind === 'definition')
-            declaration.target.definitions.forEach(add);
-    }
-    for (const node of Object.values(owner.core.nodes))
-        add(node.class);
-    for (const edge of owner.core.edges) {
-        add(edge.class);
-        if (edge.source.kind !== 'domain')
-            add(edge.source);
-        if (edge.target.kind !== 'domain')
-            add(edge.target);
-    }
-    return [...refs.values()].sort(compareDefinitionRefs);
-}
-function collectMemberSemanticRefs(owner, ref, add) {
-    switch (ref.kind) {
-        case 'class': {
-            const declaration = owner.classes[ref.name];
-            if (declaration !== undefined) {
-                collectClassRefs(semanticDefinition(declaration), add);
-            }
-            return;
-        }
-        case 'function': {
-            const declaration = owner.functions[ref.name];
-            if (declaration !== undefined)
-                collectCallableRefs(semanticFunction(declaration), add);
-            return;
-        }
-        case 'policy': {
-            const declaration = owner.policies[ref.name];
-            if (declaration !== undefined) {
-                collectPolicyDefinitionRefs(semanticPolicy(declaration), add);
-            }
-            return;
-        }
-        case 'view': {
-            const declaration = owner.views[ref.name];
-            if (declaration?.target.kind === 'definition')
-                declaration.target.definitions.forEach(add);
-            return;
-        }
-        case 'core': {
-            const node = owner.core.nodes[ref.name];
-            if (node === undefined)
-                return;
-            add(node.class);
-            for (const edge of incidentCoreEdges(owner, ref.name)) {
-                add(edge.class);
-                if (edge.source.kind !== 'domain')
-                    add(edge.source);
-                if (edge.target.kind !== 'domain')
-                    add(edge.target);
-            }
-        }
-    }
-}
-function meaningForCoordinate(owner, coordinate) {
-    if (Key.origin(coordinate.key) !== owner.origin)
-        return undefined;
-    if (coordinate.kind === 'member')
-        return memberMeaning(owner, coordinate.ref);
-    const analysis = effectiveDefinition(owner, coordinate.owner);
-    if (analysis === undefined)
-        return undefined;
-    if (coordinate.kind === 'property') {
-        const field = analysis.properties.get(coordinate.key);
-        return field === undefined ? undefined : propertyMeaning(field);
-    }
-    const method = [...analysis.methods.values()].find((candidate) => MethodKey.of(candidate.owner, candidate.name) === coordinate.key);
-    return method === undefined ? undefined : methodMeaning(method);
-}
-function memberMeaning(owner, ref) {
-    if (ref.origin !== owner.origin)
-        return undefined;
-    switch (ref.kind) {
-        case 'class':
-            return definitionMeaning(owner, ref);
-        case 'function': {
-            const declaration = owner.functions[ref.name];
-            return declaration === undefined
-                ? undefined
-                : { kind: ref.kind, declaration: semanticFunction(declaration) };
-        }
-        case 'policy': {
-            const declaration = owner.policies[ref.name];
-            return declaration === undefined
-                ? undefined
-                : { kind: ref.kind, declaration: semanticPolicy(declaration) };
-        }
-        case 'view': {
-            const declaration = owner.views[ref.name];
-            return declaration === undefined
-                ? undefined
-                : { kind: ref.kind, declaration: semanticView(declaration) };
-        }
-        case 'core': {
-            const node = owner.core.nodes[ref.name];
-            return node === undefined
-                ? undefined
-                : {
-                    kind: ref.kind,
-                    node,
-                    edges: incidentCoreEdges(owner, ref.name),
-                };
-        }
-    }
-}
-function definitionMeaning(owner, ref) {
-    const declaration = owner.classes[ref.name];
-    const effective = effectiveDefinition(owner, ref);
-    if (declaration === undefined || effective === undefined || ref.origin !== owner.origin)
-        return undefined;
-    return {
-        kind: ref.kind,
-        declaration: semanticDefinition(declaration),
-        effective: {
-            properties: [...effective.properties.keys()].sort(compareUnicode),
-            methods: [...effective.methods.values()]
-                .map((method) => MethodKey.of(method.owner, method.name))
-                .sort(compareUnicode),
-            ...(effective.data === undefined
-                ? {}
-                : {
-                    data: {
-                        owner: keyForDefinitionRef(effective.data.owner),
-                        declaration: effective.data.declaration,
-                    },
-                }),
-        },
-    };
-}
-function effectiveDefinition(owner, ref) {
-    const validation = validateDomainSchemaSemantics(owner, lookupForDomainClosure(owner));
-    if (validation.diagnostics.length > 0)
-        return undefined;
-    return validation.analysis.definitions.get(definitionRefIndex(ref));
-}
-function propertyMeaning(field) {
-    return {
-        kind: 'property',
-        owner: keyForDefinitionRef(field.owner),
-        name: field.name,
-        schema: semanticValueSchema(field.schema),
-        required: field.required,
-        visibility: field.visibility,
-    };
-}
-function methodMeaning(method) {
-    return {
-        kind: 'method',
-        owner: keyForDefinitionRef(method.owner),
-        name: method.name,
-        declaration: semanticMethod(method.declaration),
-    };
-}
-function semanticDefinition(declaration) {
-    const { description: _description, ...rest } = declaration;
-    const semantic = {
-        ...rest,
-        properties: Object.fromEntries(Object.entries(declaration.properties).map(([name, property]) => [
-            name,
-            {
-                ...property,
-                schema: semanticValueSchema(property.schema),
-            },
-        ])),
-    };
-    if ('methods' in declaration) {
-        semantic.methods = Object.fromEntries(Object.entries(declaration.methods).map(([name, method]) => [name, semanticMethod(method)]));
-    }
-    return semantic;
-}
-function semanticFunction(declaration) {
-    const { description: _description, ...rest } = declaration;
-    return {
-        ...rest,
-        input: semanticValueSchema(declaration.input),
-        output: semanticOutput(declaration.output),
-    };
-}
-function semanticMethod(declaration) {
-    const { description: _description, ...rest } = declaration;
-    return {
-        ...rest,
-        input: semanticValueSchema(declaration.input),
-        output: semanticOutput(declaration.output),
-    };
-}
-function semanticOutput(output) {
-    switch (output.mode) {
-        case 'value':
-            return { mode: 'value', schema: semanticValueSchema(output.schema) };
-        case 'stream':
-            return { mode: 'stream', item: semanticValueSchema(output.item) };
-        case 'binary':
-            return { mode: 'binary' };
-    }
-}
-function semanticPolicy(declaration) {
-    const { description: _description, ...semantic } = declaration;
-    return semantic;
-}
-function semanticView(declaration) {
-    const { description: _description, ...semantic } = declaration;
-    return semantic;
-}
-function semanticValueSchema(value) {
-    if (typeof value === 'boolean')
-        return value;
-    const semantic = {};
-    for (const [keyword, entry] of Object.entries(value)) {
-        if (VALUE_SCHEMA_ANNOTATIONS.has(keyword))
-            continue;
-        if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(entry)) {
-            semantic[keyword] = semanticValueSchema(entry);
-        }
-        else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(entry)) {
-            semantic[keyword] = entry.map((item) => isJsonSchema(item) ? semanticValueSchema(item) : item);
-        }
-        else if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(entry)) {
-            semantic[keyword] = Object.fromEntries(Object.entries(entry).map(([name, item]) => [
-                name,
-                isJsonSchema(item) ? semanticValueSchema(item) : item,
-            ]));
-        }
-        else {
-            semantic[keyword] = entry;
-        }
-    }
-    return semantic;
-}
-function coordinateForKey(source, input, index) {
-    let key;
-    try {
-        key = Key(input);
-    }
-    catch {
-        return invalidMemberRoot(input, index, 'is not a canonical semantic Key');
-    }
-    if (Key.origin(key) !== source.origin) {
-        return invalidMemberRoot(key, index, `belongs to ${Key.origin(key)}, not source ${source.origin}`);
-    }
-    const reference = keyReference(key);
-    let coordinate;
-    if ((reference.member === 'property' || reference.member === 'method') &&
-        reference.ownerKind === 'class' &&
-        reference.ownerName !== undefined) {
-        const owner = definitionRefFor(source, reference.ownerKind, reference.ownerName);
-        if (owner === undefined) {
-            return invalidMemberRoot(key, index, 'has no exact owning Definition');
-        }
-        coordinate =
-            reference.member === 'property'
-                ? propertyCoordinate(owner, reference.name)
-                : methodCoordinate(owner, reference.name);
-    }
-    else if (reference.kind !== 'core') {
-        const member = memberRefFor(source, {
-            origin: source.origin,
-            kind: reference.kind,
-            name: reference.name,
-        });
-        if (member === undefined)
-            return invalidMemberRoot(key, index, 'does not exist in the source');
-        coordinate = memberCoordinate(member);
-    }
-    else {
-        coordinate = memberCoordinate({
-            origin: source.origin,
-            kind: 'core',
-            name: reference.name,
-        });
-    }
-    if (meaningForCoordinate(source, coordinate) === undefined) {
-        return invalidMemberRoot(key, index, 'does not exist in the source');
-    }
-    return coordinate;
-}
-function memberRefFor(source, ref) {
-    const name = ref.name;
-    const owner = definitionRefFor(source, ref.kind, name);
-    if (owner !== undefined)
-        return owner;
-    switch (ref.kind) {
-        case 'function':
-            return source.functions[name] === undefined
-                ? undefined
-                : { origin: source.origin, kind: 'function', name };
-        case 'policy':
-            return source.policies[name] === undefined
-                ? undefined
-                : { origin: source.origin, kind: 'policy', name };
-        case 'view':
-            return source.views[name] === undefined
-                ? undefined
-                : { origin: source.origin, kind: 'view', name };
-        default:
-            return undefined;
-    }
-}
-function definitionRefFor(source, namespace, name) {
-    if (namespace === 'class') {
-        return source.classes[name] === undefined
-            ? undefined
-            : { origin: source.origin, kind: 'class', name };
-    }
-    return undefined;
-}
-function invalidMemberRoot(key, index, reason) {
-    throw new SchemaError([
-        diagnostic('DM_MEMBER_ROOT_INVALID', `/roots/${index}`, `Member comparison root ${JSON.stringify(key)} ${reason}.`, typeof key === 'string' ? key : undefined),
-    ]);
-}
-function memberCoordinate(ref) {
-    return Object.freeze({ kind: 'member', key: keyForDefinitionRef(ref), ref });
-}
-function propertyCoordinate(owner, name) {
-    return Object.freeze({ kind: 'property', key: PropertyKey.of(owner, name), owner, name });
-}
-function methodCoordinate(owner, name) {
-    return Object.freeze({ kind: 'method', key: MethodKey.of(owner, name), owner, name });
-}
-function keyForDefinitionRef(ref) {
-    return ref.kind === 'core'
-        ? Key.of(ref)
-        : Key.of(ref);
-}
-function keyReference(key) {
-    const semantic = key.slice(key.indexOf(':') + 1);
-    const parts = semantic.split('.');
-    if (parts[0] === 'core' && parts.length === 2) {
-        return { kind: 'core', name: parts[1] };
-    }
-    if (parts.length === 2) {
-        return { kind: parts[0], name: parts[1] };
-    }
-    if (parts.length === 4 &&
-        parts[0] === 'class' &&
-        (parts[2] === 'property' || parts[2] === 'method')) {
-        return {
-            kind: 'class',
-            name: parts[3],
-            member: parts[2],
-            ownerKind: 'class',
-            ownerName: parts[1],
-        };
-    }
-    throw new SchemaError([
-        diagnostic('DM_MEMBER_ROOT_INVALID', '/roots', `Key ${key} has no supported V1 shape.`, key),
-    ]);
-}
-function incidentCoreEdges(owner, name) {
-    return owner.core.edges.filter((edge) => (edge.source.kind === 'core' && edge.source.name === name) ||
-        (edge.target.kind === 'core' && edge.target.name === name));
-}
-function fingerprintMeaning(value) {
-    return digestDomainSchemaBytes(json.encode(value));
-}
-function isDefinitionRef(ref) {
-    return ref.kind === 'class';
-}
-function requireMemberRef(ref) {
-    switch (ref.kind) {
-        case 'class':
-        case 'function':
-        case 'policy':
-        case 'view':
-            return ref;
-        case 'core':
-            return ref;
-    }
-    return ref;
-}
-function isJsonSchema(value) {
-    return typeof value === 'boolean' || isJsonObject(value);
-}