@openmbee/opensysml 0.9.2 → 0.10.0

package/dist/core/model.js

@@ -1,7 +1,9 @@
 // The ergonomic surface: a loaded model, its symbols, and the objects it
 // instantiates. Everything here is built on Connection.rpc.
 import { CAPABILITY_EVALUATE_SUBJECT, CAPABILITY_INLINE_LANGUAGE, CAPABILITY_STRICT_CONFORMANCE, requireCapability, upgradeRemedy, } from "./capabilities.js";
+import { requireString, requireSourceText } from "./arguments.js";
 import { EvaluationError, OpenSysMLError, ParseError, SymbolNotFoundError } from "./errors.js";
+import { requireLanguage } from "./sources.js";
 import { callRpc } from "./status.js";
 import { decodeValue } from "./values.js";
 /** How alike two names must be for one to be suggested for the other. */
@@ -31,6 +33,54 @@ function editDistance(left, right) {
     }
     return previous[right.length] ?? 0;
 }
+/** Resolves `strictConformance` and its `strict` alias; differing values refuse. */
+export function strictConformanceOf(options) {
+    if (options.strict !== undefined &&
+        options.strictConformance !== undefined &&
+        options.strict !== options.strictConformance) {
+        throw new RangeError(`strict (${options.strict}) and strictConformance (${options.strictConformance}) disagree; ` +
+            "pass only strictConformance");
+    }
+    return options.strictConformance ?? options.strict;
+}
+/** The integer one bound spells, or undefined when it spells none. */
+function multiplicityBound(bound) {
+    const trimmed = bound.trim();
+    if (!/^[+-]?\d+$/.test(trimmed)) {
+        return undefined;
+    }
+    return Number.parseInt(trimmed, 10);
+}
+/** Builds a Multiplicity whose predicates mirror Python's. */
+function multiplicityOf(lower, upper) {
+    const lowerBound = lower === "" ? undefined : multiplicityBound(lower);
+    return {
+        lower,
+        upper,
+        isOptional: lowerBound === undefined ? undefined : lowerBound === 0,
+        isCollection: isCollectionUpper(upper),
+    };
+}
+/** Whether an upper bound admits more than one: unknown for none, or one that is not a number. */
+function isCollectionUpper(upper) {
+    if (upper === "") {
+        return undefined;
+    }
+    if (upper === "*") {
+        return true;
+    }
+    const bound = multiplicityBound(upper);
+    return bound === undefined ? undefined : bound > 1;
+}
+/** The symbols of one level of a model, then those of the levels below it. */
+async function* walkLevels(level) {
+    if (level.length === 0) {
+        return;
+    }
+    yield* level;
+    const children = await Promise.all(level.map((symbol) => symbol.children()));
+    yield* walkLevels(children.flat());
+}
 /** A model the service has parsed and holds under its hash. */
 export class Model {
     connection;
@@ -38,43 +88,87 @@ export class Model {
     hash;
     /** Diagnostics the parse reported, in the order the service reported them. */
     diagnostics;
-    rootSymbol;
+    /** The name of each document this model was parsed from, empty for an adopted model. */
+    documents;
+    rootSymbols;
     ownsConnection;
     constructor(init) {
         this.connection = init.connection;
         this.hash = init.hash;
-        this.rootSymbol = init.root;
+        this.rootSymbols = init.roots ?? [];
         this.diagnostics = init.diagnostics;
         this.ownsConnection = init.ownsConnection;
+        this.documents = init.documents ?? [];
+        this.sourcePath = init.sourcePath;
     }
     /** Adopts a model the service already holds, by the hash it holds it under. */
     static adopt(connection, hash) {
         return new Model({ connection, hash, diagnostics: [], ownsConnection: false });
     }
+    /** Builds a model of several roots, from a ParseSources response. */
+    static fromRoots(connection, hash, roots, diagnostics, options = {}) {
+        return new Model({
+            connection,
+            hash,
+            roots: roots.map((info) => new ModelSymbol(connection, hash, info)),
+            diagnostics,
+            ownsConnection: options.ownsConnection ?? false,
+            ...(options.documents === undefined ? {} : { documents: options.documents }),
+        });
+    }
     /** Whether this model was parsed here, and so knows its root symbol. */
     get parsed() {
-        return this.rootSymbol !== undefined;
+        return this.rootSymbols.length > 0;
     }
     /** The model's root namespace. An adopted model has none: look symbols up by id. */
     get root() {
-        if (this.rootSymbol === undefined) {
+        if (this.rootSymbols.length === 0) {
             throw new OpenSysMLError(`model ${this.hash} was adopted by hash, not parsed here, so its root is unknown; ` +
                 "look a symbol up by its qualified name with symbolById()");
         }
-        return this.rootSymbol;
+        return this.rootSymbols[0];
+    }
+    /** One root per document parsed; the one symbol {@link root} names is the first. */
+    get roots() {
+        return this.rootSymbols;
+    }
+    /** The path this model was loaded from, when it was parsed from a file;
+     * inline content and parseSources models have none, whatever they are named. */
+    sourcePath;
+    /** The error-severity diagnostics the parse reported. */
+    get errors() {
+        return this.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    }
+    /** Whether the parse reported no error-severity diagnostic. */
+    get ok() {
+        return this.errors.length === 0;
+    }
+    /** Raises a {@link ParseError} carrying this model when its parse reported errors. */
+    raiseForErrors() {
+        if (this.hasErrors) {
+            throw new ParseError(this.errors.map((diagnostic) => diagnostic.message).join("\n"), this.errors, {
+                model: this,
+            });
+        }
+        return this;
     }
     /** Parses a source over `connection`. Used by Connection.load / Connection.loads. */
     static async parse(connection, source, options = {}, ownsConnection = false) {
+        if (source.source.case === "content") {
+            requireSourceText("source", source.source.value);
+        }
         if (options.language !== undefined) {
+            requireLanguage(options.language);
             requireCapability(connection.info, CAPABILITY_INLINE_LANGUAGE, upgradeRemedy(CAPABILITY_INLINE_LANGUAGE));
         }
-        if (options.strict === true) {
+        const strictConformance = strictConformanceOf(options);
+        if (strictConformance === true) {
             requireCapability(connection.info, CAPABILITY_STRICT_CONFORMANCE, upgradeRemedy(CAPABILITY_STRICT_CONFORMANCE));
         }
         const response = await callRpc(connection.rpc.parseFile({
             source: source.source,
             ...(options.language === undefined ? {} : { language: options.language }),
-            ...(options.strict === undefined ? {} : { strictConformance: options.strict }),
+            ...(strictConformance === undefined ? {} : { strictConformance }),
         }, connection.callOptions()), source.source.case === "filePath" ? "file" : "model");
         const diagnostics = response.diagnostics.map(decodeDiagnostic);
         if (response.error !== "") {
@@ -86,9 +180,12 @@ export class Model {
         return new Model({
             connection,
             hash: response.modelHash,
-            root: new ModelSymbol(connection, response.modelHash, response.root),
+            roots: [new ModelSymbol(connection, response.modelHash, response.root)],
             diagnostics,
             ownsConnection,
+            ...(source.source.case === "filePath"
+                ? { documents: [source.source.value], sourcePath: source.source.value }
+                : {}),
         });
     }
     /** Whether the parse reported an error-severity diagnostic. */
@@ -97,6 +194,7 @@ export class Model {
     }
     /** Evaluates a SysML expression against this model. */
     async eval(expression, options = {}) {
+        requireString("expression", expression);
         if (options.subject !== undefined) {
             requireCapability(this.connection.info, CAPABILITY_EVALUATE_SUBJECT, upgradeRemedy(CAPABILITY_EVALUATE_SUBJECT));
         }
@@ -113,30 +211,158 @@ export class Model {
     }
     /** Looks a symbol up by short name, FQN or id; throws when the model declares none. */
     async symbol(name) {
-        if (this.looksQualified(name)) {
-            return this.symbolById(name);
+        requireString("name", name);
+        // The empty name names the model itself, as Python's model.get("") does.
+        if (name === "") {
+            return this.parsed ? this.root : this.symbolById(name);
         }
-        // A short name is searched for from the root, which an adopted model has not
-        // got; the service resolves a name the model declares at its top level.
-        if (this.rootSymbol === undefined) {
-            return this.symbolById(name);
+        if (this.looksQualified(name) || !this.parsed) {
+            // A qualified name or a name on an adopted model is resolved by the
+            // service; one it cannot resolve is searched for, as Python's find does.
+            try {
+                return await this.symbolById(name);
+            }
+            catch (error) {
+                if (!(error instanceof SymbolNotFoundError)) {
+                    throw error;
+                }
+            }
+            const qualified = await this.find(name);
+            if (qualified !== undefined) {
+                return qualified;
+            }
+            throw new SymbolNotFoundError(name, await this.nearNames(name));
         }
         const found = await this.find(name);
         if (found === undefined) {
+            // A short name may still be one the service resolves directly, as an id.
+            try {
+                return await this.symbolById(name);
+            }
+            catch (error) {
+                if (!(error instanceof SymbolNotFoundError)) {
+                    throw error;
+                }
+            }
             throw new SymbolNotFoundError(name, await this.nearNames(name));
         }
         return found;
     }
+    /** Writes this model out in `toFormat`. */
+    convert(toFormat, options = {}) {
+        return this.connection.convert(toFormat, { modelHash: this.hash }, options);
+    }
+    /** This model written in SysML notation. */
+    toSysml() {
+        return this.convert("sysml");
+    }
+    /** This model written as RDF Turtle. */
+    toTurtle() {
+        return this.convert("ttl");
+    }
+    /** This model written as API JSON. */
+    toApiJson() {
+        return this.convert("api-json");
+    }
+    /** Runs a SysML v2 API & Services Query over this model. */
+    query(options = {}) {
+        return this.connection.query(this.hash, options);
+    }
+    /** Runs a named document query against this model. */
+    runDocumentQuery(queryId, bindings) {
+        return this.connection.runDocumentQuery(this.hash, queryId, bindings);
+    }
+    /** Renders a named document of this model to Markdown or HTML. */
+    renderDocument(documentId, options = {}) {
+        return this.connection.renderDocument(this.hash, documentId, options);
+    }
+    /** Renders a named view or targeted pseudo-view as diagram data. */
+    renderView(viewName, options = {}) {
+        return this.connection.renderView(this.hash, viewName, options);
+    }
+    /** Exports the lowered graph of an action or state machine of this model as `graphs:1` JSON. */
+    exportGraphs(subject) {
+        return this.connection.exportGraphs(this.hash, subject);
+    }
+    /** Starts an edit of this model, to be applied in one call. */
+    edit() {
+        return this.connection.edit(this.hash);
+    }
+    /** Executes an action definition of this model. */
+    executeAction(actionSymbolId, options = {}) {
+        return this.connection.executeAction(this.hash, actionSymbolId, options);
+    }
+    /** Runs an action once per valid order of its choice points. */
+    exploreAction(actionSymbolId, options = {}) {
+        return this.connection.exploreAction(this.hash, actionSymbolId, options);
+    }
+    /** Executes a state machine of this model. */
+    executeState(stateMachineSymbolId, options = {}) {
+        return this.connection.executeState(this.hash, stateMachineSymbolId, options);
+    }
+    /** Runs a state machine once per valid order of its choice points. */
+    exploreState(stateMachineSymbolId, options = {}) {
+        return this.connection.exploreState(this.hash, stateMachineSymbolId, options);
+    }
+    /** Asks whether a constraint of this model holds. */
+    verifyConstraint(symbolId, options = {}) {
+        return this.connection.verifyConstraint(this.hash, symbolId, options);
+    }
+    /** Asks whether a requirement of this model is satisfied. */
+    verifyRequirement(symbolId, options = {}) {
+        return this.connection.verifyRequirement(this.hash, symbolId, options);
+    }
+    /** Asks whether this model's satisfaction assertions hold. */
+    verifySatisfaction(options = {}) {
+        return this.connection.verifySatisfaction(this.hash, options);
+    }
+    /** Whether every verdict {@link verifySatisfaction} returns holds. */
+    async satisfied(options = {}) {
+        const verdicts = await this.verifySatisfaction(options);
+        return verdicts.every((verdict) => verdict.verdict.kind === "holds");
+    }
+    /** Checks every assertion about an object of this model's parts. */
+    validateInstance(symbolId, options = {}) {
+        return this.connection.validateInstance(this.hash, symbolId, options);
+    }
+    /** Invokes a calculation of this model. */
+    calc(symbolId, options = {}) {
+        return this.connection.calc(this.hash, symbolId, options);
+    }
+    /** Runs an analysis case of this model. */
+    runAnalysis(symbolId, options = {}) {
+        return this.connection.runAnalysis(this.hash, symbolId, options);
+    }
+    /** Runs an analysis case once per valid order of its choice points. */
+    exploreAnalysis(symbolId, options = {}) {
+        return this.connection.exploreAnalysis(this.hash, symbolId, options);
+    }
+    /** Runs an analysis case or calc of this model once per row of a sweep. */
+    runSweep(symbolId, ranges, options = {}) {
+        return this.connection.runSweep(this.hash, symbolId, ranges, options);
+    }
+    /** The diagnostics the service reports for this model now — for a model of
+     * several documents, or one parsed before later edits changed it. */
+    async refreshDiagnostics() {
+        const response = await callRpc(this.connection.rpc.getDiagnostics({ modelHash: this.hash }, this.connection.callOptions()));
+        return response.diagnostics.map(decodeDiagnostic);
+    }
     /** Looks a symbol up by its qualified name, in one call. */
     async symbolById(id) {
+        requireString("id", id);
         const response = await callRpc(this.connection.rpc.getSymbol({ modelHash: this.hash, symbolId: id }, this.connection.callOptions()));
         if (response.symbol === undefined) {
+            // A single call: near names are symbol()'s to compute.
             throw new SymbolNotFoundError(id);
         }
         return new ModelSymbol(this.connection, this.hash, response.symbol);
     }
     /** Looks a symbol up by short name, FQN or id, breadth-first from the root. */
     async find(name) {
+        requireString("name", name);
+        if (name === "") {
+            return this.parsed ? this.root : undefined;
+        }
         for await (const symbol of this.walk()) {
             if (symbol.name === name || symbol.id === name) {
                 return symbol;
@@ -146,18 +372,11 @@ export class Model {
     }
     /** Every symbol of the model, breadth-first from the root. */
     async *walk() {
-        const queue = [this.root];
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (current === undefined) {
-                break;
-            }
-            yield current;
-            queue.push(...(await current.children()));
-        }
+        yield* walkLevels([...this.rootSymbols]);
     }
     /** Instantiates a part or usage, by short name, FQN or id. */
     async instantiate(name) {
+        requireString("name", name);
         const id = this.looksQualified(name) ? name : (await this.symbol(name)).id;
         const response = await callRpc(this.connection.rpc.instantiate({ modelHash: this.hash, symbolId: id }, this.connection.callOptions()));
         if (response.error !== "") {
@@ -179,7 +398,7 @@ export class Model {
     }
     /** Whether a name is one the service can resolve directly, without a search. */
     looksQualified(name) {
-        return name.includes("::") || name === this.rootSymbol?.id;
+        return name.includes("::") || name === this.rootSymbols[0]?.id;
     }
     /** The names of the model closest to one it has not got, best first. */
     async nearNames(name) {
@@ -190,9 +409,16 @@ export class Model {
             if (symbol.name === "") {
                 continue;
             }
-            const score = similarity(name.toLowerCase(), symbol.name.toLowerCase());
-            if (score >= NEAR_ENOUGH) {
-                scored.push({ id: symbol.id, score });
+            // A short name and a qualified one are both candidates, either being
+            // what a mistyped lookup may have meant.
+            for (const candidate of [symbol.name, symbol.id]) {
+                if (candidate === "") {
+                    continue;
+                }
+                const score = similarity(name.toLowerCase(), candidate.toLowerCase());
+                if (score >= NEAR_ENOUGH) {
+                    scored.push({ id: candidate, score });
+                }
             }
             seen += 1;
             if (seen === NEAR_SEARCH_LIMIT) {
@@ -247,7 +473,7 @@ export class ModelSymbol {
         this.multiplicity =
             info.multiplicity === undefined
                 ? undefined
-                : { lower: info.multiplicity.lower, upper: info.multiplicity.upper };
+                : multiplicityOf(info.multiplicity.lower, info.multiplicity.upper);
         this.specializations = info.specializations.map((specialization) => ({
             kind: specialization.kind,
             declared: specialization.declared,
@@ -258,9 +484,9 @@ export class ModelSymbol {
     }
     /** The symbols this one owns, fetched one call each. */
     async children() {
+        const responses = await Promise.all(this.childIds.map((id) => callRpc(this.connection.rpc.getSymbol({ modelHash: this.modelHash, symbolId: id }, this.connection.callOptions()))));
         const children = [];
-        for (const id of this.childIds) {
-            const response = await callRpc(this.connection.rpc.getSymbol({ modelHash: this.modelHash, symbolId: id }, this.connection.callOptions()));
+        for (const response of responses) {
             if (response.symbol !== undefined) {
                 children.push(new ModelSymbol(this.connection, this.modelHash, response.symbol));
             }
@@ -320,7 +546,8 @@ function decodeFeatureValue(value) {
     }
     return { kind: "single", value: decodeValue(value.value), materialized: value.materialized };
 }
-function decodeDiagnostic(diagnostic) {
+/** Reads a wire `Diagnostic` into this client's own {@link ModelDiagnostic}. */
+export function decodeDiagnostic(diagnostic) {
     const span = diagnostic.span;
     return {
         severity: diagnostic.severity,

package/dist/core/package.d.ts

@@ -1,4 +1,6 @@
 /** The npm name this client is published under; package.json's "name" must match it. */
 export declare const PACKAGE_NAME = "@openmbee/opensysml";
+/** The optional npm package that carries the combined WebAssembly module. */
+export declare const WASM_PACKAGE = "@openmbee/opensysml-wasm";
 /** Prefix of the per-platform packages that carry sysml-grpc: `${prefix}<os>-<cpu>`. */
 export declare const PLATFORM_PACKAGE_PREFIX = "@openmbee/opensysml-sysml-grpc-";

package/dist/core/package.js

@@ -1,4 +1,6 @@
 /** The npm name this client is published under; package.json's "name" must match it. */
 export const PACKAGE_NAME = "@openmbee/opensysml";
+/** The optional npm package that carries the combined WebAssembly module. */
+export const WASM_PACKAGE = `${PACKAGE_NAME}-wasm`;
 /** Prefix of the per-platform packages that carry sysml-grpc: `${prefix}<os>-<cpu>`. */
 export const PLATFORM_PACKAGE_PREFIX = `${PACKAGE_NAME}-sysml-grpc-`;

package/dist/core/query.d.ts

@@ -0,0 +1,50 @@
+import type { Query, QueryResponse } from "../generated/sysml_pb.js";
+/** `@type` of the standard's query resource. */
+export declare const TYPE_QUERY = "Query";
+/** `@type` of a single-property constraint. */
+export declare const TYPE_PRIMITIVE_CONSTRAINT = "PrimitiveConstraint";
+/** `@type` of a constraint over nested constraints. */
+export declare const TYPE_COMPOSITE_CONSTRAINT = "CompositeConstraint";
+/** An element a query selected. */
+export declare class QueryElement {
+    /** Qualified name of the element, which is what a scope names it by. */
+    readonly id: string;
+    /** The element's metamodel type, e.g. `PartUsage`. */
+    readonly type: string;
+    /** The selected properties it has; one it does not have is absent. */
+    readonly properties: Readonly<Record<string, string>>;
+    constructor(init: {
+        id: string;
+        type: string;
+        properties: Record<string, string>;
+    });
+    /** Value of a selected property, or `fallback` if the element has none. */
+    get(propertyName: string, fallback?: string): string | undefined;
+    /** The element as the standard's JSON names it: `@id`, `@type`, properties. */
+    asDict(): Record<string, string>;
+    toString(): string;
+}
+/** A scope entry: an element's qualified name or an `@id` reference. */
+export type ScopeEntry = string | {
+    "@id": string;
+};
+/** A constraint, as the standard's JSON writes it. */
+export type ConstraintPayload = Record<string, unknown>;
+/** The standard's `Query` object, as JSON. */
+export type QueryPayload = Record<string, unknown>;
+/** Keyword form of a query, exclusive with `payload`. */
+export interface QueryForm {
+    scope?: readonly ScopeEntry[];
+    select?: readonly string[];
+    where?: ConstraintPayload;
+    /** An OSLC query text, evaluated instead of the structured query. */
+    oslc?: string;
+    /** A query already decoded for the wire; passes through as written. */
+    query?: Query;
+}
+/** Translate a query, given as the standard's JSON or as keywords, to protobuf. */
+export declare function buildQuery(options?: {
+    payload?: QueryPayload;
+} & QueryForm): Query;
+/** The elements a `QueryResponse` reports, as `QueryElement` records. */
+export declare function elementsOf(response: QueryResponse): QueryElement[];