feat(migrate): a strict migration refers to no OpenSysML library; -portable inlines the ones a default migration does

changes/unreleased/portable-migration-inlines-libraries.added.md

@@ -0,0 +1 @@
+- **`-portable` makes a SysML v1 migration one self-contained file.** With `-migrate sysml -portable`, the OpenSysML library packages the output refers to — `DiagramLayout`, `MigrationMetadata`, `StateMachines`, `Stochastic`, `DocumentQueries`, and whatever those refer to in turn — are appended after the model, a KerML library in its SysML spelling, so the file loads in a tool that ships only the standard library without changing what the migration writes; the report names the packages inlined. `-strict` remains the way to an output that refers to no OpenSysML library at all.

changes/unreleased/strict-migration-standard-library.changed.md

@@ -0,0 +1 @@
+- **A `-strict` SysML v1 migration refers to no OpenSysML library.** The output loads in a tool that ships only the standard library — the pilot implementation, or a modeling tool built on it — where it used to fail on `MigrationMetadata`, `StateMachines`, `Stochastic`, `DocumentQueries` and `DiagramLayout` references. Made-up name markers become comments, a choice or junction a plain state whose else branch is guarded by the negation of the other guards, a branch probability a comment, an interval wait its midpoint, a view carries no layout, a Monte Carlo analysis loses its `Simulation::MonteCarlo` generalization, and a history pseudostate, a document (with every view and paragraph in it) or a table is refused with a report line; a layout export is still joined to the views, the report counting the geometry it omits; the deferral encoding keeps its `MigrationMetadata::Deferred*` annotations. The default migration is unchanged.

cmd/sysml/convert_test.go

@@ -524,6 +524,8 @@ func TestMigrateMigratesXMI(t *testing.T) {
 		"migrate several models":                       {[]string{v1, v1, "-migrate", "sysml"}, "-migrate migrates one SysML v1 model per run"},
 		"id with migrate":                              {[]string{v1, "-migrate", "ttl", "-id", "uuid"}, "-id accompanies -convert"},
 		"image base URL with convert":                  {[]string{model, "-convert", "ttl", "-image-base-url", "https://ve.example.org"}, "-image-base-url accompanies -migrate"},
+		"portable with convert":                        {[]string{model, "-convert", "ttl", "-portable"}, "-portable accompanies -migrate"},
+		"portable with validate":                       {[]string{model, "-validate", "-portable"}, "-portable accompanies -migrate"},
 		"report over the model":                        {[]string{xmi, "-migrate", "sysml", "-o", textReport, "-migration-report", textReport}, "-migration-report and -o both name"},
 		"report over the model through dangling links": {[]string{xmi, "-migrate", "sysml", "-o", danglingLink(t, dir, "model-link", "shared.txt"), "-migration-report", danglingLink(t, dir, "report-link", "shared.txt")}, "-migration-report and -o both name"},
 		"report over the input":                        {[]string{xmi, "-migrate", "sysml", "-migration-report", xmi}, "names the model being migrated"},

cmd/sysml/features.go

@@ -53,7 +53,7 @@ func boolFlags(names ...string) []featureFlag {
 var (
 	v1Feature = &feature{
 		name:     "v1",
-		flags:    flags("migrate", "migration-report", "migration-results", "layout", "image-base-url"),
+		flags:    append(flags("migrate", "migration-report", "migration-results", "layout", "image-base-url"), boolFlags("portable")...),
 		values:   map[string][]string{"from": {"xmi", "uml", "mdzip"}},
 		sections: []string{"Migration"},
 		markers:  []string{"SysML v1"},

cmd/sysml/main.go

@@ -152,6 +152,7 @@ var (
 	htmlMath         string
 	htmlTheme        string
 	strictMode       bool
+	portableMode     bool
 	disabledLints    lintList
 	enabledLints     lintList
 	noRecordCache    bool
@@ -544,6 +545,10 @@ func runCLI() int {
 		fmt.Fprintln(os.Stderr, "sysml: -image-base-url accompanies -migrate of a SysML v1 model; write `sysml Model.mdzip -migrate sysml -image-base-url https://ve.example.org`")
 		return 2
 	}
+	if portableMode && migrateFormat == "" {
+		fmt.Fprintln(os.Stderr, "sysml: -portable accompanies -migrate of a SysML v1 model; write `sysml Model.mdzip -migrate sysml -portable -o Model.sysml`")
+		return 2
+	}
 	if message := importMisuse(); message != "" {
 		fmt.Fprintf(os.Stderr, "sysml: %s\n", message)
 		return 2

cmd/sysml/migrate.go

@@ -27,6 +27,7 @@ func init() {
 		fs.StringVar(&migrationResults, "migration-results", "", "With -migrate, write the run configurations and the result snapshots the simulation tool stored for them to this JSON file, for -compare-results to read against the migrated model")
 		fs.StringVar(&layoutPath, "layout", "", "With -migrate, read this MTIP export (HUDS XML) and write the diagram geometry it records as DiagramLayout annotations in the migrated views")
 		fs.StringVar(&imageBaseURL, "image-base-url", "", "With -migrate, the http(s) URL a comment's relative <img src> is resolved against, such as the View Editor server")
+		fs.BoolVar(&portableMode, "portable", false, "With -migrate, append the OpenSysML library packages the output refers to, so the one file loads in a tool that ships only the standard library; the report names them")
 	})
 }
 
@@ -139,7 +140,7 @@ func migrateInput(name string, data []byte, _ convert.Format, to convert.Format)
 // options; none were given when the flag was not passed.
 func migrationOptions() (convert.MigrateOptions, error) {
 	if layoutPath == "" {
-		return convert.MigrateOptions{ImageBaseURL: imageBaseURL, Strict: strictMode}, nil
+		return convert.MigrateOptions{ImageBaseURL: imageBaseURL, Strict: strictMode, Portable: portableMode}, nil
 	}
 	data, err := os.ReadFile(layoutPath)
 	if err != nil {
@@ -149,7 +150,7 @@ func migrationOptions() (convert.MigrateOptions, error) {
 	if err != nil {
 		return convert.MigrateOptions{}, fmt.Errorf("%s: %w", layoutPath, err)
 	}
-	return convert.MigrateOptions{Layout: layout, LayoutSource: layoutPath, ImageBaseURL: imageBaseURL, Strict: strictMode}, nil
+	return convert.MigrateOptions{Layout: layout, LayoutSource: layoutPath, ImageBaseURL: imageBaseURL, Strict: strictMode, Portable: portableMode}, nil
 }
 
 // writeMigrationReport writes the report to the -migration-report file (JSON when

cmd/sysml/usage.go

@@ -649,7 +649,7 @@ func registerFlags(fs *flag.FlagSet) {
 	fs.Var(&disabledLints, "disable-lint", "Leave this lint out of the model's diagnostics: undeclared-signal, port-type-mismatch, deferred-keeper-unmarked or rounded-real-literal, comma-separated or repeated")
 	fs.Var(&enabledLints, "enable-lint", "Report this opt-in lint, off by default, in the model's diagnostics: rounded-real-literal, comma-separated or repeated; -disable-lint wins")
 	fs.BoolVar(&noRecordCache, "no-record-cache", false, "Parse every file loaded and hold it loaded, reading no interface record from the record cache and writing none; default off, or OPENSYSML_RECORD_CACHE=0")
-	fs.BoolVar(&strictMode, "strict", false, "Judge the model as conforming SysML v2: notation no pinned production admits is an error, not a warning; a SysML v1 migration writes none of it")
+	fs.BoolVar(&strictMode, "strict", false, "Judge the model as conforming SysML v2: notation no pinned production admits is an error, not a warning; a SysML v1 migration writes none of it and refers to no OpenSysML library")
 	fs.Var(&modelChecks.constraints, "constraint", "Evaluate this constraint and exit (repeatable)")
 	fs.BoolVar(&modelChecks.selfCheck, "self-check", false, "Apply the SysMLValidation constraints to every reflectively classified model element and exit")
 	fs.Var(&modelChecks.selfCheckPackages, "self-check-package", "Apply this package's constraint defs with the SysMLValidation ones, as -self-check-package Acme::ModelingRules; implies -self-check (repeatable)")
@@ -826,6 +826,7 @@ func optionGroups() []usage.OptionGroup {
 			usage.Opt("migration-results", fileArg),
 			usage.Opt("layout", fileArg),
 			usage.Opt("image-base-url", "<url>"),
+			usage.Opt("portable", ""),
 			usage.Opt("compare-results", fileArg),
 		},
 	}, {

docs/guide/03-command-line.md

@@ -226,7 +226,7 @@ friends — reported as warnings that name the replacement, so a model that uses
 still analyses cleanly. `-strict` promotes those warnings
 to errors, which turns the run into a test of whether the file is conforming SysML v2. The flag
 applies to `-migrate` too: a strict SysML v1 migration writes no extension notation
-at all — see [Portable output with `-strict`](../reference/sysml-v1-migration.md#portable-output-with--strict).
+at all and refers to no OpenSysML library — see [Portable output with `-strict`](../reference/sysml-v1-migration.md#portable-output-with--strict); `-portable` instead appends the OpenSysML library packages a default migration refers to, so the one file loads elsewhere unchanged.
 
 The state machine below uses the `choice` extension so the difference is visible:
 

docs/guide/11-migrating-from-sysml-v1.md

@@ -315,24 +315,39 @@ its type: `end [0..1] driver : Driver;`. From this point `%save` in the REPL, `-
 LSP and the clients all take the file as they take any other; nothing remembers that it was
 migrated.
 
-## Portable output with `-strict`
-
-Pseudostates are written through the `StateMachines` library's metadata
-spellings — `#StateMachines::junction state x;` — with `private import
-StateMachines::*;` added to each package that holds one, so a migrated model
-reads as conforming SysML v2 either way. Pass `-strict` (see
-[Strict conformance](03-command-line.md#strict-conformance)) and the migration
-still writes only notation a pinned grammar admits — the pseudostates keep
-their `StateMachines` metadata spellings in both modes:
-
-```console
-$ sysml Project.xmi -strict -migrate sysml -o Project.sysml
-$ sysml -strict -validate Project.sysml
-✓ Project.sysml: no errors
-```
-
-What a strict migration refuses is described in the reference under
-[Portable output with `-strict`](../reference/sysml-v1-migration.md#portable-output-with--strict).
+## Portable output: `-portable` and `-strict`
+
+A migrated model refers to OpenSysML's own library packages where v1 has no standard v2
+form: a pseudostate is written through the `StateMachines` library's metadata spellings
+(`#StateMachines::junction state x;`, with `private import StateMachines::*;` added to each
+package that holds one), a branch probability through `Stochastic`, a view's geometry through
+`DiagramLayout`, the names the migration made up through `MigrationMetadata`. OpenSysML ships
+them, so the file loads here as it is; a tool that ships only the standard library — the pilot
+implementation, or a modeling tool built on it — reports every such reference unresolved. Two
+flags make the output portable to such a tool:
+
+- `-portable` keeps the migration as it is and appends the library packages the output refers
+  to, so the one file carries everything it needs; the report names them:
+
+  ```console
+  $ sysml Project.xmi -migrate sysml -portable -o Project.sysml
+  migration: … inlined 4 OpenSysML library package(s): DiagramLayout, MigrationMetadata, StateMachines, Stochastic
+  ```
+
+- `-strict` (see [Strict conformance](03-command-line.md#strict-conformance)) writes no
+  OpenSysML reference at all — a pseudostate as a plain state, a probability as a comment, a
+  view without geometry — at the cost of what the reference lists under
+  [Portable output with `-strict`](../reference/sysml-v1-migration.md#portable-output-with--strict),
+  so the output also reads as conforming SysML v2:
+
+  ```console
+  $ sysml Project.xmi -strict -migrate sysml -o Project.sysml
+  $ sysml -strict -validate Project.sysml
+  ✓ Project.sysml: no errors
+  ```
+
+Both are described in the reference under
+[Portable output with `-portable`](../reference/sysml-v1-migration.md#portable-output-with--portable).
 
 A deferred signal is standard notation in both modes: the state gets an `item` buffer its do
 action fills from an accept loop while the state is active, substates included, and its exit

docs/reference/cli.md

@@ -249,6 +249,7 @@ the same member-path parser as `Project` and `OrderBy`.
 | `--migration-report <file>` | | With `--migrate`: write the element-by-element migration report to this file, JSON when it ends in `.json`, text otherwise. Without it the one-line summary goes to stderr |
 | `--migration-results <file>` | | With `--migrate`: write the simulation tool's run configurations (`SimulationProfile:SimulationConfig`) and the result snapshots it stored for each of them to this JSON file — the sidecar `-compare-results` reads against the migrated model. See [Comparing a migrated configuration with the tool's results](#comparing-a-migrated-configuration-with-the-tools-results) |
 | `--image-base-url <url>` | | With `--migrate`: the absolute http(s) URL a comment's relative `<img src>` — a path the View Editor serves, such as `/projects/.../png` — is resolved against, so the migrated document's `Image` block points at the server instead of losing the image (see [SysML v1 migration](sysml-v1-migration.md)) |
+| `--portable` | | With `--migrate`: append the OpenSysML library packages the output refers to, so the one file loads in a tool that ships only the standard library; the report names them (see [Portable output with `--portable`](sysml-v1-migration.md#portable-output-with--portable)) |
 | `--render <view>` | | Render this view of the model (every file named, loaded as one) instead of running it, in the form its `render` member states (see [Rendering a view](#rendering-a-view)) |
 | `--render-all <dir>` | | Render every declared view into the directory, one artifact per view |
 | `--graphs <subject>` | | Write the lowered graph of this action or state machine, and of every behavior it performs, as the canonical `graphs:1` JSON an external analysis engine is sent ([the `graphs:1` model form](external-engines.md#the-graphs1-model-form)) to stdout, or to `--output`. The subject is a qualified name, definition or usage; a name that is no behavior, or that nothing declares, is refused with exit status 2. Cannot be combined with checks, rendering, `--convert`, `--migrate`, `--query` or `--eval` |