@hla4ts/fom-codegen 0.1.0

package/README.md

@@ -0,0 +1,247 @@
+# @hla4ts/fom-codegen
+
+**TypeScript-first FOM/SOM code generator (IEEE 1516-2025 OMT/FDD XML)**
+
+This package provides a registry API for describing object/interaction classes and data types in TypeScript, then generating valid IEEE 1516-2025 XML (OMT or FDD). It is designed to be the base for higher-level SpaceFOM-friendly frameworks.
+
+## Goals
+
+- Let users describe HLA classes in TypeScript without hand-editing XML.
+- Generate deterministic, schema-valid XML for import into RTIs.
+- Keep metadata explicit (update types, ownership, transport/order, semantics).
+
+## Installation
+
+```bash
+bun add @hla4ts/fom-codegen
+```
+
+## Quick Start
+
+```ts
+import {
+  FomRegistry,
+  type ObjectClassSchema,
+} from "@hla4ts/fom-codegen";
+
+const registry = new FomRegistry();
+
+registry.setModelIdentification({
+  name: "MyFederate FOM",
+  type: "FOM",
+  version: "0.1.0",
+  modificationDate: "2026-01-22",
+  securityClassification: "Unclassified",
+  description: "Custom SpaceFOM extensions for MyFederate",
+});
+
+const vehicle: ObjectClassSchema = {
+  name: "SpaceVehicle",
+  parent: "PhysicalEntity",
+  sharing: "PublishSubscribe",
+  semantics: "A user-defined vehicle class.",
+  attributes: [
+    {
+      name: "name",
+      dataType: "HLAunicodeString",
+      updateType: "Static",
+      updateCondition: "during initialization",
+      ownership: "NoTransfer",
+      sharing: "PublishSubscribe",
+      transportation: "HLAreliable",
+      order: "TimeStamp",
+      semantics: "Unique name.",
+      valueRequired: true,
+    },
+  ],
+};
+
+registry.addObjectClass(vehicle);
+
+const xml = registry.toXml({ format: "omt" });
+console.log(xml);
+```
+
+## Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant User as Developer
+  participant Registry as FomRegistry
+  participant Writer as renderFomXml
+  User->>Registry: addObjectClass / addDataType
+  User->>Registry: toXml({ format })
+  Registry->>Writer: buildModel()
+  Writer-->>User: OMT/FDD XML
+```
+
+## Registry API
+
+- `setModelIdentification(...)`
+- `setTime(...)`
+- `addObjectClass(...)`
+- `addInteractionClass(...)`
+- `addDataType(...)`
+- `addDimension(...)`
+- `addTransportation(...)`
+- `setSwitches(...)`
+- `toXml({ format: "omt" | "fdd" })`
+
+## XML Parsing
+
+You can parse an existing XML FOM into a `FomModel` and then re-emit or convert it:
+
+```ts
+import { parseFomXml, generateFomTypescript } from "@hla4ts/fom-codegen";
+
+const model = parseFomXml(xmlString);
+const ts = generateFomTypescript(model, { mode: "registry" });
+```
+
+## XSD-Based Type Generation
+
+This package includes TypeScript types generated directly from the IEEE 1516-2025 XSD schemas. These types provide:
+
+- **Autocomplete** based on the official XML schema
+- **Type checking** that matches XSD validation
+- **Documentation** extracted from XSD annotations
+
+### Using XSD Types
+
+The generated types are available from the `generated` submodule:
+
+```ts
+import type {
+  ModelIdentification,
+  ObjectClass,
+  InteractionClass,
+  SharingEnumeration,
+  OrderEnumeration,
+} from "@hla4ts/fom-codegen/generated";
+
+// Use XSD types for autocomplete
+const modelId: ModelIdentification = {
+  name: "MyFOM",
+  type: "FOM", // Autocomplete: "FOM" | "SOM"
+  version: "1.0",
+  modificationDate: "2026-01-23",
+  securityClassification: "Unclassified", // Autocomplete shows valid values
+  description: "My federation object model",
+};
+
+const objectClass: ObjectClass = {
+  name: "MyObject",
+  sharing: "PublishSubscribe", // Autocomplete: "Publish" | "Subscribe" | "PublishSubscribe" | "Neither"
+  // ... other properties with full autocomplete
+};
+```
+
+### Generating Types
+
+Types are generated from the XSD schemas in the `schema/` directory:
+
+```bash
+bun run generate-types
+```
+
+This parses `IEEE1516-DIF-2025.xsd` and generates TypeScript types in `src/generated/xsd-types.ts`.
+
+### Type Adapters
+
+Use the adapter functions to convert XSD types to FomRegistry schema types:
+
+```ts
+import {
+  FomRegistry,
+  adaptModelIdentification,
+  adaptObjectClass,
+  adaptInteractionClass,
+} from "@hla4ts/fom-codegen";
+import type {
+  ModelIdentification,
+  ObjectClass,
+  InteractionClass,
+} from "@hla4ts/fom-codegen/generated";
+
+const registry = new FomRegistry();
+
+// Define using XSD types for autocomplete and type checking
+const modelId: ModelIdentification = {
+  name: "MyFOM",
+  type: "FOM", // TypeScript autocomplete: "FOM" | "SOM"
+  version: "1.0",
+  modificationDate: "2026-01-23",
+  securityClassification: "Unclassified", // Autocomplete shows valid values
+  description: "My federation object model",
+};
+
+// Convert and use with FomRegistry
+registry.setModelIdentification(adaptModelIdentification(modelId));
+
+// Object classes with XSD autocomplete
+const vehicle: ObjectClass = {
+  name: "SpaceVehicle",
+  sharing: "PublishSubscribe", // Autocomplete: "Publish" | "Subscribe" | "PublishSubscribe" | "Neither"
+  semantics: "A space vehicle",
+  attribute: [
+    {
+      name: "name",
+      dataType: "HLAunicodeString",
+      updateType: "Static", // Autocomplete: "Static" | "Periodic" | "Conditional" | "NA"
+      ownership: "NoTransfer", // Autocomplete: "Divest" | "Acquire" | "DivestAcquire" | "NoTransfer"
+      sharing: "PublishSubscribe",
+      transportation: "HLAreliable",
+      order: "TimeStamp", // Autocomplete: "Receive" | "TimeStamp"
+    },
+  ],
+};
+
+registry.addObjectClass(adaptObjectClass(vehicle));
+```
+
+### Benefits
+
+- **Compile-time type checking**: TypeScript will catch invalid enum values, missing required fields, and type mismatches
+- **Autocomplete**: Your IDE will suggest valid values for enums and available properties
+- **XSD alignment**: The generated types match the XSD schema exactly, so what TypeScript accepts will pass XSD validation
+- **Documentation**: JSDoc comments from XSD annotations are preserved in the generated types
+
+### Parser Notes
+
+- The parser targets IEEE 1516-2025 OMT/FDD structures and ignores unrelated XML.
+- Namespaces are stripped from element and attribute names.
+- Missing attribute metadata is defaulted to safe values (e.g., `updateType = "NA"`).
+
+## Notes
+
+- OMT output requires `modelIdentification` fields. FDD output is more relaxed.
+- The generator always writes `HLAobjectRoot` and `HLAinteractionRoot` if not provided.
+- Attribute/interaction metadata is not inferred from TS types; it must be explicit.
+
+## Testing
+
+```bash
+cd packages/fom-codegen
+bun test
+```
+
+## CLI
+
+Generate XML from a registry module:
+
+```bash
+bun run @hla4ts/fom-codegen cli -- --entry src/fom.ts --out dist/fom.xml --format omt
+```
+
+Entry modules can export:
+
+- `registry`: a `FomRegistry` instance
+- `default`: a `FomRegistry` instance
+- `buildFom()`: function returning `FomModel`
+- `default`: a `FomModel` object
+
+Parse XML and emit TypeScript:
+
+```bash
+bun run @hla4ts/fom-codegen cli -- --from-xml spacefom/SISO_SpaceFOM_entity.xml --out-ts src/fom.ts --ts-mode registry
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hla4ts/fom-codegen",
+  "version": "0.1.0",
+  "description": "FOM XML parser, registry, and TypeScript code generation tooling for hla4typescript",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "bin": {
+    "hla4ts-fom": "src/cli.ts"
+  },
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "scripts": {
+    "cli": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "generate-types": "bun run scripts/generate-types.ts"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env bun
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readFileSync, writeFileSync } from "node:fs";
+import { FomRegistry } from "./registry.ts";
+import type { FomModel, FomOutputFormat, FomOutputOptions } from "./types.ts";
+import { renderFomXml } from "./xml-writer.ts";
+import { parseFomXml } from "./xml-parser.ts";
+import { generateFomTypescript } from "./ts-codegen.ts";
+
+type CliArgs = {
+  entry: string;
+  out?: string;
+  format: FomOutputFormat;
+  schemaLocation?: string;
+  includeModelIdentification: boolean;
+  indent?: string;
+  fromXml?: string;
+  outTs?: string;
+  tsMode?: "model" | "registry";
+};
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    entry: "",
+    format: "omt",
+    includeModelIdentification: true,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--entry":
+        args.entry = argv[++i] ?? "";
+        break;
+      case "--from-xml":
+        args.fromXml = argv[++i];
+        break;
+      case "--out-ts":
+        args.outTs = argv[++i];
+        break;
+      case "--ts-mode":
+        args.tsMode = argv[++i] as "model" | "registry";
+        break;
+      case "--out":
+        args.out = argv[++i];
+        break;
+      case "--format":
+        args.format = (argv[++i] as FomOutputFormat) ?? "omt";
+        break;
+      case "--schema":
+        args.schemaLocation = argv[++i];
+        break;
+      case "--no-model-identification":
+        args.includeModelIdentification = false;
+        break;
+      case "--indent":
+        args.indent = argv[++i];
+        break;
+      case "--fdd":
+        args.format = "fdd";
+        break;
+      case "--omt":
+        args.format = "omt";
+        break;
+      case "--help":
+        printUsage();
+        process.exit(0);
+      default:
+        if (!arg.startsWith("--") && !args.entry) {
+          args.entry = arg;
+        }
+        break;
+    }
+  }
+
+  if (!args.entry && !args.fromXml) {
+    printUsage();
+    process.exit(1);
+  }
+
+  return args;
+}
+
+function printUsage(): void {
+  const text = [
+    "Usage: hla4ts-fom --entry <file> [options]",
+    "",
+    "Options:",
+    "  --entry <file>              Module that exports a registry or model",
+    "  --out <file>                Output XML file (stdout if omitted)",
+    "  --format <omt|fdd>          Output format (default: omt)",
+    "  --omt                       Shortcut for --format omt",
+    "  --fdd                       Shortcut for --format fdd",
+    "  --from-xml <file>           Parse XML and emit TypeScript",
+    "  --out-ts <file>             Output TypeScript file",
+    "  --ts-mode <model|registry>  TypeScript output mode (default: model)",
+    "  --schema <value>            Override xsi:schemaLocation",
+    "  --indent <value>            Indent string (default: two spaces)",
+    "  --no-model-identification   Skip modelIdentification block",
+  ];
+  console.log(text.join("\n"));
+}
+
+function resolveModel(mod: Record<string, unknown>): FomModel {
+  if (isRegistry(mod.registry)) {
+    return (mod.registry as FomRegistry).buildModel();
+  }
+  if (isRegistry(mod.default)) {
+    return (mod.default as FomRegistry).buildModel();
+  }
+  if (typeof mod.buildFom === "function") {
+    return mod.buildFom() as FomModel;
+  }
+  if (isFomModel(mod.default)) {
+    return mod.default as FomModel;
+  }
+  if (isFomModel(mod.fom)) {
+    return mod.fom as FomModel;
+  }
+  throw new Error("Entry module did not export a registry or FomModel.");
+}
+
+function isRegistry(value: unknown): value is FomRegistry {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      typeof (value as FomRegistry).buildModel === "function" &&
+      typeof (value as FomRegistry).toXml === "function"
+  );
+}
+
+function isFomModel(value: unknown): value is FomModel {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      Array.isArray((value as FomModel).objectClasses) &&
+      Array.isArray((value as FomModel).interactionClasses) &&
+      Array.isArray((value as FomModel).dataTypes)
+  );
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.fromXml) {
+    const xml = readFileSync(args.fromXml, "utf8");
+    const model = parseFomXml(xml);
+    const ts = generateFomTypescript(model, {
+      mode: args.tsMode ?? "model",
+    });
+    if (args.outTs) {
+      writeFileSync(args.outTs, ts);
+    } else {
+      console.log(ts);
+    }
+    return;
+  }
+
+  const entryUrl = pathToFileURL(resolve(args.entry)).href;
+  const mod = (await import(entryUrl)) as Record<string, unknown>;
+  const model = resolveModel(mod);
+  const options: FomOutputOptions = {
+    format: args.format,
+    schemaLocation: args.schemaLocation,
+    includeModelIdentification: args.includeModelIdentification,
+    indent: args.indent,
+  };
+  const xml = renderFomXml(model, options);
+  if (args.out) {
+    writeFileSync(args.out, xml);
+  } else {
+    console.log(xml);
+  }
+}
+
+main().catch((error) => {
+  console.error(`[hla4ts-fom] ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});

package/src/generated/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Generated XSD Types - Re-exported for convenience
+ *
+ * This module re-exports the generated TypeScript types from the XSD schema.
+ * These types provide autocomplete and type checking that matches XSD validation.
+ */
+
+export * from "./xsd-types.ts";
+
+// Re-export commonly used types with shorter names for convenience
+export type {
+  ModelIdentification as XsdModelIdentification,
+  ObjectClass as XsdObjectClass,
+  InteractionClass as XsdInteractionClass,
+  Attribute as XsdAttribute,
+  Parameter as XsdParameter,
+} from "./xsd-types.ts";
+
+export type {
+  SharingEnumeration as XsdSharingType,
+  OrderEnumeration as XsdOrderType,
+  UpdateEnumeration as XsdUpdateType,
+  OwnershipEnumeration as XsdOwnershipType,
+  OMTypeEnumeration as XsdOMType,
+} from "./xsd-types.ts";