@openmbee/opensysml 0.9.2 → 0.10.1

package/dist/core/conversion.d.ts

@@ -0,0 +1,153 @@
+import type { ModelDiagnostic } from "./errors.js";
+import type { MigrationReport as PbMigrationReport } from "../generated/sysml_pb.js";
+/** SysML v2 / KerML textual notation. `kerml` and `text` name it too. */
+export declare const FORMAT_SYSML = "sysml";
+/** RDF in Turtle syntax. `turtle` and `rdf` name it too. */
+export declare const FORMAT_TURTLE = "ttl";
+/** The OMG API's JSON element form, the same RDF mapping spelled differently. `json` names it too. */
+export declare const FORMAT_API_JSON = "api-json";
+/** Whether a format names SysML v1 in any of its forms: `xmi`, `uml` or `mdzip`, spelt as the service reads them. */
+export declare function isV1(format: string): boolean;
+/** Whether a path's extension names a SysML v1 model: `.xmi`, `.uml` or `.mdzip`. */
+export declare function pathIsV1(path: string): boolean;
+/** Why a v1 model is refused by a conversion, in the words every surface uses. */
+export declare const MIGRATED_NOT_CONVERTED: string;
+/** The fallback wording, for a service too old to send its own notice. */
+export declare const EXPERIMENTAL_NOTICE: string;
+/** The fallback wording for a migration, for a service too old to send its own notice. */
+export declare const MIGRATION_NOTICE: string;
+/** Whether a conversion between these formats uses an experimental mapping. */
+export declare function isExperimental(fromFormat: string, toFormat: string): boolean;
+/** The format to write `path` as, from its extension. */
+export declare function formatOfPath(path: string): string;
+/** A model written out in one of the formats OpenSysML writes. */
+export declare class Conversion {
+    /** The converted model. */
+    readonly content: string;
+    /** Format the source was read as, reported even when inferred. */
+    readonly fromFormat: string;
+    /** Format `content` is written in. */
+    readonly toFormat: string;
+    /** Syntax errors the service tolerated under `tolerateSyntaxErrors`. */
+    readonly diagnostics: readonly ModelDiagnostic[];
+    /** True when the conversion went through the RDF mapping, which is experimental. */
+    readonly experimental: boolean;
+    /** What is experimental about it, in the service's own wording; empty when stable. */
+    readonly experimentalNotice: string;
+    constructor(init: {
+        content: string;
+        fromFormat: string;
+        toFormat: string;
+        diagnostics: readonly ModelDiagnostic[];
+        experimental: boolean;
+        experimentalNotice: string;
+    });
+    toString(): string;
+    get length(): number;
+}
+/** What a migration may be asked for beside the target format. */
+export interface MigrateOptions {
+    /** The v1 form the source is in: `xmi`, `uml` or `mdzip`. Required for inline content; a path's extension names it otherwise. */
+    fromFormat?: string;
+    /** Answer every element's verdict and the report text `-migration-report` writes. */
+    report?: boolean;
+    /** Answer the JSON index of result snapshots `-migration-results` writes. */
+    results?: boolean;
+    /** Path of an MTIP layout file the service reads, as `-layout` names it. */
+    layoutPath?: string;
+    /** An MTIP layout carried inline; at most one of `layoutPath` and `layoutContent`. */
+    layoutContent?: string;
+    /** Prefix the migrated model refers to its image files with, as `-image-base-url` sets it. */
+    imageBaseUrl?: string;
+    /** Refuse a model with an unmapped element rather than reporting it, as `-strict` does. */
+    strict?: boolean;
+}
+/** One SysML v1 element's verdict in a migration. */
+export interface MigrationEntry {
+    /** The element's `xmi:id`. */
+    readonly id: string;
+    /** Its v1 metaclass, with its applied stereotypes. */
+    readonly kind: string;
+    /** Its qualified name in the v1 model. */
+    readonly name: string;
+    /** The v2 element it was written as, when it was written. */
+    readonly target: string;
+    /** `mapped`, `approximated`, `unmapped` or `skipped`. */
+    readonly verdict: string;
+    /** Why the verdict is what it is, in the migrator's words. */
+    readonly note: string;
+}
+/**
+ * The account a migration gives of itself: what became of every element. The
+ * summary and the four counts always come back; `entries` and `text` when the
+ * migration was asked for the report.
+ */
+export declare class MigrationReport {
+    /** The v1 model migrated, as the service named it. */
+    readonly source: string;
+    /** The tool that exported it, as its XMI says. */
+    readonly exporter: string;
+    /** The one-line account: `migrated N element(s): … mapped, … approximated, … unmapped`. */
+    readonly summary: string;
+    /** Elements with a faithful v2 form. */
+    readonly mapped: number;
+    /** Elements written in a v2 form that is not quite theirs. */
+    readonly approximated: number;
+    /** Elements with no v2 form, left out and reported. */
+    readonly unmapped: number;
+    /** Elements the migration does not consider: profile, library and notation-only content, and elements nothing refers to. */
+    readonly skipped: number;
+    /** Every element's verdict, when the report was asked for. */
+    readonly entries: readonly MigrationEntry[];
+    /** The report as `-migration-report` writes it, when asked for; else empty. */
+    readonly text: string;
+    constructor(init: {
+        source: string;
+        exporter: string;
+        summary: string;
+        mapped: number;
+        approximated: number;
+        unmapped: number;
+        skipped: number;
+        entries: readonly MigrationEntry[];
+        text: string;
+    });
+    /** The entries with `verdict`: `mapped`, `approximated`, `unmapped` or `skipped`. */
+    byVerdict(verdict: string): MigrationEntry[];
+    toString(): string;
+}
+/** Reads the report the service sent. */
+export declare function migrationReportOf(message: PbMigrationReport | undefined): MigrationReport;
+/** A SysML v1 model migrated to one of the formats OpenSysML writes. */
+export declare class Migration {
+    /** The migrated model. */
+    readonly content: string;
+    /** The v1 form read, canonically `xmi`: `uml` and `mdzip` name the same reader. */
+    readonly fromFormat: string;
+    /** Format `content` is written in. */
+    readonly toFormat: string;
+    /** What became of every element; the summary and the counts come back with every migration. */
+    readonly report: MigrationReport;
+    /** The JSON index of the result snapshots the v1 tool stored, as `-migration-results` writes it, when asked for; else empty. */
+    readonly results: string;
+    /** Image files the model's diagrams embed, by the relative path `content` refers to them with. */
+    readonly files: ReadonlyMap<string, Uint8Array>;
+    /** The path the v1 model was read from, as given; empty when it was inline content. */
+    readonly sourcePath: string;
+    /** Always true: the migration is experimental. */
+    readonly experimental = true;
+    /** What is experimental about it, in the service's own wording. */
+    readonly experimentalNotice: string;
+    constructor(init: {
+        content: string;
+        fromFormat: string;
+        toFormat: string;
+        report: MigrationReport;
+        results: string;
+        files: ReadonlyMap<string, Uint8Array>;
+        sourcePath: string;
+        experimentalNotice: string;
+    });
+    toString(): string;
+    get length(): number;
+}

package/dist/core/conversion.js

@@ -0,0 +1,191 @@
+// Writing a model back out, in SysML notation or RDF Turtle. The formats are
+// named as the `sysml` CLI's -from/-to name them.
+import { byCodeUnit } from "./capabilities.js";
+/** SysML v2 / KerML textual notation. `kerml` and `text` name it too. */
+export const FORMAT_SYSML = "sysml";
+/** RDF in Turtle syntax. `turtle` and `rdf` name it too. */
+export const FORMAT_TURTLE = "ttl";
+/** The OMG API's JSON element form, the same RDF mapping spelled differently. `json` names it too. */
+export const FORMAT_API_JSON = "api-json";
+const TURTLE_NAMES = new Set(["ttl", "turtle", "rdf"]);
+const API_JSON_NAMES = new Set(["api-json", "json"]);
+const XMI_NAMES = new Set(["xmi", "uml", "mdzip"]);
+/** Whether a format names SysML v1 in any of its forms: `xmi`, `uml` or `mdzip`, spelt as the service reads them. */
+export function isV1(format) {
+    return XMI_NAMES.has(format.trim().toLowerCase());
+}
+/** Whether a path's extension names a SysML v1 model: `.xmi`, `.uml` or `.mdzip`. */
+export function pathIsV1(path) {
+    const dot = path.lastIndexOf(".");
+    return dot !== -1 && XMI_NAMES.has(path.slice(dot + 1).toLowerCase());
+}
+/** Why a v1 model is refused by a conversion, in the words every surface uses. */
+export const MIGRATED_NOT_CONVERTED = "is a SysML v1 model, which is migrated, not converted: every element is mapped, " +
+    "approximated or left unmapped and reported element by element";
+/** The fallback wording, for a service too old to send its own notice. */
+export const EXPERIMENTAL_NOTICE = "RDF conversion — Turtle and the API's JSON element form alike — is experimental: the " +
+    "mapping covers model structure and the behavior its bodies state, refuses what it " +
+    "cannot write back, and its vocabulary may change without a compatibility path; see " +
+    "docs/reference/rdf-mapping.md § Status";
+/** The fallback wording for a migration, for a service too old to send its own notice. */
+export const MIGRATION_NOTICE = "SysML v1 migration is experimental: the mapping covers structure, ports and connectors, " +
+    "requirements, constraints, instances and allocations, reports every element it approximates " +
+    "or leaves behind, and what it writes for a v1 element may change without a compatibility " +
+    "path; see docs/reference/sysml-v1-migration.md § Status";
+/** Whether a conversion between these formats uses an experimental mapping. */
+export function isExperimental(fromFormat, toFormat) {
+    return (TURTLE_NAMES.has(fromFormat) ||
+        TURTLE_NAMES.has(toFormat) ||
+        API_JSON_NAMES.has(fromFormat) ||
+        API_JSON_NAMES.has(toFormat) ||
+        XMI_NAMES.has(fromFormat));
+}
+const EXTENSIONS = new Map([
+    [".sysml", FORMAT_SYSML],
+    [".kerml", FORMAT_SYSML],
+    [".ttl", FORMAT_TURTLE],
+    [".turtle", FORMAT_TURTLE],
+    [".json", FORMAT_API_JSON],
+]);
+/** The format to write `path` as, from its extension. */
+export function formatOfPath(path) {
+    const dot = path.lastIndexOf(".");
+    const ext = dot === -1 ? "" : path.slice(dot).toLowerCase();
+    const format = EXTENSIONS.get(ext);
+    if (format === undefined) {
+        const known = [...EXTENSIONS.keys()].sort(byCodeUnit).join(", ");
+        throw new RangeError(`cannot tell the format to write ${JSON.stringify(path)} as: expected one of ${known}, ` +
+            `or pass toFormat explicitly`);
+    }
+    return format;
+}
+/** A model written out in one of the formats OpenSysML writes. */
+export class Conversion {
+    /** The converted model. */
+    content;
+    /** Format the source was read as, reported even when inferred. */
+    fromFormat;
+    /** Format `content` is written in. */
+    toFormat;
+    /** Syntax errors the service tolerated under `tolerateSyntaxErrors`. */
+    diagnostics;
+    /** True when the conversion went through the RDF mapping, which is experimental. */
+    experimental;
+    /** What is experimental about it, in the service's own wording; empty when stable. */
+    experimentalNotice;
+    constructor(init) {
+        this.content = init.content;
+        this.fromFormat = init.fromFormat;
+        this.toFormat = init.toFormat;
+        this.diagnostics = init.diagnostics;
+        this.experimental = init.experimental;
+        this.experimentalNotice = init.experimentalNotice;
+    }
+    toString() {
+        return this.content;
+    }
+    get length() {
+        return this.content.length;
+    }
+}
+/**
+ * The account a migration gives of itself: what became of every element. The
+ * summary and the four counts always come back; `entries` and `text` when the
+ * migration was asked for the report.
+ */
+export class MigrationReport {
+    /** The v1 model migrated, as the service named it. */
+    source;
+    /** The tool that exported it, as its XMI says. */
+    exporter;
+    /** The one-line account: `migrated N element(s): … mapped, … approximated, … unmapped`. */
+    summary;
+    /** Elements with a faithful v2 form. */
+    mapped;
+    /** Elements written in a v2 form that is not quite theirs. */
+    approximated;
+    /** Elements with no v2 form, left out and reported. */
+    unmapped;
+    /** Elements the migration does not consider: profile, library and notation-only content, and elements nothing refers to. */
+    skipped;
+    /** Every element's verdict, when the report was asked for. */
+    entries;
+    /** The report as `-migration-report` writes it, when asked for; else empty. */
+    text;
+    constructor(init) {
+        this.source = init.source;
+        this.exporter = init.exporter;
+        this.summary = init.summary;
+        this.mapped = init.mapped;
+        this.approximated = init.approximated;
+        this.unmapped = init.unmapped;
+        this.skipped = init.skipped;
+        this.entries = init.entries;
+        this.text = init.text;
+    }
+    /** The entries with `verdict`: `mapped`, `approximated`, `unmapped` or `skipped`. */
+    byVerdict(verdict) {
+        return this.entries.filter((entry) => entry.verdict === verdict);
+    }
+    toString() {
+        return this.text !== "" ? this.text : this.summary;
+    }
+}
+/** Reads the report the service sent. */
+export function migrationReportOf(message) {
+    return new MigrationReport({
+        source: message?.source ?? "",
+        exporter: message?.exporter ?? "",
+        summary: message?.summary ?? "",
+        mapped: message?.mapped ?? 0,
+        approximated: message?.approximated ?? 0,
+        unmapped: message?.unmapped ?? 0,
+        skipped: message?.skipped ?? 0,
+        entries: (message?.entries ?? []).map((entry) => ({
+            id: entry.id,
+            kind: entry.kind,
+            name: entry.name,
+            target: entry.target,
+            verdict: entry.verdict,
+            note: entry.note,
+        })),
+        text: message?.text ?? "",
+    });
+}
+/** A SysML v1 model migrated to one of the formats OpenSysML writes. */
+export class Migration {
+    /** The migrated model. */
+    content;
+    /** The v1 form read, canonically `xmi`: `uml` and `mdzip` name the same reader. */
+    fromFormat;
+    /** Format `content` is written in. */
+    toFormat;
+    /** What became of every element; the summary and the counts come back with every migration. */
+    report;
+    /** The JSON index of the result snapshots the v1 tool stored, as `-migration-results` writes it, when asked for; else empty. */
+    results;
+    /** Image files the model's diagrams embed, by the relative path `content` refers to them with. */
+    files;
+    /** The path the v1 model was read from, as given; empty when it was inline content. */
+    sourcePath;
+    /** Always true: the migration is experimental. */
+    experimental = true;
+    /** What is experimental about it, in the service's own wording. */
+    experimentalNotice;
+    constructor(init) {
+        this.content = init.content;
+        this.fromFormat = init.fromFormat;
+        this.toFormat = init.toFormat;
+        this.report = init.report;
+        this.results = init.results;
+        this.files = init.files;
+        this.sourcePath = init.sourcePath;
+        this.experimentalNotice = init.experimentalNotice;
+    }
+    toString() {
+        return this.content;
+    }
+    get length() {
+        return this.content.length;
+    }
+}

package/dist/core/document.d.ts

@@ -0,0 +1,188 @@
+import type { DocumentEvent as PbDocumentEvent, DocumentQueryBinding, RunDocumentQueryResponse } from "../generated/sysml_pb.js";
+import { type SysMLValue } from "./values.js";
+/** Whether a wire binding sends an Integer beyond int64, which needs `big_int_values`. */
+export declare function bindingHoldsBigInt(binding: DocumentQueryBinding): boolean;
+/** Whether a wire binding sends an exact Rational, which needs `rational_values`. */
+export declare function bindingHoldsRational(binding: DocumentQueryBinding): boolean;
+/** Rewrites each Rational a binding sends that a double holds exactly as that double, for a service without `rational_values`. */
+export declare function bindingRationalsAsReals(binding: DocumentQueryBinding): void;
+/** A model element, named by qualified name. */
+export declare class ElementRef {
+    /** Qualified name of the element. */
+    readonly id: string;
+    /** Metamodel type name; empty when bound by a caller, reported when answered. */
+    readonly type: string;
+    constructor(id: string, type?: string);
+    toString(): string;
+}
+/** An object the service holds for the model, created by `instantiate`. */
+export declare class ObjectRef {
+    /** The object's id, as `instantiate` answered it. */
+    readonly id: bigint;
+    /** The object by the label a session reaches it under. */
+    readonly path: string;
+    /** The usage the object is held under; reported when answered, ignored when bound. */
+    readonly element: ElementRef | undefined;
+    constructor(options?: {
+        id?: bigint | number;
+        path?: string;
+        element?: ElementRef;
+    });
+    toString(): string;
+}
+/** A row a `Verdicts` query answered: an assertion checked on one object. Answered only. */
+export declare class DocumentVerdict {
+    readonly assertion: ElementRef;
+    /** "constraint", "requirement", "satisfaction" or "verification". */
+    readonly kind: string;
+    /** The assertion as written. */
+    readonly text: string;
+    /** The object checked, named from the element the query was bound to. */
+    readonly path: string;
+    /** "holds", "violated" or "undecided". */
+    readonly status: string;
+    /** The condition that evaluated to false, as written; empty otherwise. */
+    readonly condition: string;
+    /** Why the assertion is violated or undecided; empty when it holds. */
+    readonly reason: string;
+    /** Verdict kinds of the verification cases verifying the row's requirement. */
+    readonly verification: readonly string[];
+    constructor(init: {
+        assertion: ElementRef;
+        kind: string;
+        text: string;
+        path: string;
+        status: string;
+        condition?: string;
+        reason?: string;
+        verification?: readonly string[];
+    });
+    toString(): string;
+}
+/** A row a `States` query answered: one active leaf state of one object. Answered only. */
+export declare class DocumentState {
+    /** The object whose state machine the row reads. */
+    readonly object: ObjectRef;
+    /** The exhibited state usage's name, or the state def's. */
+    readonly machine: string;
+    /** The active leaf state's own name. */
+    readonly name: string;
+    /** The leaf's path from the machine's top level. */
+    readonly path: string;
+    /** The state usage's declaration. */
+    readonly state: ElementRef | undefined;
+    /** The orthogonal region declaring the leaf; empty when not in one. */
+    readonly region: string;
+    /** The active composite states around the leaf, outermost first. */
+    readonly enclosing: readonly string[];
+    constructor(init: {
+        object: ObjectRef;
+        machine: string;
+        name: string;
+        path: string;
+        state?: ElementRef;
+        region?: string;
+        enclosing?: readonly string[];
+    });
+    toString(): string;
+}
+/** A row an `Events` query answered: one record of a session's trace. Answered only. */
+export declare class DocumentEvent {
+    /** "accept", "send", "transition", "entry", "exit", "do", "choice", "guard" or "terminate". */
+    readonly kind: string;
+    /** The instant the record was written at: a quantity, an int or a real. */
+    readonly time: DocumentValue;
+    /** The object the record is about; undefined for a record of the run as a whole. */
+    readonly object: ObjectRef | undefined;
+    /** The state machine the record is about. */
+    readonly machine: string;
+    /** The state entered, exited or run (entry, exit and do records). */
+    readonly state: string;
+    /** The transition's source state. */
+    readonly fromState: string;
+    /** The transition's target state. */
+    readonly toState: string;
+    /** The object a send was delivered to. */
+    readonly target: ObjectRef | undefined;
+    /** The accepted or sent event's type name. */
+    readonly event: string;
+    /** The accept's payload, one `name = value` text per attribute. */
+    readonly payload: readonly string[];
+    /** What a choice drew from, in order. */
+    readonly alternatives: readonly string[];
+    /** The alternative the choice took. */
+    readonly taken: string;
+    /** The record as the trace prints it. */
+    readonly text: string;
+    constructor(init: {
+        kind: string;
+        time: DocumentValue;
+        text: string;
+        object?: ObjectRef;
+        machine?: string;
+        state?: string;
+        fromState?: string;
+        toState?: string;
+        target?: ObjectRef;
+        event?: string;
+        payload?: readonly string[];
+        alternatives?: readonly string[];
+        taken?: string;
+    });
+    toString(): string;
+}
+export type DocumentValue = ElementRef | ObjectRef | DocumentVerdict | DocumentState | DocumentEvent | string | bigint | number | boolean | {
+    kind: "infinity";
+} | Extract<SysMLValue, {
+    kind: "rational";
+}> | ({
+    kind: "quantity";
+} & Extract<SysMLValue, {
+    kind: "quantity";
+}>);
+/** What `bindings` accepts for one parameter: one value or several. */
+export type BindingValues = DocumentValue | readonly DocumentValue[];
+/** One selected element and its projected cells, one per column. */
+export declare class DocumentRow {
+    /** The selected element itself, or the usage the row's object is held under. */
+    readonly element: ElementRef;
+    /** One value sequence per column, in column order. */
+    readonly cells: readonly (readonly DocumentValue[])[];
+    /** The verdict a `Verdicts` row carries; undefined for any other row. */
+    readonly verdict: DocumentVerdict | undefined;
+    /** The object a row over held objects is about; undefined for any other row. */
+    readonly object: ObjectRef | undefined;
+    /** The state a `States` row carries; undefined for any other row. */
+    readonly state: DocumentState | undefined;
+    /** The event an `Events` row carries; undefined for any other row. */
+    readonly event: DocumentEvent | undefined;
+    constructor(init: {
+        element: ElementRef;
+        cells: readonly (readonly DocumentValue[])[];
+        verdict?: DocumentVerdict;
+        object?: ObjectRef;
+        state?: DocumentState;
+        event?: DocumentEvent;
+    });
+    /** The values of the `index`-th column. */
+    cell(index: number): readonly DocumentValue[];
+}
+/** A document query's answer: projected columns and typed rows, in the engine's order. */
+export declare class DocumentQueryResult {
+    /** Projected property names, in projection order. */
+    readonly columns: readonly string[];
+    /** The selected rows, in the engine's order. */
+    readonly rows: readonly DocumentRow[];
+    constructor(init: {
+        columns: readonly string[];
+        rows: readonly DocumentRow[];
+    });
+    get length(): number;
+    [Symbol.iterator](): Iterator<DocumentRow>;
+}
+/** Translate a bindings mapping into the RPC's protobuf. */
+export declare function buildBindings(bindings: Readonly<Record<string, BindingValues>> | undefined): DocumentQueryBinding[];
+/** Decode a `RunDocumentQueryResponse` into a `DocumentQueryResult`. */
+export declare function documentResult(response: RunDocumentQueryResponse): DocumentQueryResult;
+/** Decode a run-trace event using the document query's event conversion. */
+export declare function documentEventOf(event: PbDocumentEvent): DocumentEvent;