ALITSoftware Architect Get the extension

Command-line validation and export

The extension ships two self-contained Node.js bundles. Use Node 22 or newer. In desktop VS Code, run swa.ml: Copy Headless CLI Command and choose validation or export; the command contains the correct installed extension path. Browser-only sessions cannot run Node commands.

The examples below use <extension-folder> for that installed directory. Quote paths containing spaces. Both tools accept --help and --version; the version output distinguishes the extension version from language implementation 3.0.0 and parser 2.1.

npm distribution

The published npm package is @voidaliot/swaml-cli, with commands swaml-validate and swaml-diagram. Install version 0.17.1 with npm install --global @voidaliot/swaml-cli@0.17.1, or use npx --package=@voidaliot/swaml-cli@0.17.1 swaml-validate ./models --format json. Replace the installed-extension node .../validate.mjs and node .../cli.mjs prefixes below with those command names. The npm tarball includes the same standalone bundles, licensing and pinned language identity, without source maps, editor assets or runtime dependencies.

Validate a complete model

node "<extension-folder>/out/validate.mjs" ./models --format text
node "<extension-folder>/out/validate.mjs" ./models --format json
node "<extension-folder>/out/validate.mjs" ./models --format sarif > validation.sarif
node "<extension-folder>/out/validate.mjs" ./models --format github --strict
node "<extension-folder>/out/validate.mjs" model.swaml dependency.swaml --language-version 2.1 --no-config

Supply every application dependency together, or a directory containing the complete source set. The standard library is already embedded. Directory discovery respects .gitignore and .swamlignore, skips hidden/generated/dependency directories and does not pull in ignored negative examples. An explicitly named ignored file is inspected separately; it does not join the application namespace. Exact source copies of the pinned standard library are inspected separately too. Different library source is not substituted for the pin.

Option Behavior
--format text|json|sarif|github Human diagnostics, structured diagnostics, SARIF 2.1.0 or escaped GitHub annotations. Default: text.
--strict Warnings also fail the command.
--language-version 2.1 Select the supported parser family explicitly. Historical editions fail.
--no-config Ignore project/editor settings; source boundary rules still apply.

Exit 0 means validation passed the chosen warning policy; 1 means diagnostics fail that policy; 2 means invalid arguments, configuration or an I/O failure. JSON valid describes semantic errors, so a warning-only model can have valid: true and exit 1 under --strict. Display severity settings cannot make an invalid model pass. JSON includes extensionVersion, language version, parserFamily, source URIs and located diagnostics. Error codes are stable SW2xxx identifiers.

Export diagrams or the GRV table

node "<extension-folder>/out/cli.mjs" export --file model.swaml --workspace ./models --view gv --out architecture.svg
node "<extension-folder>/out/cli.mjs" export --file model.swaml --view fv --anchor "Example::Demo::counters[0]::increment" --out flow.svg
node "<extension-folder>/out/cli.mjs" export --file model.swaml --view grv --out inventory.csv
node "<extension-folder>/out/cli.mjs" export --file model.swaml --all --out-dir ./export --theme light --auto-layout

Use an anchor that exists in the selected source/dependency set. A missing anchor fails rather than exporting a different scope. The available views are gv, iv, cv, sv, fv, tv (SVG) and grv (CSV). Browser is a navigation surface and has no headless export. --all exports available content, skipping empty views, and requires an output directory rather than one output file. A Timing export without identified simulation evidence shows declared contracts.

Saved Sequence case and participant selections and optional Interconnect case overlays use the same sidecar state as the editor. --no-config ignores these choices. IV SVG retains case, exchange, route and source identity metadata. A selected incompatible or hidden case route fails export with an explicit explanation. Any source error fails before export; partial or stale editor recovery is never exported as a complete valid model.

Option Behavior
--file Source file; one positional file is also accepted.
--workspace Additional source directory containing application dependencies.
--view, --anchor View kind and qualified source/occurrence scope.
--out, --out-dir One output file, or a directory for generated view filenames.
--theme dark|light Export palette.
--gv-mode group|tree General view presentation.
--auto-layout Compute layout rather than restoring saved positions.
--strict, --no-config, --language-version Validation policy and edition selection, as above.

Exports use the shared renderer and source identities. The CLI reads committed .vscode/settings.json, .vscode/swaml/project.json and diagram sidecars where present; project configuration takes precedence. swaml.library.directories adds explicit library roots. CLI roots support filesystem paths and file: URIs; virtual filesystem URIs belong to the browser host. Outputs are written only after successful validation; a successful export exits 0, invalid source exits 1, and argument/configuration/export failures exit 2.

CI use

Install the exact released VSIX in the CI image or extract its extension folder, then run its bundled validator with Node 22+. Keep the extension version and VSIX checksum with the report. A typical validation step is:

node "$SWAML_EXTENSION_DIR/out/validate.mjs" ./models --format github --strict --no-config

The tools perform syntax, linking and semantic validation. They do not prove requirements, run use cases or tests or provide production scheduling guarantees.