@techspokes/typescript-wsdl-client 1.1.4 → 1.1.8

package/dist/compiler/catalogErrors.js

@@ -0,0 +1,86 @@
+export class CatalogError extends Error {
+    category;
+    field;
+    constructor(category, message, field) {
+        super(message);
+        this.category = category;
+        this.field = field;
+        this.name = "CatalogError";
+    }
+}
+export const DEFAULT_CATALOG_BYTES = 64 * 1024 * 1024;
+export const DEFAULT_CATALOG_DEPTH = 1024;
+/** Property ordering is display ordering; array ordering always remains semantic. */
+export function canonicalJson(value) {
+    const order = (v) => {
+        if (Array.isArray(v))
+            return v.map(order);
+        if (v && typeof v === "object")
+            return Object.fromEntries(Object.keys(v).sort().filter(k => v[k] !== undefined).map(k => [k, order(v[k])]));
+        return v;
+    };
+    return JSON.stringify(order(value));
+}
+export function positiveLimit(value, fallback, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return result;
+}
+/** Scan nesting before JSON.parse can allocate an arbitrarily deep input. */
+export function parseCatalogJson(text, limits = {}) {
+    const maxBytes = positiveLimit(limits.maxBytes, DEFAULT_CATALOG_BYTES, "maxBytes");
+    const maxDepth = positiveLimit(limits.maxDepth, DEFAULT_CATALOG_DEPTH, "maxDepth");
+    if (maxDepth > DEFAULT_CATALOG_DEPTH)
+        throw new RangeError(`maxDepth cannot exceed the reader safety ceiling ${DEFAULT_CATALOG_DEPTH}`);
+    if (Buffer.byteLength(text, "utf8") > maxBytes)
+        throw new CatalogError("resource-limit", `Catalog exceeds ${maxBytes} UTF-8 bytes`);
+    let depth = 0, quoted = false, escaped = false, quoteStart = 0;
+    const stack = [];
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"') {
+                quoted = false;
+                let next = i + 1;
+                while (/[\t\r\n ]/.test(text[next] ?? "x"))
+                    next++;
+                if (text[next] === ":" && stack.at(-1)?.object) {
+                    let key;
+                    try {
+                        key = JSON.parse(text.slice(quoteStart, i + 1));
+                    }
+                    catch {
+                        throw new CatalogError("invalid-schema", "Catalog is not valid JSON");
+                    }
+                    if (stack.at(-1).keys.has(key))
+                        throw new CatalogError("invalid-schema", "Catalog contains duplicate object fields");
+                    stack.at(-1).keys.add(key);
+                }
+            }
+        }
+        else if (char === '"') {
+            quoted = true;
+            quoteStart = i;
+        }
+        else if (char === "{" || char === "[") {
+            if (++depth > maxDepth)
+                throw new CatalogError("resource-limit", `Catalog exceeds nesting depth ${maxDepth}`);
+            stack.push({ object: char === "{", keys: new Set() });
+        }
+        else if (char === "}" || char === "]") {
+            depth--;
+            stack.pop();
+        }
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CatalogError("invalid-schema", "Catalog is not valid JSON");
+    }
+}

package/dist/compiler/catalogProvenance.d.ts

@@ -0,0 +1,14 @@
+import type { CanonicalGraph } from "./canonicalGraph.js";
+export declare const sha256: (text: string) => string;
+export declare function artifactGraph(graph: CanonicalGraph): CanonicalGraph;
+/** These display/provenance tables have no semantic child order. */
+export declare function normalizeGraphTables(result: CanonicalGraph): CanonicalGraph;
+/** Excludes source digests/locations, machine paths, documentation and loading policy. */
+export declare function semanticGraphRepresentation(graph: CanonicalGraph, options?: {
+    referenceIdentityOnly?: boolean;
+}): {
+    structure: string;
+    identities: ReadonlyMap<string, string>;
+};
+/** Fingerprinting and companion comparison share the same actual normalized structure. */
+export declare function semanticGraphFingerprint(graph: CanonicalGraph): string;

package/dist/compiler/catalogProvenance.js

@@ -0,0 +1,229 @@
+/** Portable provenance is content-addressed; full retrieval context stays in the loading snapshot. */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { XML_NAMESPACE, XSD_NAMESPACE, WSDL_NAMESPACE } from "../loader/orderedSyntax.js";
+import { canonicalJson, CatalogError } from "./catalogErrors.js";
+export const sha256 = (text) => createHash("sha256").update(text, "utf8").digest("hex");
+const sourceUri = (digest) => `urn:source:sha256:${digest}`;
+const artifactUri = /^(?:urn:source:sha256:|urn:base:sha256:)[a-f0-9]{64}$/;
+function baseUri(uri, source) {
+    if (artifactUri.test(uri))
+        return uri;
+    try {
+        const base = new URL(uri), document = new URL(source.uri);
+        // Relative file placement is retained as a digest; temporary root paths never leave the snapshot.
+        const relation = base.protocol === document.protocol && base.host === document.host
+            ? path.posix.relative(path.posix.dirname(document.pathname), base.pathname) : `${base.protocol}//${base.host}${base.pathname}`;
+        return `urn:base:sha256:${sha256(canonicalJson([source.digest, relation, base.search ? sha256(base.search) : ""]))}`;
+    }
+    catch {
+        throw new CatalogError("invalid-schema", "Invalid provenance URI");
+    }
+}
+export function artifactGraph(graph) {
+    const resources = new Map();
+    const collected = new WeakSet();
+    const collect = (v) => {
+        if (typeof v === "string" && /[a-z][a-z0-9+.-]*:\/\/[^\s/]*@/i.test(v))
+            throw new CatalogError("incompatible-artifact", "Credential-bearing URI cannot be serialized");
+        if (!v || typeof v !== "object")
+            return;
+        if (collected.has(v))
+            return;
+        collected.add(v);
+        if (Array.isArray(v)) {
+            for (const c of v)
+                collect(c);
+            return;
+        }
+        const o = v;
+        if (typeof o.uri === "string" && typeof o.digest === "string" && typeof o.path === "string")
+            resources.set(o.uri, o.digest);
+        for (const c of Object.values(o))
+            collect(c);
+    };
+    collect(graph);
+    const interpretation = (key) => {
+        if (artifactUri.test(key))
+            return key;
+        if (resources.has(key))
+            return sourceUri(resources.get(key));
+        try {
+            const tuple = JSON.parse(key);
+            if (!Array.isArray(tuple) || tuple.length !== 7)
+                throw Error();
+            return canonicalJson([tuple[0], sourceUri(tuple[0]), baseUri(tuple[2], { uri: tuple[1], digest: tuple[0] }), ...tuple.slice(3)]);
+        }
+        catch {
+            throw new CatalogError("invalid-schema", "Invalid loading interpretation key");
+        }
+    };
+    // Preserve immutable source/syntax sharing internally. Parent namespace and
+    // local name remain part of the key: retrieval attributes and SOAP binding
+    // addresses have different transformations/checks in different XML contexts.
+    // The data-only format-2 materialization remains byte-for-byte unchanged.
+    const transformed = new WeakMap();
+    const transform = (v, parentName) => {
+        if (!v || typeof v !== "object")
+            return v;
+        const context = parentName ? JSON.stringify([parentName.namespace, parentName.local]) : "";
+        let variants = transformed.get(v);
+        if (variants?.has(context))
+            return variants.get(context);
+        if (!variants) {
+            variants = new Map();
+            transformed.set(v, variants);
+        }
+        if (Array.isArray(v)) {
+            const result = v.map(c => transform(c, parentName));
+            variants.set(context, result);
+            return result;
+        }
+        const o = v, result = Object.create(null);
+        for (const [k, c] of Object.entries(o)) {
+            if (c === undefined)
+                continue;
+            if (k === "uri" && typeof o.digest === "string")
+                result[k] = sourceUri(o.digest);
+            else if (k === "baseUri" && o.source)
+                result[k] = baseUri(c, o.source);
+            else if (k === "interpretation" || (k === "from" && o.cycle !== undefined) || (k === "to" && o.cycle !== undefined))
+                result[k] = interpretation(c);
+            else if (k === "referenceUri" && o.source)
+                result[k] = baseUri(c, o.source);
+            else
+                result[k] = transform(c, k === "attributes" && o.kind === "element" ? o.name : undefined);
+        }
+        if (o.name && typeof o.value === "string") {
+            const a = o;
+            const bindingAddress = ["http://schemas.xmlsoap.org/wsdl/soap/", "http://schemas.xmlsoap.org/wsdl/soap12/"].includes(parentName?.namespace ?? "") && parentName?.local === "address" && a.name.local === "location";
+            if (bindingAddress) {
+                try {
+                    const endpoint = new URL(a.value);
+                    if ([...endpoint.searchParams.keys()].some(k => /token|secret|password|api[-_]?key|authorization|signature|credential/i.test(k)))
+                        throw new CatalogError("incompatible-artifact", "Credential-bearing binding URI cannot be serialized");
+                }
+                catch (e) {
+                    if (e instanceof CatalogError)
+                        throw e;
+                    throw new CatalogError("invalid-schema", "Invalid binding address URI");
+                }
+            }
+            if ((a.name.namespace === XML_NAMESPACE && a.name.local === "base") ||
+                (parentName?.namespace === XSD_NAMESPACE && ["include", "import", "redefine"].includes(parentName.local) && a.name.local === "schemaLocation") ||
+                (parentName?.namespace === XSD_NAMESPACE && parentName.local === "documentation" && a.name.local === "source") ||
+                (parentName?.namespace === WSDL_NAMESPACE && parentName.local === "import" && a.name.local === "location")) {
+                // Retrieval URI attributes are provenance; binding endpoints remain semantic syntax.
+                result.value = artifactUri.test(a.value) ? a.value : `urn:base:sha256:${sha256(a.value.replace(/\?.*$/, ""))}`;
+            }
+        }
+        variants.set(context, result);
+        return result;
+    };
+    return normalizeGraphTables(transform(graph));
+}
+/** These display/provenance tables have no semantic child order. */
+export function normalizeGraphTables(result) {
+    const origins = Object.fromEntries(Object.entries(result.origins).map(([id, values]) => [id, [...values].sort((a, b) => { const x = canonicalJson(a), y = canonicalJson(b); return x < y ? -1 : x > y ? 1 : 0; })]));
+    return { ...result, origins, nodes: [...result.nodes].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0), globals: [...result.globals].sort() };
+}
+/** Excludes source digests/locations, machine paths, documentation and loading policy. */
+export function semanticGraphRepresentation(graph, options = {}) {
+    const portable = artifactGraph(graph);
+    // Source-relative scoped IDs remain artifact identity. Fingerprint-only IDs follow semantic
+    // containment instead, so inserting documentation cannot change their identity or table order.
+    const ids = new Map(), paths = new Map();
+    const nodes = new Map(portable.nodes.map(n => [n.id, n]));
+    const children = (n) => {
+        const result = [];
+        const ref = (r, edge) => { if (r?.kind === "local")
+            result.push([r.target, edge]); };
+        if (n.kind === "element" || n.kind === "attribute")
+            ref(n.type, "type");
+        if (n.kind === "element")
+            ref(n.substitutionGroup, "substitutionGroup");
+        if (n.kind === "attributeUse")
+            ref(n.declaration, "declaration");
+        if (n.kind === "attributeGroupUse")
+            ref(n.reference, "attributeGroup");
+        if (n.kind === "particle") {
+            if (n.term.kind === "element")
+                ref(n.term.declaration, "declaration");
+            else if (n.term.kind === "group")
+                ref(n.term.reference, "group");
+            else if (n.term.kind === "sequence" || n.term.kind === "choice" || n.term.kind === "all")
+                n.term.children.forEach((id, i) => result.push([id, `children/${i}`]));
+        }
+        if (n.kind === "group" || n.kind === "complexType") {
+            if (n.content)
+                result.push([n.content, "content"]);
+        }
+        if (n.kind === "attributeGroup" || n.kind === "complexType")
+            n.attributes.forEach((id, i) => result.push([id, `attributes/${i}`]));
+        if (n.kind === "complexType") {
+            ref(n.derivation?.base, "base");
+            ref(n.derivation?.inlineType, "inlineType");
+        }
+        if (n.kind === "simpleType") {
+            if (n.variety.kind === "restriction")
+                ref(n.variety.base, "base");
+            else if (n.variety.kind === "list")
+                ref(n.variety.item, "item");
+            else
+                n.variety.members.forEach((r, i) => ref(r, `members/${i}`));
+        }
+        return result;
+    };
+    const stack = portable.globals.map(id => ({ id, path: id }));
+    while (stack.length) {
+        const item = stack.pop(), n = nodes.get(item.id);
+        if (ids.has(n.id))
+            continue;
+        const id = n.identity.kind === "global" ? n.id : `semantic:${sha256(item.path)}`;
+        ids.set(n.id, id);
+        paths.set(n.id, item.path);
+        for (const [child, edge] of children(n))
+            stack.push({ id: child, path: `${item.path}/${edge}` });
+    }
+    const mappedId = (id) => ids.get(id);
+    const reference = (r) => r.kind === "local" ? { ...r, target: mappedId(r.target) } : r;
+    const mapNode = (n) => {
+        const common = { ...n, id: mappedId(n.id), identity: n.identity.kind === "scoped" ? { ...n.identity, owner: mappedId(n.identity.owner), path: paths.get(n.id) } : n.identity };
+        switch (n.kind) {
+            case "element": return { ...common, kind: n.kind, name: n.name, type: reference(n.type), nillable: n.nillable, abstract: n.abstract, value: n.value, substitutionGroup: n.substitutionGroup ? reference(n.substitutionGroup) : undefined };
+            case "attribute": return { ...common, kind: n.kind, name: n.name, type: reference(n.type), value: n.value };
+            case "attributeUse": return { ...common, kind: n.kind, declaration: reference(n.declaration), use: n.use, value: n.value };
+            case "particle": return { ...common, kind: n.kind, occurs: n.occurs, term: n.term.kind === "element" ? { ...n.term, declaration: reference(n.term.declaration) } : n.term.kind === "group" ? { ...n.term, reference: reference(n.term.reference) } : n.term.kind === "sequence" || n.term.kind === "choice" || n.term.kind === "all" ? { ...n.term, children: n.term.children.map(mappedId) } : n.term };
+            case "group": return { ...common, kind: n.kind, content: mappedId(n.content) };
+            case "attributeGroup": return { ...common, kind: n.kind, attributes: n.attributes.map(mappedId) };
+            case "complexType": return { ...common, kind: n.kind, mixed: n.mixed, abstract: n.abstract, content: n.content ? mappedId(n.content) : undefined, attributes: n.attributes.map(mappedId), derivation: n.derivation ? { ...n.derivation, base: reference(n.derivation.base), inlineType: n.derivation.inlineType ? reference(n.derivation.inlineType) : undefined } : undefined };
+            case "simpleType": return { ...common, kind: n.kind, variety: n.variety.kind === "restriction" ? { ...n.variety, base: reference(n.variety.base) } : n.variety.kind === "list" ? { ...n.variety, item: reference(n.variety.item) } : { ...n.variety, members: n.variety.members.map(reference) } };
+            case "attributeGroupUse": return { ...common, kind: n.kind, reference: reference(n.reference) };
+            case "attributeWildcard": return { ...common, kind: n.kind, wildcard: n.wildcard };
+            case "wsdl": return { ...common, kind: n.kind, name: n.name, role: n.role, syntax: n.syntax, references: n.references };
+        }
+    };
+    const stable = { ...portable, nodes: portable.nodes.map(mapNode).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0) };
+    const omit = new Set(["source", "uri", "digest", "baseUri", "origins", "loading", "schemaAnnotations", "annotations", "lexicalName"]);
+    const semantic = (v, parentName) => {
+        if (Array.isArray(v))
+            return v.filter(c => !(c && typeof c === "object" && ((c.name?.local === "annotation" && c.name?.namespace === XSD_NAMESPACE) || (c.name?.local === "documentation" && [XSD_NAMESPACE, WSDL_NAMESPACE].includes(c.name?.namespace))))).map(c => semantic(c, parentName)).filter(c => c !== undefined);
+        if (!v || typeof v !== "object")
+            return v;
+        const o = v;
+        if (o.kind === "text" && typeof o.value === "string" && !/[^\t\r\n ]/.test(o.value) && [XSD_NAMESPACE, WSDL_NAMESPACE].includes(parentName?.namespace ?? ""))
+            return undefined;
+        if (o.kind === "symbol" || o.kind === "builtin")
+            return Object.fromEntries(Object.entries(o).filter(([k]) => k !== "lexical" && !(options.referenceIdentityOnly && k === "target")).map(([k, c]) => [k, semantic(c)]));
+        if (o.name && typeof o.value === "string" && o.name.namespace === XML_NAMESPACE && o.name.local === "base")
+            return undefined;
+        if (o.name && typeof o.value === "string" && o.name.namespace === "" && o.name.local === "schemaLocation" && parentName?.namespace === XSD_NAMESPACE && ["include", "import"].includes(parentName.local))
+            return undefined;
+        return Object.fromEntries(Object.entries(o).filter(([k]) => !omit.has(k) && !(k === "path" && Object.hasOwn(o, "reference") && Object.hasOwn(o, "attribute"))).map(([k, c]) => [k, semantic(c, ["children", "attributes"].includes(k) && o.kind === "element" ? o.name : undefined)]));
+    };
+    return { structure: canonicalJson(semantic(stable)), identities: ids };
+}
+/** Fingerprinting and companion comparison share the same actual normalized structure. */
+export function semanticGraphFingerprint(graph) {
+    return sha256(semanticGraphRepresentation(graph).structure);
+}

package/dist/compiler/checkedAssessment.d.ts

@@ -0,0 +1,90 @@
+import type { SchemaInput, SchemaInputOptions } from '../loader/schemaInput.js';
+import type { SemanticBudgetLimits, ResolverUsage } from './semanticBudget.js';
+export declare const ASSESSMENT_REPORT_BYTES: number;
+export declare const ASSESSMENT_VERSION: "checked-assessment-v1";
+export declare const ASSESSMENT_BASIS: "native-direct-premises-v1";
+export type AssessmentStatus = 'established' | 'disproved' | 'inconclusive';
+export interface AssessmentObligation {
+    readonly rule: string;
+    readonly component: string;
+    readonly context: string;
+    readonly basis: typeof ASSESSMENT_BASIS | 'dated-XSD-2004-direct-v1';
+    readonly status: AssessmentStatus;
+    readonly reason: string;
+}
+export interface AssessedOperation {
+    readonly id: string;
+    readonly name: string;
+    readonly capabilities: readonly Readonly<{
+        name: string;
+        status: 'supported' | 'unsupported' | 'not-assessed';
+        reason: string;
+    }>[];
+    readonly admitted: false;
+}
+export interface CheckedAssessmentReport {
+    readonly tool: Readonly<{
+        version: string;
+        node: string;
+    }>;
+    readonly identity: string;
+    readonly reportVersion: typeof ASSESSMENT_VERSION;
+    readonly scope: 'whole-actual-native-direct-v1';
+    readonly model: 'xsd10-faithful-v1';
+    readonly basis: typeof ASSESSMENT_BASIS;
+    readonly schema: AssessmentStatus;
+    readonly correspondence: AssessmentStatus;
+    readonly execution: 'completed' | 'resource-limit' | 'cancelled' | 'failed';
+    readonly category?: string;
+    readonly obligations: readonly AssessmentObligation[];
+    readonly operations: readonly AssessedOperation[];
+    readonly operationInventory: 'complete' | 'unassessed';
+    readonly resources: readonly Readonly<{
+        id: string;
+        digest: string;
+        bytes: number;
+    }>[];
+    readonly contexts: readonly Readonly<{
+        id: string;
+        resource: string;
+        digest: string;
+        namespace: string;
+        base: string;
+        kind: string;
+    }>[];
+    readonly components: readonly Readonly<{
+        id: string;
+        digest: string;
+        resource: string;
+        path: string;
+        contexts: readonly string[];
+    }>[];
+    readonly edges: readonly Readonly<{
+        kind: string;
+        from: string;
+        to?: string;
+        cycle: boolean;
+    }>[];
+    readonly limits: Readonly<{
+        maxWork: number;
+        maxNodes: number;
+        maxReportBytes: number;
+        loading?: SchemaInput['limits'];
+    }>;
+    readonly usage: ResolverUsage;
+    readonly schemaEligible: boolean;
+    readonly admitted: false;
+}
+/** Explicit expected inventory prevents missing duties or empty reports from establishing scope. */
+export declare function aggregateAssessment(required: readonly string[], facts: ReadonlyMap<string, AssessmentStatus>): AssessmentStatus;
+export declare function serializeAssessmentReport(report: CheckedAssessmentReport): string;
+export declare function assessmentExitCode(report: CheckedAssessmentReport): number;
+export declare function assessSchemaSource(source: string, options: Readonly<{
+    loading: SchemaInputOptions;
+    limits?: SemanticBudgetLimits;
+    signal?: AbortSignal;
+    expectedBasis?: string;
+    expectedIdentity?: string;
+}>): Promise<CheckedAssessmentReport>;
+/** Validate diagnostic JSON without treating it as authenticated semantic evidence. */
+export declare function parseAssessmentReport(text: string): CheckedAssessmentReport;