@astrale-os/kernel-dsl 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/v1/language/policy/analysis/typing.js

@@ -0,0 +1,338 @@
+import { Key } from '../../../addressing/index.js';
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { branchesOf, branchProduct, capBranches, targetMode, termKey, UnionFind, } from './branches.js';
+import { MAX_REPEAT } from './budgets.js';
+import { admittedCheckClasses } from './checks.js';
+export class PolicyTyping {
+    scope;
+    // Expanded branches of each named Policy, cached by node identity. A Policy's expansion is reused
+    // across every composition path that reaches it (and across every use site and object contract,
+    // none of which the expansion depends on), so a shared-child composition DAG is expanded in work
+    // linear in the number of Policies instead of enumerating every path. The expansion result is
+    // independent of the reaching path up to the opaque term-namespace labels, which only ever
+    // disambiguate variables within one branch and leave targetMode and branch typing unchanged.
+    // Two occurrences of one Policy in a branch share labels only when a Policy reaches it by two
+    // paths; for that to merge distinct variables, the Policy expands deeper than MAX_PATTERN_DEPTH.
+    #expansions = new Map();
+    constructor(scope) {
+        this.scope = scope;
+    }
+    /** The normalized branches of a named Policy, `undefined` when it does not expand. */
+    expandedBranches(name, namespace) {
+        return this.#expandedBranches(name, new Set(), namespace);
+    }
+    policyAccepts(name, object) {
+        return this.#policyBranchTyping(name, object)?.every(Boolean) ?? false;
+    }
+    /** Whether the Policy accepts every concrete source and target pair the Edge Class accepts. */
+    policyAcceptsEdgeClass(name, declaration) {
+        const endpoints = declaration.orientation === 'directed'
+            ? [declaration.endpoints.source, declaration.endpoints.target]
+            : declaration.endpoints;
+        const sources = this.#concreteEndpointClasses(endpoints[0].accepts);
+        const targets = this.#concreteEndpointClasses(endpoints[1].accepts);
+        return sources.every((source) => targets.every((target) => this.#policyAcceptsEdge(name, { kind: 'exact', ref: source }, { kind: 'exact', ref: target })));
+    }
+    /**
+     * How a check of the Policy types against each contract of its object, `undefined` when the
+     * Policy does not expand or one of its branches is typed for no contract.
+     */
+    checkLeafClasses(name, contracts) {
+        const typings = new Map(contracts.map((contract) => [
+            contract.kind === 'exact' ? Key.of(contract.ref) : 'default',
+            this.#policyBranchTyping(name, contract),
+        ]));
+        const admitted = admittedCheckClasses(typings);
+        return admitted === undefined ? undefined : { accepted: [...typings.keys()], admitted };
+    }
+    endpointsOverlap(left, right) {
+        const seed = [{ kind: 'open', requirements: [] }];
+        const afterLeft = this.#applyEndpoint(seed, left);
+        return this.#applyEndpoint(afterLeft, right).length > 0;
+    }
+    branchIsTyped(branch, use) {
+        if (targetMode(branch) !== use.kind)
+            return false;
+        const alternatives = edgeAlternatives(branch.edges, this);
+        return alternatives.some((variants) => this.#constraintsAreSatisfiable(branch, variants, use));
+    }
+    /** Whether each normalized branch of the Policy is typed for an object of this contract. */
+    #policyBranchTyping(name, object) {
+        const branches = this.#expandedBranches(name, new Set(), `$use:${name}`);
+        const use = { kind: 'object', object };
+        return branches?.map((branch) => this.branchIsTyped(branch, use));
+    }
+    #policyAcceptsEdge(name, source, target) {
+        const branches = this.#expandedBranches(name, new Set(), `$edge-use:${name}`);
+        const use = { kind: 'edge', source, target };
+        return branches !== undefined && branches.every((branch) => this.branchIsTyped(branch, use));
+    }
+    #concreteEndpointClasses(accepts) {
+        return this.scope.concreteNodeClasses.filter((candidate) => this.#classSatisfiesEndpoint(candidate, accepts));
+    }
+    #expandedBranches(name, visiting, namespace) {
+        if (visiting.has(name))
+            return undefined;
+        const cached = this.#expansions.get(name);
+        if (cached !== undefined || this.#expansions.has(name))
+            return cached;
+        const expanded = this.#expandDeclaration(name, visiting, namespace);
+        this.#expansions.set(name, expanded);
+        return expanded;
+    }
+    #expandDeclaration(name, visiting, namespace) {
+        const declaration = this.scope.normalized.get(name);
+        if (declaration === undefined)
+            return undefined;
+        if ('match' in declaration)
+            return branchesOf(declaration.match, namespace);
+        const nested = new Set(visiting);
+        nested.add(name);
+        const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+        const children = [];
+        for (const [index, ref] of refs.entries()) {
+            if (!this.scope.isLocalPolicy(ref))
+                return undefined;
+            const expanded = this.#expandedBranches(ref.name, nested, `${namespace}/${index}:${ref.name}`);
+            if (expanded === undefined)
+                return undefined;
+            children.push(expanded);
+        }
+        return 'allOf' in declaration ? branchProduct(children) : capBranches(children.flat());
+    }
+    #constraintsAreSatisfiable(branch, variants, use) {
+        const terms = new Set(use.kind === 'object' ? ['subject', 'object'] : ['subject', 'source', 'target']);
+        for (const key of branch.variables.keys())
+            terms.add(key);
+        for (const key of branch.terms.keys())
+            terms.add(key);
+        for (const edge of branch.edges) {
+            terms.add(termKey(edge.pattern.source, edge.namespace));
+            terms.add(termKey(edge.pattern.target, edge.namespace));
+        }
+        const union = new UnionFind(terms);
+        for (const [left, right] of branch.equalities)
+            union.join(left, right);
+        for (const variant of variants) {
+            for (const [left, right] of variant.equalities)
+                union.join(left, right);
+        }
+        const constraints = new Map();
+        for (const variant of variants) {
+            for (const [term, accepts] of variant.constraints) {
+                const root = union.find(term);
+                const values = constraints.get(root) ?? [];
+                values.push(accepts);
+                constraints.set(root, values);
+            }
+        }
+        const groups = new Map();
+        for (const term of terms) {
+            const root = union.find(term);
+            const members = groups.get(root) ?? [];
+            members.push(term);
+            groups.set(root, members);
+        }
+        for (const [root, members] of groups) {
+            const endpointConstraints = constraints.get(root) ?? [];
+            let candidates = [{ kind: 'open', requirements: [] }];
+            for (const member of members) {
+                candidates = this.#applyInitial(candidates, member, branch, use);
+                if (candidates.length === 0)
+                    return false;
+            }
+            for (const endpoint of endpointConstraints) {
+                candidates = this.#applyEndpoint(candidates, endpoint);
+                if (candidates.length === 0)
+                    return false;
+            }
+        }
+        return true;
+    }
+    #applyInitial(candidates, term, branch, use) {
+        if (term === 'subject')
+            return this.#applyAnyNodeClass(candidates);
+        const contract = targetContract(term, use);
+        if (contract !== undefined) {
+            if (contract.kind === 'exact')
+                return this.#applyExact(candidates, contract.ref);
+            if (contract.kind === 'default') {
+                return uniqueCandidates(this.scope.allNodeClasses.flatMap((ref) => this.#applyExact(candidates, ref)));
+            }
+            return candidates;
+        }
+        const referenced = branch.terms.get(term);
+        if (referenced?.kind === 'ref') {
+            const contract = this.scope.referenceContract(referenced.ref);
+            return contract?.kind === 'exact' ? this.#applyExact(candidates, contract.ref) : [];
+        }
+        const selector = branch.variables.get(term);
+        if (selector === undefined)
+            return [];
+        if (selector.kind === 'exact')
+            return this.#applyExact(candidates, selector.class);
+        if (selector.kind === 'any')
+            return candidates;
+        return this.#applyRequirement(candidates, selector.class);
+    }
+    #applyExact(candidates, exact) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (definitionRefIndex(candidate.ref) === definitionRefIndex(exact))
+                    result.push(candidate);
+            }
+            else if (candidate.requirements.every((required) => this.scope.classExtends(exact, required))) {
+                result.push({ kind: 'exact', ref: exact });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #applyAnyNodeClass(candidates) {
+        return uniqueCandidates(candidates.flatMap((candidate) => candidate.kind === 'exact'
+            ? [candidate]
+            : this.scope.allNodeClasses
+                .filter((ref) => candidate.requirements.every((required) => this.scope.classExtends(ref, required)))
+                .map((ref) => ({ kind: 'exact', ref }))));
+    }
+    #applyRequirement(candidates, required) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (this.scope.classExtends(candidate.ref, required))
+                    result.push(candidate);
+            }
+            else {
+                result.push({
+                    kind: 'open',
+                    requirements: uniqueClasses([...candidate.requirements, required]),
+                });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #applyEndpoint(candidates, accepts) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (this.#classSatisfiesEndpoint(candidate.ref, accepts))
+                    result.push(candidate);
+                continue;
+            }
+            for (const accept of accepts) {
+                result.push({
+                    kind: 'open',
+                    requirements: uniqueClasses([...candidate.requirements, accept]),
+                });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #classSatisfiesEndpoint(candidate, accepts) {
+        return accepts.some((accept) => this.scope.classExtends(candidate, accept));
+    }
+}
+function targetContract(term, use) {
+    if (use.kind === 'object')
+        return term === 'object' ? use.object : undefined;
+    if (term === 'source')
+        return use.source;
+    if (term === 'target')
+        return use.target;
+    return undefined;
+}
+function edgeAlternatives(edges, typing) {
+    let result = [[]];
+    for (const edge of edges) {
+        const variants = variantsForEdge(edge, typing);
+        if (variants.length === 0)
+            return [];
+        const next = [];
+        for (const prefix of result) {
+            for (const variant of variants)
+                next.push([...prefix, variant]);
+        }
+        result = next;
+    }
+    return result;
+}
+function variantsForEdge(use, typing) {
+    const edge = use.pattern;
+    const declaration = typing.scope.edgeDeclaration(edge.class);
+    if (declaration === undefined)
+        return [];
+    const endpoints = declaration.orientation === 'directed'
+        ? [declaration.endpoints.source, declaration.endpoints.target]
+        : declaration.endpoints;
+    const bounds = edge.repeat ?? { min: 1, max: 1 };
+    if (!Number.isInteger(bounds.min) ||
+        !Number.isInteger(bounds.max) ||
+        bounds.min < 0 ||
+        bounds.max < bounds.min ||
+        bounds.max > MAX_REPEAT) {
+        return [];
+    }
+    const sourceKey = termKey(edge.source, use.namespace);
+    const targetKey = termKey(edge.target, use.namespace);
+    const variants = [];
+    for (let length = bounds.min; length <= bounds.max; length++) {
+        if (length === 0) {
+            variants.push({ constraints: [], equalities: [[sourceKey, targetKey]] });
+            continue;
+        }
+        const orientationCount = declaration.orientation === 'undirected' ? 2 ** length : 1;
+        for (let mask = 0; mask < orientationCount; mask++) {
+            const orientations = Array.from({ length }, (_, index) => declaration.orientation === 'undirected' && (mask & (1 << index)) !== 0);
+            let transitionsValid = true;
+            for (let index = 0; index + 1 < length; index++) {
+                const incoming = endEndpoint(endpoints, orientations[index] ?? false);
+                const outgoing = startEndpoint(endpoints, orientations[index + 1] ?? false);
+                if (!typing.endpointsOverlap(incoming.accepts, outgoing.accepts)) {
+                    transitionsValid = false;
+                    break;
+                }
+            }
+            if (!transitionsValid)
+                continue;
+            const first = startEndpoint(endpoints, orientations[0] ?? false);
+            const last = endEndpoint(endpoints, orientations[length - 1] ?? false);
+            variants.push({
+                constraints: [
+                    [sourceKey, first.accepts],
+                    [targetKey, last.accepts],
+                ],
+                equalities: [],
+            });
+        }
+    }
+    return uniqueEdgeVariants(variants);
+}
+function startEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[1] : endpoints[0];
+}
+function endEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[0] : endpoints[1];
+}
+function uniqueEdgeVariants(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = `${value.constraints
+            .map(([term, accepts]) => `${term}:${accepts.map(definitionRefIndex).sort().join(',')}`)
+            .join('|')}=${value.equalities.map(([left, right]) => `${left}:${right}`).join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueCandidates(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = value.kind === 'exact'
+            ? `exact:${definitionRefIndex(value.ref)}`
+            : `open:${value.requirements.map(definitionRefIndex).sort().join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueClasses(values) {
+    return [...new Map(values.map((value) => [definitionRefIndex(value), value])).values()];
+}

package/dist/v1/language/validation/diagnostic.d.ts

@@ -6,3 +6,17 @@ export interface Diagnostic<out Code extends DiagnosticCode = DiagnosticCode> {
     readonly ref?: string;
 }
 export declare function diagnostic<const Code extends DiagnosticCode>(code: Code, pointer: string, message: string, ref?: string): Diagnostic<Code>;
+/** The fields every diagnostic family shares. */
+interface DiagnosticFields {
+    readonly code: string;
+    readonly pointer: string;
+    readonly message: string;
+    readonly ref?: string;
+}
+/** Order diagnostics by pointer, then code, then message. */
+export declare function orderDiagnostics<Value extends DiagnosticFields>(diagnostics: readonly Value[]): Value[];
+/** Keep one of each pointer, code, ref and message, then order them. */
+export declare function orderAndDeduplicate<Value extends DiagnosticFields>(diagnostics: readonly Value[]): Value[];
+/** One line per diagnostic: its pointer (`/` for the root), its code and its message. */
+export declare function formatDiagnostics(diagnostics: readonly DiagnosticFields[]): string;
+export {};

package/dist/v1/language/validation/diagnostic.js

@@ -1,3 +1,24 @@
+import { compareUnicode } from '../../addressing/ordering.js';
 export function diagnostic(code, pointer, message, ref) {
     return Object.freeze({ code, pointer, message, ...(ref === undefined ? {} : { ref }) });
 }
+/** Order diagnostics by pointer, then code, then message. */
+export function orderDiagnostics(diagnostics) {
+    return [...diagnostics].sort((left, right) => compareUnicode(left.pointer, right.pointer) ||
+        compareUnicode(left.code, right.code) ||
+        compareUnicode(left.message, right.message));
+}
+/** Keep one of each pointer, code, ref and message, then order them. */
+export function orderAndDeduplicate(diagnostics) {
+    const unique = new Map();
+    for (const value of diagnostics) {
+        unique.set(`${value.pointer}\u0000${value.code}\u0000${value.ref ?? ''}\u0000${value.message}`, value);
+    }
+    return orderDiagnostics([...unique.values()]);
+}
+/** One line per diagnostic: its pointer (`/` for the root), its code and its message. */
+export function formatDiagnostics(diagnostics) {
+    return diagnostics
+        .map(({ code, pointer, message }) => `${pointer || '/'} [${code}] ${message}`)
+        .join('\n');
+}

package/dist/v1/language/value/compile/fields.js

@@ -1,3 +1,5 @@
+import { compareCodeUnits } from '../../../addressing/ordering.js';
+import { escapePointerToken } from '../syntax/pointer.js';
 /** Exact field constraints available for independent scalar route validation. */
 export function inputFieldNodes(program) {
     const fields = new Map();
@@ -34,7 +36,7 @@ export function inputFieldNodes(program) {
             Array.isArray(schema.properties))
             return;
         for (const name of Object.keys(schema.properties)) {
-            const child = node.children[`properties/${escapePointer(name)}`];
+            const child = node.children[`properties/${escapePointerToken(name)}`];
             if (child === undefined)
                 throw new TypeError(`Compiled input field ${name} is absent.`);
             const constraints = fields.get(name) ?? new Set();
@@ -46,15 +48,9 @@ export function inputFieldNodes(program) {
     if (!closed || unsupported)
         return undefined;
     return Object.freeze(Object.fromEntries([...fields]
-        .sort(([left], [right]) => compare(left, right))
+        .sort(([left], [right]) => compareCodeUnits(left, right))
         .map(([name, nodes]) => [
         name,
         Object.freeze([...nodes].sort((left, right) => left - right)),
     ])));
 }
-function escapePointer(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}
-function compare(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

package/dist/v1/language/value/profile/rules.js

@@ -4,6 +4,7 @@ import { blob, BLOB_VALUE_KIND } from '../model/blob.js';
 import { isValueObject as isJsonObject } from '../model/object.js';
 import { VALUE_SCHEMA_DIALECT } from '../model/schema.js';
 import { refuseIRegexp, stateBudgetMessage } from '../regexp/syntax.js';
+import { escapePointerToken } from '../syntax/pointer.js';
 import { walkSchema } from '../syntax/walk.js';
 import { FORBIDDEN_DYNAMIC_KEYWORDS, STANDARD_SCHEMA_KEYWORDS } from './vocabulary.js';
 export function validateSchemaProfile(schema, context, pointer) {
@@ -14,10 +15,10 @@ export function validateSchemaProfile(schema, context, pointer) {
         const currentPointer = `${pointer}${location.pointer}`;
         for (const keyword of Object.keys(location.schema)) {
             if (!STANDARD_SCHEMA_KEYWORDS.has(keyword)) {
-                diagnostics.push(diagnostic('VS_KEYWORD_CLOSED', `${currentPointer}/${escapeToken(keyword)}`, `Keyword ${keyword} is outside the closed V1 Draft 2020-12 vocabulary.`));
+                diagnostics.push(diagnostic('VS_KEYWORD_CLOSED', `${currentPointer}/${escapePointerToken(keyword)}`, `Keyword ${keyword} is outside the closed V1 Draft 2020-12 vocabulary.`));
             }
             if (FORBIDDEN_DYNAMIC_KEYWORDS.has(keyword)) {
-                diagnostics.push(diagnostic('VS_DYNAMIC_FORBIDDEN', `${currentPointer}/${escapeToken(keyword)}`, `Keyword ${keyword} is forbidden by V1.`));
+                diagnostics.push(diagnostic('VS_DYNAMIC_FORBIDDEN', `${currentPointer}/${escapePointerToken(keyword)}`, `Keyword ${keyword} is forbidden by V1.`));
             }
         }
         if (Object.hasOwn(location.schema, '$schema')) {
@@ -86,7 +87,7 @@ function validateSemanticSets(schema, pointer, diagnostics) {
     if (isJsonObject(schema.dependentRequired)) {
         for (const [name, dependencies] of Object.entries(schema.dependentRequired)) {
             if (Array.isArray(dependencies)) {
-                rejectPrimitiveDuplicates(dependencies, `${pointer}/dependentRequired/${escapeToken(name)}`, 'dependentRequired', diagnostics);
+                rejectPrimitiveDuplicates(dependencies, `${pointer}/dependentRequired/${escapePointerToken(name)}`, 'dependentRequired', diagnostics);
             }
         }
     }
@@ -103,7 +104,7 @@ function validateRegexes(schema, pointer, diagnostics) {
     }
     if (isJsonObject(schema.patternProperties)) {
         for (const pattern of Object.keys(schema.patternProperties)) {
-            portableRegex(pattern, `${pointer}/patternProperties/${escapeToken(pattern)}`, 'A patternProperties key', 'patternProperties keys must satisfy RFC 9485 I-Regexp syntax.', diagnostics);
+            portableRegex(pattern, `${pointer}/patternProperties/${escapePointerToken(pattern)}`, 'A patternProperties key', 'patternProperties keys must satisfy RFC 9485 I-Regexp syntax.', diagnostics);
         }
     }
 }
@@ -140,6 +141,3 @@ function rejectCanonicalDuplicates(values, pointer, name, diagnostics) {
         seen.add(key);
     }
 }
-function escapeToken(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}

package/dist/v1/language/value/profile/validate.js

@@ -1,4 +1,4 @@
-import { compareUnicode } from '../../../addressing/ordering.js';
+import { orderAndDeduplicate } from '../../validation/diagnostic.js';
 import { collectResourceClosure } from '../reference/closure.js';
 import { validateProductiveRecursion } from '../reference/recursion.js';
 import { hasNodeDefinition, indexRegistry } from '../reference/registry.index.js';
@@ -28,12 +28,3 @@ export function validateValueSchema(schema, context, registry, pointer = '') {
     diagnostics.push(...validateProductiveRecursion(closure.resources, closure.resolutions));
     return orderAndDeduplicate(diagnostics);
 }
-function orderAndDeduplicate(diagnostics) {
-    const unique = new Map();
-    for (const value of diagnostics) {
-        unique.set(`${value.pointer}\u0000${value.code}\u0000${value.ref ?? ''}\u0000${value.message}`, value);
-    }
-    return [...unique.values()].sort((left, right) => compareUnicode(left.pointer, right.pointer) ||
-        compareUnicode(left.code, right.code) ||
-        compareUnicode(left.message, right.message));
-}

package/dist/v1/language/value/reference/recursion.js

@@ -1,8 +1,7 @@
 import { diagnostic } from '../../validation/diagnostic.js';
 import { isValueObject as isJsonObject } from '../model/object.js';
-import { SCHEMA_ARRAY_KEYWORDS, SCHEMA_MAP_KEYWORDS, SCHEMA_SINGLE_KEYWORDS, } from '../syntax/keywords.js';
 import { appendPointer } from '../syntax/pointer.js';
-import { isJsonSchema, walkSchema } from '../syntax/walk.js';
+import { forEachSubschema, walkSchema } from '../syntax/walk.js';
 import { locationKey } from './closure.js';
 export const CONSUMING_SCHEMA_KEYWORDS = new Set([
     'additionalProperties',
@@ -43,26 +42,7 @@ export function validateProductiveRecursion(resources, resolutions) {
             for (const [keyword, value] of Object.entries(location.schema)) {
                 if (!NON_CONSUMING_SCHEMA_KEYWORDS.has(keyword))
                     continue;
-                const keywordPointer = appendPointer(location.pointer, keyword);
-                if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(value)) {
-                    outgoing.add(locationKey(resource.key, keywordPointer));
-                    continue;
-                }
-                if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(value)) {
-                    value.forEach((entry, index) => {
-                        if (isJsonSchema(entry)) {
-                            outgoing.add(locationKey(resource.key, appendPointer(keywordPointer, index)));
-                        }
-                    });
-                    continue;
-                }
-                if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(value)) {
-                    for (const [name, entry] of Object.entries(value)) {
-                        if (isJsonSchema(entry)) {
-                            outgoing.add(locationKey(resource.key, appendPointer(keywordPointer, name)));
-                        }
-                    }
-                }
+                forEachSubschema(keyword, value, appendPointer(location.pointer, keyword), (_, at) => outgoing.add(locationKey(resource.key, at)));
             }
         });
     }

package/dist/v1/language/value/syntax/pointer.d.ts

@@ -1,3 +1,5 @@
+/** Escape one JSON Pointer reference token: `~` as `~0`, then `/` as `~1`. */
+export declare function escapePointerToken(token: string): string;
 export declare function appendPointer(pointer: string, token: string | number): string;
 export declare function parseJsonPointerFragment(fragment: string): readonly string[] | undefined;
 export declare function tokensToPointer(tokens: readonly string[]): string;

package/dist/v1/language/value/syntax/pointer.js

@@ -1,6 +1,9 @@
+/** Escape one JSON Pointer reference token: `~` as `~0`, then `/` as `~1`. */
+export function escapePointerToken(token) {
+    return token.replaceAll('~', '~0').replaceAll('/', '~1');
+}
 export function appendPointer(pointer, token) {
-    const encoded = String(token).replaceAll('~', '~0').replaceAll('/', '~1');
-    return `${pointer}/${encoded}`;
+    return `${pointer}/${escapePointerToken(String(token))}`;
 }
 export function parseJsonPointerFragment(fragment) {
     if (!fragment.startsWith('#'))

package/dist/v1/language/value/syntax/walk.d.ts

@@ -6,5 +6,7 @@ export interface SchemaLocation {
     readonly parentKeyword?: string;
 }
 export declare function walkSchema(schema: JsonSchema, visit: (location: SchemaLocation) => void, pointer?: string): void;
+/** Visit each subschema `keyword` holds directly, with its pointer under `pointer`. */
+export declare function forEachSubschema(keyword: string, value: unknown, pointer: string, visit: (schema: JsonSchema, pointer: string) => void): void;
 export declare function collectSchemaPointers(schema: JsonSchema): ReadonlySet<string>;
 export declare function isJsonSchema(value: unknown): value is JsonSchema;

package/dist/v1/language/value/syntax/walk.js

@@ -14,26 +14,7 @@ export function walkSchema(schema, visit, pointer = '') {
             if (!isJsonObject(current))
                 return;
             for (const [keyword, value] of Object.entries(current)) {
-                const keywordPointer = appendPointer(currentPointer, keyword);
-                if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(value)) {
-                    walk(value, keywordPointer, depth + 1, keyword);
-                    continue;
-                }
-                if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(value)) {
-                    value.forEach((entry, index) => {
-                        if (isJsonSchema(entry)) {
-                            walk(entry, appendPointer(keywordPointer, index), depth + 1, keyword);
-                        }
-                    });
-                    continue;
-                }
-                if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(value)) {
-                    for (const [name, entry] of Object.entries(value)) {
-                        if (isJsonSchema(entry)) {
-                            walk(entry, appendPointer(keywordPointer, name), depth + 1, keyword);
-                        }
-                    }
-                }
+                forEachSubschema(keyword, value, appendPointer(currentPointer, keyword), (entry, at) => walk(entry, at, depth + 1, keyword));
             }
         }
         finally {
@@ -43,6 +24,24 @@ export function walkSchema(schema, visit, pointer = '') {
     }
     walk(schema, pointer, 0);
 }
+/** Visit each subschema `keyword` holds directly, with its pointer under `pointer`. */
+export function forEachSubschema(keyword, value, pointer, visit) {
+    if (SCHEMA_SINGLE_KEYWORDS.has(keyword) && isJsonSchema(value)) {
+        visit(value, pointer);
+    }
+    else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(value)) {
+        value.forEach((entry, index) => {
+            if (isJsonSchema(entry))
+                visit(entry, appendPointer(pointer, index));
+        });
+    }
+    else if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(value)) {
+        for (const [name, entry] of Object.entries(value)) {
+            if (isJsonSchema(entry))
+                visit(entry, appendPointer(pointer, name));
+        }
+    }
+}
 export function collectSchemaPointers(schema) {
     const pointers = new Set();
     walkSchema(schema, ({ pointer }) => pointers.add(pointer));

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

@@ -1,5 +1,6 @@
 import { compareUnicode } from '../../addressing/ordering.js';
 import { isValueObject as isJsonObject } from '../../language/value/model/object.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
 /** Structural differences between two portable values, leaf by leaf, in JSON Pointer order. */
 export function differences(before, after) {
     const found = [];
@@ -17,7 +18,7 @@ function collect(before, after, path, found) {
     if (isJsonObject(before) && isJsonObject(after)) {
         const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])].sort(compareUnicode);
         for (const key of keys) {
-            collect(before[key], after[key], `${path}/${escape(key)}`, found);
+            collect(before[key], after[key], `${path}/${escapePointerToken(key)}`, found);
         }
         return;
     }
@@ -34,6 +35,3 @@ function collect(before, after, path, found) {
         ...(after === undefined ? {} : { after }),
     }));
 }
-function escape(segment) {
-    return segment.replaceAll('~', '~0').replaceAll('/', '~1');
-}