@openmbee/opensysml 0.9.1 → 0.10.0

package/dist/node/generate.js

@@ -0,0 +1,757 @@
+// Generate statically typed TypeScript classes from a SysML model.
+//
+// Usage: `opensysml-generate model.sysml -o model_types.ts`
+//
+// The generated module contains one class per SysML definition, deriving from
+// TypedObject, with one getter per feature. Emission is deterministic —
+// symbols are ordered by fully-qualified name and nothing environment-
+// dependent is written — so the output can be committed as a golden file, and
+// --check can gate that it is current.
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import { CAPABILITY_TYPE_FACTS, MissingCapabilityError, requireCapability, } from "../core/capabilities.js";
+import { PACKAGE_NAME } from "../core/package.js";
+import { connect } from "./index.js";
+export const GENERATED_HEADER = "// Generated by opensysml-generate. Do not edit.";
+// Decoder for a feature whose SysML type has no sound TypeScript type.
+const OBJECT_DECODER = "_t.asObject";
+// Emission schema, bumped when this generator's output changes for an
+// unchanged model. Not the opensysml release version, which would churn
+// every module.
+export const GENERATOR_VERSION = "5";
+// The stamp hashes the model source client-side. A path, a timestamp or the
+// service version would churn without the module's content changing.
+export const MODEL_HASH_ALGORITHM = "sha256";
+// What a module rendered without the model source says, so it cannot be
+// mistaken for one stamped with a real hash.
+export const UNSTAMPED = "unstamped";
+// Definition kinds get a class; these usage kinds become properties on the
+// enclosing class. Behavioral and connector usages (action, state, calc,
+// constraint, requirement, connection, flow, interface, allocation, case) are
+// not instance feature values and are skipped.
+const FEATURE_KINDS = new Set([
+    "attributeusage",
+    "referenceusage",
+    "partusage",
+    "itemusage",
+    "occurrenceusage",
+    "individualusage",
+    "portusage",
+    "enumusage",
+]);
+// The generalization edges that make one element a kind of another. A typing
+// edge is the element's type, not a supertype of it, so it is not one of these.
+const GENERALIZATION_KINDS = new Set(["specializes", "subsets", "redefines"]);
+// How far a generalization chain is followed for a fact a declaration leaves out.
+const MAX_GENERALIZATION_DEPTH = 16;
+const PRIMITIVE_TYPES = new Map([
+    ["Boolean", { annotation: "boolean", decoder: "_t.asBoolean" }],
+    ["String", { annotation: "string", decoder: "_t.asString" }],
+    ["Natural", { annotation: "bigint", decoder: "_t.asInt" }],
+    ["Integer", { annotation: "bigint", decoder: "_t.asInt" }],
+    ["Rational", { annotation: "_t.RationalValue", decoder: "_t.asRational" }],
+    ["Real", { annotation: "number", decoder: "_t.asReal" }],
+    ["Complex", { annotation: "_t.ComplexValue", decoder: "_t.asComplex" }],
+]);
+// Library scalars with no sound TypeScript counterpart, mapped to object:
+// Number is the supertype of every numeric scalar, so a Number slot may hold
+// any of them.
+const UNMAPPED_PRIMITIVES = new Set(["Number"]);
+// Members TypedObject itself provides; a getter of the same name would shadow
+// the machinery the accessors use, so such a feature is renamed.
+const RESERVED_MEMBERS = new Set([
+    "instance",
+    "fromInstance",
+    "unchecked",
+    "sysmlId",
+    "resolver",
+]);
+// Words TypeScript and JavaScript reserve; a getter or class may not be one.
+const RESERVED_WORDS = new Set([
+    "break", "case", "catch", "class", "const", "continue", "debugger",
+    "default", "delete", "do", "else", "enum", "export", "extends", "false",
+    "finally", "for", "function", "if", "implements", "import", "in",
+    "instanceof", "interface", "let", "new", "null", "package", "private",
+    "protected", "public", "return", "static", "super", "switch", "this",
+    "throw", "true", "try", "typeof", "undefined", "var", "void", "while",
+    "with", "yield",
+]);
+/** Whether a symbol kind declares a type, e.g. `partDef` or `metaclass`. */
+export function isDefinitionKind(kind) {
+    const lowered = kind.toLowerCase();
+    return lowered.endsWith("def") || lowered === "metaclass";
+}
+/** Whether a symbol kind is a usage exposed as an instance feature. */
+export function isFeatureKind(kind) {
+    return FEATURE_KINDS.has(kind.toLowerCase());
+}
+/** One SysML definition to emit as a class. */
+export class Definition {
+    id;
+    name;
+    kind;
+    specializations;
+    features;
+    constructor(init) {
+        this.id = init.id;
+        this.name = init.name;
+        this.kind = init.kind;
+        this.specializations = init.specializations ?? [];
+        this.features = init.features ?? [];
+    }
+    /** FQNs of what this definition specializes, subsets or redefines, in
+     * declaration order, without repetition. */
+    get baseIds() {
+        const ordered = [];
+        for (const spec of this.specializations) {
+            if (GENERALIZATION_KINDS.has(spec.kind) && spec.targetId !== "" && !ordered.includes(spec.targetId)) {
+                ordered.push(spec.targetId);
+            }
+        }
+        return ordered;
+    }
+}
+/** Collect the definitions in one or more symbol trees, sorted by FQN, each
+ * feature taking the type and multiplicity it inherits. */
+export async function collectDefinitions(...roots) {
+    const definitions = [];
+    const factsById = new Map();
+    await Promise.all(roots.map((root) => collect(root, definitions, factsById)));
+    const resolved = definitions.map((definition) => withInheritedFacts(definition, factsById));
+    resolved.sort((left, right) => left.id.localeCompare(right.id));
+    return resolved;
+}
+async function collect(symbol, out, factsById) {
+    const children = await symbol.children();
+    factsById.set(symbol.id, {
+        id: symbol.id,
+        name: symbol.name,
+        kind: symbol.kind,
+        type: symbol.type,
+        multiplicity: symbol.multiplicity,
+        specializations: symbol.specializations ?? [],
+    });
+    if (isDefinitionKind(symbol.kind)) {
+        const featureChildren = children
+            .filter((child) => isFeatureKind(child.kind))
+            .sort((left, right) => left.id.localeCompare(right.id));
+        out.push(new Definition({
+            id: symbol.id,
+            name: symbol.name,
+            kind: symbol.kind,
+            specializations: symbol.specializations,
+            features: featureChildren.map((child) => ({
+                id: child.id,
+                name: child.name,
+                kind: child.kind,
+                type: child.type,
+                multiplicity: child.multiplicity,
+            })),
+        }));
+    }
+    await Promise.all(children.map((child) => collect(child, out, factsById)));
+}
+function withInheritedFacts(definition, factsById) {
+    return new Definition({
+        id: definition.id,
+        name: definition.name,
+        kind: definition.kind,
+        specializations: definition.specializations,
+        features: definition.features.map((feature) => resolvedFeature(feature, factsById)),
+    });
+}
+function resolvedFeature(feature, factsById) {
+    const owner = factsById.get(feature.id);
+    const specializations = owner?.specializations ?? [];
+    let typeFacts = feature.type;
+    if (!namesAType(typeFacts)) {
+        const inherited = inheritedFact({ specializations }, factsById, (other) => (namesAType(other.type) ? other.type : undefined));
+        if (inherited !== undefined) {
+            typeFacts = mergedType(typeFacts, inherited);
+        }
+    }
+    const multiplicity = feature.multiplicity ?? inheritedFact({ specializations }, factsById, (other) => other.multiplicity);
+    if (typeFacts === feature.type && multiplicity === feature.multiplicity) {
+        return feature;
+    }
+    return { ...feature, type: typeFacts, multiplicity };
+}
+function inheritedFact(facts, factsById, pick, depth = 0) {
+    if (depth >= MAX_GENERALIZATION_DEPTH) {
+        return undefined;
+    }
+    for (const spec of facts.specializations) {
+        if (!GENERALIZATION_KINDS.has(spec.kind) || spec.targetId === "") {
+            continue;
+        }
+        const target = factsById.get(spec.targetId);
+        if (target === undefined) {
+            continue;
+        }
+        const found = pick(target);
+        if (found !== undefined) {
+            return found;
+        }
+        const deeper = inheritedFact(target, factsById, pick, depth + 1);
+        if (deeper !== undefined) {
+            return deeper;
+        }
+    }
+    return undefined;
+}
+function namesAType(typeFacts) {
+    return typeFacts !== undefined && (typeFacts.resolvedId !== "" || typeFacts.declared !== "");
+}
+function mergedType(own, inherited) {
+    if (own === undefined) {
+        return inherited;
+    }
+    return {
+        declared: inherited.declared,
+        resolvedId: inherited.resolvedId,
+        resolvedKind: inherited.resolvedKind,
+        primitive: own.primitive !== "" ? own.primitive : inherited.primitive,
+        primitiveSource: own.primitiveSource !== "" ? own.primitiveSource : inherited.primitiveSource,
+        quantity: own.quantity || inherited.quantity,
+        unit: own.unit !== "" ? own.unit : inherited.unit,
+    };
+}
+/** Map definition FQN → TypeScript class name.
+ *
+ * A simple name declared by more than one definition is qualified with its
+ * owning path so that every generated class name is unique and stable. */
+export function classNames(definitions) {
+    const byName = new Map();
+    for (const definition of definitions) {
+        const simple = identifier(definition.name);
+        const group = byName.get(simple) ?? [];
+        group.push(definition);
+        byName.set(simple, group);
+    }
+    const names = new Map();
+    for (const [simple, group] of byName) {
+        if (group.length === 1) {
+            names.set(group[0].id, simple);
+            continue;
+        }
+        for (const definition of group) {
+            names.set(definition.id, definition.id.split("::").map(identifier).join("_"));
+        }
+    }
+    return names;
+}
+function identifier(name) {
+    let cleaned = Array.from(name)
+        .map((char) => (/[\p{L}\p{N}_]/u.test(char) ? char : "_"))
+        .join("");
+    if (cleaned === "" || /^\d/.test(cleaned)) {
+        cleaned = `_${cleaned}`;
+    }
+    if (RESERVED_WORDS.has(cleaned)) {
+        cleaned += "_";
+    }
+    return cleaned;
+}
+function literal(text) {
+    return JSON.stringify(text);
+}
+/** TypeScript name of the getter for a feature; the SysML feature name is unchanged. */
+export function propertyName(name) {
+    let ident = identifier(name);
+    if (RESERVED_MEMBERS.has(ident)) {
+        ident += "_";
+    }
+    return ident;
+}
+/** Map the type of a single value to a TypeScript annotation and decoder. */
+export function elementType(typeFacts, names) {
+    if (typeFacts === undefined) {
+        return { annotation: "_t.SysMLValue", decoder: OBJECT_DECODER, comment: "untyped feature" };
+    }
+    // A value written with a unit is a magnitude and that unit, whatever library
+    // scalar the magnitude reduces to, so it is typed before the primitive below.
+    if (typeFacts.quantity && typeFacts.unit !== "") {
+        return {
+            annotation: "_t.Quantity",
+            decoder: "_t.asQuantity",
+            comment: `quantity in [${typeFacts.unit}]`,
+        };
+    }
+    if (typeFacts.quantity) {
+        // A quantity value type constrains the type, not what is written for it.
+        return {
+            annotation: "_t.SysMLValue",
+            decoder: OBJECT_DECODER,
+            comment: "quantity value type, no unit written",
+        };
+    }
+    // A definition reducing to a library scalar holds that scalar, not an
+    // instance, even when it has a generated class of its own.
+    const primitive = PRIMITIVE_TYPES.get(typeFacts.primitive);
+    if (primitive !== undefined) {
+        return { annotation: primitive.annotation, decoder: primitive.decoder, comment: "" };
+    }
+    // An enumeration-typed feature holds one of the enumeration's literals, a
+    // value of its own rather than an instance of the generated class.
+    if (typeFacts.resolvedKind === "enumDef") {
+        return { annotation: "_t.EnumValue", decoder: "_t.asEnum", comment: "" };
+    }
+    const generated = names.get(typeFacts.resolvedId);
+    if (typeFacts.resolvedId !== "" && generated !== undefined) {
+        return { annotation: generated, decoder: `_t.asTyped(${generated})`, comment: "" };
+    }
+    if (UNMAPPED_PRIMITIVES.has(typeFacts.primitive)) {
+        return {
+            annotation: "_t.SysMLValue",
+            decoder: OBJECT_DECODER,
+            comment: `SysML ${typeFacts.primitive} has no TypeScript counterpart`,
+        };
+    }
+    if (typeFacts.resolvedId !== "") {
+        return {
+            annotation: "_t.SysMLValue",
+            decoder: OBJECT_DECODER,
+            comment: `SysML type ${typeFacts.resolvedId} has no generated class`,
+        };
+    }
+    if (typeFacts.declared !== "") {
+        return {
+            annotation: "_t.SysMLValue",
+            decoder: OBJECT_DECODER,
+            comment: `unresolved SysML type ${typeFacts.declared}`,
+        };
+    }
+    return { annotation: "_t.SysMLValue", decoder: OBJECT_DECODER, comment: "untyped feature" };
+}
+const EMPTY_MULTIPLICITY = { lower: "", upper: "" };
+function isCollection(multiplicity) {
+    if (multiplicity.upper === "") {
+        return undefined;
+    }
+    if (multiplicity.upper === "*") {
+        return true;
+    }
+    const upper = Number.parseInt(multiplicity.upper, 10);
+    return Number.isNaN(upper) ? undefined : upper > 1;
+}
+function isOptional(multiplicity) {
+    if (multiplicity.lower === "") {
+        return undefined;
+    }
+    const lower = Number.parseInt(multiplicity.lower, 10);
+    return Number.isNaN(lower) ? undefined : lower === 0;
+}
+/** Map a feature to its TypeScript annotation, decoder and accessor, honoring multiplicity. */
+export function featureType(feature, names) {
+    const element = elementType(feature.type, names);
+    const multiplicity = feature.multiplicity ?? EMPTY_MULTIPLICITY;
+    if (isCollection(multiplicity)) {
+        return { ...element, annotation: `readonly ${element.annotation}[]` };
+    }
+    if (isOptional(multiplicity)) {
+        return { ...element, annotation: `${element.annotation} | undefined` };
+    }
+    return element;
+}
+function accessor(feature) {
+    const multiplicity = feature.multiplicity ?? EMPTY_MULTIPLICITY;
+    if (isCollection(multiplicity)) {
+        return "_t.listFeatureValue";
+    }
+    if (isOptional(multiplicity)) {
+        return "_t.optionalFeatureValue";
+    }
+    return "_t.featureValue";
+}
+/** Hash of the model source a generated module was produced from.
+ *
+ * Newlines are normalized so the same model checked out with CRLF endings
+ * stamps identically; nothing else about the text is interpreted. */
+export function modelStamp(sourceText) {
+    const normalized = sourceText.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+    return createHash(MODEL_HASH_ALGORITHM).update(normalized, "utf8").digest("hex");
+}
+function hashLiteral(stamp) {
+    return stamp !== undefined ? `${MODEL_HASH_ALGORITHM}:${stamp}` : UNSTAMPED;
+}
+/** Render a complete, importable TypeScript module for `definitions`.
+ *
+ * `stamp` is the {@link modelStamp} of the model source, recorded in the
+ * module so a reader — and the `--check` gate — can tell what it was generated
+ * from. Without one the module says `unstamped` rather than claim a hash it
+ * does not have. */
+export function renderModule(definitions, stamp) {
+    const names = classNames(definitions);
+    const lines = [
+        GENERATED_HEADER,
+        "// Typed views over SysML definitions, generated from a parsed model.",
+        "",
+        `import * as _t from ${literal(PACKAGE_NAME)};`,
+        "",
+        `export const SYSML_GENERATOR_VERSION = ${literal(GENERATOR_VERSION)};`,
+        `export const SYSML_MODEL_HASH = ${literal(hashLiteral(stamp))};`,
+    ];
+    if (definitions.length === 0) {
+        lines.push("");
+        return lines.join("\n");
+    }
+    const plan = basePlan(definitions);
+    const linearizations = plan.linearizations;
+    for (const definition of dependencyOrder(definitions)) {
+        lines.push("", "", ...renderClass(definition, names, plan.plan.get(definition.id), linearizations, definitions));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function basePlan(definitions) {
+    const generated = new Set(definitions.map((definition) => definition.id));
+    const linearizations = new Map();
+    const plan = new Map();
+    for (const definition of dependencyOrder(definitions)) {
+        const kept = [];
+        const declared = [...new Set(definition.baseIds)].filter((baseId) => generated.has(baseId));
+        const candidates = declared.filter((baseId) => linearizations.has(baseId));
+        for (const baseId of withoutImplied(candidates, linearizations)) {
+            if (linearize(definition.id, [...kept, baseId], linearizations) === undefined) {
+                continue;
+            }
+            kept.push(baseId);
+        }
+        const line = linearize(definition.id, kept, linearizations) ?? [definition.id];
+        linearizations.set(definition.id, line);
+        const dropped = declared.filter((baseId) => !line.includes(baseId));
+        plan.set(definition.id, { kept, dropped });
+    }
+    return { plan, linearizations };
+}
+function withoutImplied(bases, linearizations) {
+    const unique = [...new Set(bases)];
+    return unique.filter((baseId) => !unique.some((other) => other !== baseId && (linearizations.get(other) ?? []).slice(1).includes(baseId)));
+}
+function linearize(target, bases, linearizations) {
+    const sequences = bases.map((base) => [...(linearizations.get(base) ?? [base])]);
+    sequences.push([...bases]);
+    const result = [target];
+    for (;;) {
+        const remaining = sequences.filter((sequence) => sequence.length > 0);
+        if (remaining.length === 0) {
+            return result;
+        }
+        const head = remaining.find((sequence) => !remaining.some((other) => other.slice(1).includes(sequence[0])))?.[0];
+        if (head === undefined) {
+            return undefined;
+        }
+        result.push(head);
+        for (const sequence of remaining) {
+            if (sequence[0] === head) {
+                sequence.shift();
+            }
+        }
+        sequences.length = 0;
+        sequences.push(...remaining);
+    }
+}
+function dependencyOrder(definitions) {
+    const byId = new Map(definitions.map((definition) => [definition.id, definition]));
+    const ordered = [];
+    const emitted = new Set();
+    const visiting = new Set();
+    const visit = (definition) => {
+        if (emitted.has(definition.id) || visiting.has(definition.id)) {
+            return;
+        }
+        visiting.add(definition.id);
+        for (const baseId of definition.baseIds) {
+            const base = byId.get(baseId);
+            if (base !== undefined) {
+                visit(base);
+            }
+        }
+        visiting.delete(definition.id);
+        emitted.add(definition.id);
+        ordered.push(definition);
+    };
+    for (const definition of definitions) {
+        visit(definition);
+    }
+    return ordered;
+}
+function edgeKinds(definition) {
+    const edges = new Map();
+    for (const spec of definition.specializations) {
+        if (GENERALIZATION_KINDS.has(spec.kind) && spec.targetId !== "") {
+            edges.set(spec.targetId, spec.kind);
+        }
+    }
+    return edges;
+}
+function featuresOf(line, definitions) {
+    const byId = new Map(definitions.map((definition) => [definition.id, definition]));
+    const seen = new Set();
+    const features = [];
+    for (const id of line) {
+        for (const feature of byId.get(id)?.features ?? []) {
+            if (!seen.has(feature.name)) {
+                seen.add(feature.name);
+                features.push(feature);
+            }
+        }
+    }
+    return features;
+}
+function renderClass(definition, names, plan, linearizations, definitions) {
+    const kept = plan?.kept ?? definition.baseIds;
+    const dropped = plan?.dropped ?? [];
+    const bases = kept.filter((baseId) => names.has(baseId)).map((baseId) => names.get(baseId) ?? "");
+    const unmapped = definition.baseIds.filter((baseId) => !names.has(baseId));
+    const edges = edgeKinds(definition);
+    const header = `export class ${names.get(definition.id) ?? identifier(definition.name)} extends ${bases[0] ?? "_t.TypedObject"} {`;
+    const lines = [
+        `/** ${definition.kind} ${definition.id}. */`,
+        header,
+        ...unmapped.map((baseId) => `  // ${edges.get(baseId) ?? "specializes"} ${baseId}, which has no generated class`),
+        ...dropped.map((baseId) => `  // ${edges.get(baseId) ?? "specializes"} ${baseId}, left out: ` +
+            "the generated hierarchy cannot linearize it with the bases above"),
+        `  static readonly sysmlId: string = ${literal(definition.id)};`,
+        "  static { _t.registerTyped(this); }",
+    ];
+    // TypeScript has single inheritance: the first kept base is the superclass,
+    // and every other base Python would have carried is re-declared as getters,
+    // so every feature its class exposes is reachable here.
+    const inheritedFeatures = new Map();
+    const ownNames = new Set(definition.features.map((feature) => feature.name));
+    for (const baseId of [...kept.slice(1), ...dropped]) {
+        for (const feature of featuresOf(linearizations.get(baseId) ?? [baseId], definitions)) {
+            if (!ownNames.has(feature.name) && !inheritedFeatures.has(feature.name)) {
+                inheritedFeatures.set(feature.name, feature);
+            }
+        }
+    }
+    for (const feature of [...definition.features, ...inheritedFeatures.values()]) {
+        lines.push("", ...renderGetter(feature, names));
+    }
+    lines.push("}");
+    return lines;
+}
+function renderGetter(feature, names) {
+    const tsType = featureType(feature, names);
+    const ident = propertyName(feature.name);
+    let doc = `${feature.kind} ${feature.id}.`;
+    if (RESERVED_MEMBERS.has(identifier(feature.name))) {
+        doc += ` Renamed from ${JSON.stringify(feature.name)}, which TypedObject already defines.`;
+    }
+    if (tsType.comment !== "") {
+        doc += ` Mapped to ${tsType.annotation}: ${tsType.comment}.`;
+    }
+    return [
+        `  /** ${doc} */`,
+        `  get ${ident}(): ${tsType.annotation} {`,
+        `    return ${accessor(feature)}(this, ${literal(feature.name)}, ${tsType.decoder});`,
+        "  }",
+    ];
+}
+/** Render the typed module for a loaded model.
+ *
+ * `sourceText` is the model source the module is stamped with; it is required
+ * so a module cannot silently claim the hash of nothing. A model of several
+ * documents (`Connection.parseSources`) is generated whole, from every
+ * document's root. */
+export async function generateSource(model, sourceText) {
+    return renderModule(await collectDefinitions(...model.roots), modelStamp(sourceText));
+}
+// Named in the failure message below: which binary is at fault, and what to do.
+const TYPE_FACTS_REMEDY = "install a sysml-grpc that reports the 'type_facts' capability. Build it from " +
+    "this repository with `make build-grpc` and run `bin/sysml-grpc`, or remove the " +
+    "cached binary at ~/.opensysml/bin/sysml-grpc and set $OPENSYSML_GRPC_VERSION to a " +
+    "release that has it. Generating against a service without type facts would emit " +
+    "a module in which every feature is typed `SysMLValue`, indistinguishable from a " +
+    "feature that is genuinely untyped, so generation stops instead.";
+/** Fail unless `connection`'s service can supply static type facts. */
+export function requireTypeFacts(connection) {
+    requireCapability(connection.info, CAPABILITY_TYPE_FACTS, TYPE_FACTS_REMEDY);
+}
+/** The externally managed service `--host`/`--port` names, or undefined when
+ * neither names one and the connection starts a private child — or honors
+ * $OPENSYSML_SERVICE — the way `connect()` does with no address. */
+export function serviceAddress(host, port) {
+    if (port === undefined && host === "localhost") {
+        return undefined;
+    }
+    return splitTarget(host, port);
+}
+function splitTarget(host, port) {
+    const fallback = () => `${host}:${port ?? 50051}`;
+    if (!host.includes(":")) {
+        return fallback();
+    }
+    let name;
+    let written;
+    if (host.startsWith("[")) {
+        const closing = host.indexOf("]");
+        if (closing === -1 || !host.slice(closing + 1).startsWith(":")) {
+            return fallback();
+        }
+        name = host.slice(0, closing + 1);
+        written = host.slice(closing + 2);
+    }
+    else if (host.indexOf(":") !== host.lastIndexOf(":")) {
+        return fallback();
+    }
+    else {
+        const parts = host.split(":");
+        name = parts[0] ?? "";
+        written = parts[1] ?? "";
+    }
+    if (!/^\d+$/.test(written)) {
+        throw new RangeError(`host=${JSON.stringify(host)} names no port this client can read; pass ` +
+            `host and port separately, as --host ${JSON.stringify(name)} --port <port>`);
+    }
+    const embedded = Number.parseInt(written, 10);
+    if (port !== undefined && port !== embedded) {
+        throw new RangeError(`host=${JSON.stringify(host)} and port=${port} name different ports; give the port once`);
+    }
+    return `${name}:${String(embedded)}`;
+}
+function parseArgs(argv) {
+    const args = { host: "localhost", check: false };
+    const rest = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "-o" || arg === "--output") {
+            args.output = argv[++index];
+        }
+        else if (arg.startsWith("--output=")) {
+            args.output = arg.slice("--output=".length);
+        }
+        else if (arg === "--host") {
+            args.host = argv[++index];
+        }
+        else if (arg.startsWith("--host=")) {
+            args.host = arg.slice("--host=".length);
+        }
+        else if (arg === "--port") {
+            args.port = Number.parseInt(argv[++index], 10);
+        }
+        else if (arg.startsWith("--port=")) {
+            args.port = Number.parseInt(arg.slice("--port=".length), 10);
+        }
+        else if (arg === "--check") {
+            args.check = true;
+        }
+        else if (arg === "-h" || arg === "--help") {
+            return { error: help(), code: 0 };
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    if (args.output === "" || args.host === "" || Number.isNaN(args.port)) {
+        return { error: "error: an option is missing its value or is invalid", code: 2 };
+    }
+    if (rest.length !== 1) {
+        return { error: "error: expected exactly one source path", code: 2 };
+    }
+    return { source: rest[0], output: args.output, host: args.host ?? "localhost", port: args.port, check: args.check ?? false };
+}
+function help() {
+    return [
+        "usage: opensysml-generate [-h] [-o OUTPUT] [--host HOST] [--port PORT] [--check] source",
+        "",
+        "Generate typed TypeScript classes from a SysML model.",
+        "",
+        "positional arguments:",
+        "  source         path to a .sysml file",
+        "",
+        "options:",
+        "  -h, --help     show this help message and exit",
+        "  -o, --output   output .ts path (default: stdout)",
+        "  --host HOST    sysml-grpc host (default: localhost)",
+        "  --port PORT    sysml-grpc port (default: 50051)",
+        "  --check        do not write; exit non-zero if regenerating would change --output",
+    ].join("\n");
+}
+/** Entry point for the `opensysml-generate` bin. */
+export async function main(argv = process.argv.slice(2)) {
+    const parsed = parseArgs(argv);
+    if ("error" in parsed) {
+        const out = parsed.code === 0 ? console.log : console.error;
+        out(parsed.error);
+        return parsed.code;
+    }
+    if (parsed.check && parsed.output === undefined) {
+        console.error("error: --check requires -o/--output");
+        return 2;
+    }
+    let sourceText;
+    try {
+        sourceText = readFileSync(parsed.source, "utf8");
+    }
+    catch (error) {
+        console.error(`error: cannot read ${parsed.source}: ${error.message}`);
+        return 2;
+    }
+    let address;
+    try {
+        address = serviceAddress(parsed.host, parsed.port);
+    }
+    catch (error) {
+        console.error(`error: ${error.message}`);
+        return 2;
+    }
+    let connection;
+    try {
+        connection = address === undefined ? await connect() : await connect({ address });
+    }
+    catch (error) {
+        console.error(`error: ${error.message}`);
+        return 2;
+    }
+    try {
+        const model = await connection.load(parsed.source);
+        try {
+            requireTypeFacts(connection);
+        }
+        catch (error) {
+            if (error instanceof MissingCapabilityError) {
+                console.error(`error: ${error.message}`);
+                return 1;
+            }
+            throw error;
+        }
+        const errors = model.errors;
+        if (errors.length > 0) {
+            for (const diagnostic of errors) {
+                console.error(`error: ${diagnostic.message}`);
+            }
+            return 1;
+        }
+        const source = await generateSource(model, sourceText);
+        const output = parsed.output;
+        if (parsed.check) {
+            let existing;
+            try {
+                existing = readFileSync(output, "utf8");
+            }
+            catch {
+                existing = undefined;
+            }
+            if (existing === source) {
+                return 0;
+            }
+            const reason = existing === undefined ? "does not exist" : "is out of date";
+            console.error(`error: ${output} ${reason}; regenerate with: ` +
+                `opensysml-generate ${parsed.source} -o ${output}`);
+            return 1;
+        }
+        if (parsed.output !== undefined) {
+            writeFileSync(parsed.output, source, "utf8");
+        }
+        else {
+            process.stdout.write(source);
+        }
+        return 0;
+    }
+    finally {
+        await connection.close();
+    }
+}