sysml-validate 0.11.0 → 0.14.2

package/LICENSE

@@ -1,27 +1,27 @@
-SysML v2 Visual Studio Code Extension
-Freeware License
-
-Copyright (c) 2026 C. Ilie
-
-Permission is granted to install and use this software free of charge.
-
-The software is licensed, not sold.
-
-You may:
-- Use the software for personal purposes.
-- Use the software for educational purposes.
-- Use the software for commercial purposes.
-
-You may not:
-- Modify the software.
-- Reverse engineer the software except where required by law.
-- Redistribute the software.
-- Sublicense the software.
-- Sell the software.
-- Create derivative works.
-
-All intellectual property rights remain with the copyright holder.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
-IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.
+SysML v2 Visual Studio Code Extension
+Freeware License
+
+Copyright (c) 2026 C. Ilie
+
+Permission is granted to install and use this software free of charge.
+
+The software is licensed, not sold.
+
+You may:
+- Use the software for personal purposes.
+- Use the software for educational purposes.
+- Use the software for commercial purposes.
+
+You may not:
+- Modify the software.
+- Reverse engineer the software except where required by law.
+- Redistribute the software.
+- Sublicense the software.
+- Sell the software.
+- Create derivative works.
+
+All intellectual property rights remain with the copyright holder.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

package/README.md

@@ -1,200 +1,200 @@
-# sysml-validate
-
-Headless SysML v2 / KerML validation. Runs the same parser, linker, and
-diagnostics as the
-[SysML v2 VS Code extension](https://marketplace.visualstudio.com/items?itemName=voidaliot.vscode-sysml-v2)
-— the Problems panel, in a terminal or a CI job. No VS Code, no browser, no
-display server.
-
-```bash
-npx sysml-validate models/
-```
-
-```
-models/control.sysml
-  2:5    error  SYN067  Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
-
-models/vehicle.sysml
-  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.
-
-✖ 2 problems (2 errors) in 2 of 2 files
-```
-
-…and when the model is healthy:
-
-```
-✓ 2 files checked, no problems found
-```
-
-Colour is used on a terminal and dropped everywhere else — a pipe, a log file,
-or a coding agent's chat window gets exactly the plain text above. `--color` and
-`--no-color` force it either way, and `NO_COLOR` is honoured.
-
-## Usage
-
-```
-sysml-validate [paths...] [options]
-
-  --format <fmt>        text | compact | json | sarif | github (default: text).
-                        text     grouped and aligned, colour on a terminal
-                        compact  file:line:col: severity [CODE]: message
-  --out <path>          Write the report to a file instead of stdout.
-  --strict              Fail on warnings as well as errors.
-  --max-warnings <n>    Fail when more than n warnings are reported.
-  --all                 Report informational notices and hints too.
-  --lint-profile <p>    Override sysml.lint.profile: default | quiet | strict.
-  --workspace <path>    Index this project for cross-file reference resolution.
-  --no-config           Ignore .vscode/settings.json and .vscode/sysml/project.json.
-  --library <path>      Standard-library directory (default: the bundled library).
-  --color, --no-color   Force ANSI colour on or off (default: on a terminal only).
-```
-
-Paths may be files or directories; directories are searched recursively for
-`.sysml` and `.kerml`, skipping `node_modules`, VCS directories, build output,
-and vendored library trees. With no path, the working directory is checked.
-By default, no model file outside the paths you name is discovered or indexed.
-Use `--workspace <path>` only when references should resolve against other
-project files.
-
-The OMG standard library ships with the package, so `Real`, `ISQ::*`, `SI::*`
-and the rest resolve with nothing else installed.
-
-## Examples
-
-**Check one file while you work.** Paths, positions, severity, and the
-diagnostic code — everything needed to jump to the problem:
-
-```console
-$ sysml-validate models/vehicle.sysml
-models/vehicle.sysml
-  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.
-
-✖ 1 problem (1 error) in 1 of 1 file
-```
-
-**See the advisory notices too.** Hints and info are out of the way by default —
-`--all` brings them in:
-
-```console
-$ sysml-validate models/ --all
-models/vehicle.sysml
-  5:19   hint  RES016  'power' shadows a standard-library element of the same name; the library symbol is hidden in this scope.
-  16:21  hint  SEM006  Requirement definition 'MassLimit' has no 'subject' declaration.
-
-▲ 2 problems (2 hints) in 1 of 2 files
-```
-
-**One line per problem** for `grep`, an editor error matcher, or a coding agent
-that wants to parse the output:
-
-```console
-$ sysml-validate models/ --format compact
-models/control.sysml:2:5: error [SYN067]: Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
-models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
-```
-
-Compact prints **nothing at all** on a clean run, so `[ -s report.txt ]` and
-`if sysml-validate . --format compact | grep .` both behave.
-
-**Structured output** for a script or a dashboard:
-
-```console
-$ sysml-validate models/ --format json | jq '.counts, .diagnostics[0].code'
-{
-  "error": 2,
-  "warning": 0,
-  "info": 0,
-  "hint": 0
-}
-"SYN067"
-```
-
-**Gate a commit hook** on errors, and allow a small warning budget:
-
-```console
-$ sysml-validate models/ --max-warnings 5 && echo "model is publishable"
-```
-
-**Check just what changed**, without loading any model outside that list:
-
-```console
-$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate
-```
-
-If those files need definitions elsewhere in the checkout, opt into workspace
-indexing explicitly:
-
-```console
-$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate --workspace .
-```
-
-`--workspace .` indexes the rest of the project for reference resolution, but
-still reports diagnostics only for the files you named.
-
-**Use it from a coding agent.** The default output is plain text with a stable
-one-line summary, so an agent can act on it directly:
-
-```console
-$ sysml-validate models/ --format compact ; echo "exit=$?"
-models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
-exit=1
-```
-
-## Your project's configuration is honoured
-
-The validator reads the settings your team commits, in the editor's own
-precedence — `.vscode/settings.json` first, then `.vscode/sysml/project.json`:
-
-| Setting | Effect |
-|---|---|
-| `sysml.lint.profile` | `default` / `quiet` / `strict` style-notice volume |
-| `sysml.validation.severities` | Per-code severity overrides (e.g. `{ "SEM006": "warning" }`) |
-| `sysml.diagnostics.unusedImports` | `off` / `warning` / `error` |
-| `sysml.diagnostics.units` | UNIT001–UNIT005 dimensional analysis on/off |
-
-`--lint-profile` overrides the profile for one run, and `--no-config` ignores
-both files. Note that `sysml.validation.severities` covers the validator's own
-codes; unresolved-reference errors (`RES001`) come from the linker and are
-always errors.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | no blocking diagnostics |
-| `1` | errors, or warnings under `--strict` / `--max-warnings` |
-| `2` | the command line or the environment was wrong (bad flag, unreadable path) |
-
-Informational notices and hints never fail a run; they are only printed with
-`--all`.
-
-## GitHub Actions
-
-Fail the build on model errors, with inline annotations on the diff:
-
-```yaml
-- uses: actions/setup-node@v4
-  with: { node-version: 20 }
-
-- name: Validate the SysML model
-  run: npx sysml-validate models/ --format github --strict
-```
-
-Or upload SARIF so diagnostics land in **Security → Code scanning** and on the
-pull request:
-
-```yaml
-- name: Validate the SysML model
-  run: npx sysml-validate models/ --format sarif --out sysml.sarif
-  continue-on-error: true
-
-- uses: github/codeql-action/upload-sarif@v3
-  with:
-    sarif_file: sysml.sarif
-```
-
-## License
-
-The CLI uses the extension's Freeware License (see `LICENSE`). The vendored OMG
-standard library under `resources/sysml.library` keeps its upstream OMG
-LICENSE / LICENSE-GPL terms; see that directory's `NOTICE.md`.
+# sysml-validate
+
+Headless SysML v2 / KerML validation. Runs the same parser, linker, and
+diagnostics as the
+[SysML v2 VS Code extension](https://marketplace.visualstudio.com/items?itemName=voidaliot.vscode-sysml-v2)
+— the Problems panel, in a terminal or a CI job. No VS Code, no browser, no
+display server.
+
+```bash
+npx sysml-validate models/
+```
+
+```
+models/control.sysml
+  2:5    error  SYN067  Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
+
+models/vehicle.sysml
+  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.
+
+✖ 2 problems (2 errors) in 2 of 2 files
+```
+
+…and when the model is healthy:
+
+```
+✓ 2 files checked, no problems found
+```
+
+Colour is used on a terminal and dropped everywhere else — a pipe, a log file,
+or a coding agent's chat window gets exactly the plain text above. `--color` and
+`--no-color` force it either way, and `NO_COLOR` is honoured.
+
+## Usage
+
+```
+sysml-validate [paths...] [options]
+
+  --format <fmt>        text | compact | json | sarif | github (default: text).
+                        text     grouped and aligned, colour on a terminal
+                        compact  file:line:col: severity [CODE]: message
+  --out <path>          Write the report to a file instead of stdout.
+  --strict              Fail on warnings as well as errors.
+  --max-warnings <n>    Fail when more than n warnings are reported.
+  --all                 Report informational notices and hints too.
+  --lint-profile <p>    Override sysml.lint.profile: default | quiet | strict.
+  --workspace <path>    Index this project for cross-file reference resolution.
+  --no-config           Ignore .vscode/settings.json and .vscode/sysml/project.json.
+  --library <path>      Standard-library directory (default: the bundled library).
+  --color, --no-color   Force ANSI colour on or off (default: on a terminal only).
+```
+
+Paths may be files or directories; directories are searched recursively for
+`.sysml` and `.kerml`, skipping `node_modules`, VCS directories, build output,
+and vendored library trees. With no path, the working directory is checked.
+By default, no model file outside the paths you name is discovered or indexed.
+Use `--workspace <path>` only when references should resolve against other
+project files.
+
+The OMG standard library ships with the package, so `Real`, `ISQ::*`, `SI::*`
+and the rest resolve with nothing else installed.
+
+## Examples
+
+**Check one file while you work.** Paths, positions, severity, and the
+diagnostic code — everything needed to jump to the problem:
+
+```console
+$ sysml-validate models/vehicle.sysml
+models/vehicle.sysml
+  12:23  error  RES001  Could not resolve reference to Element named 'Engien'.
+
+✖ 1 problem (1 error) in 1 of 1 file
+```
+
+**See the advisory notices too.** Hints and info are out of the way by default —
+`--all` brings them in:
+
+```console
+$ sysml-validate models/ --all
+models/vehicle.sysml
+  5:19   hint  RES016  'power' shadows a standard-library element of the same name; the library symbol is hidden in this scope.
+  16:21  hint  SEM006  Requirement definition 'MassLimit' has no 'subject' declaration.
+
+▲ 2 problems (2 hints) in 1 of 2 files
+```
+
+**One line per problem** for `grep`, an editor error matcher, or a coding agent
+that wants to parse the output:
+
+```console
+$ sysml-validate models/ --format compact
+models/control.sysml:2:5: error [SYN067]: Import visibility is required by the Release syntax; use 'private import' unless re-export is intended.
+models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
+```
+
+Compact prints **nothing at all** on a clean run, so `[ -s report.txt ]` and
+`if sysml-validate . --format compact | grep .` both behave.
+
+**Structured output** for a script or a dashboard:
+
+```console
+$ sysml-validate models/ --format json | jq '.counts, .diagnostics[0].code'
+{
+  "error": 2,
+  "warning": 0,
+  "info": 0,
+  "hint": 0
+}
+"SYN067"
+```
+
+**Gate a commit hook** on errors, and allow a small warning budget:
+
+```console
+$ sysml-validate models/ --max-warnings 5 && echo "model is publishable"
+```
+
+**Check just what changed**, without loading any model outside that list:
+
+```console
+$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate
+```
+
+If those files need definitions elsewhere in the checkout, opt into workspace
+indexing explicitly:
+
+```console
+$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate --workspace .
+```
+
+`--workspace .` indexes the rest of the project for reference resolution, but
+still reports diagnostics only for the files you named.
+
+**Use it from a coding agent.** The default output is plain text with a stable
+one-line summary, so an agent can act on it directly:
+
+```console
+$ sysml-validate models/ --format compact ; echo "exit=$?"
+models/vehicle.sysml:12:23: error [RES001]: Could not resolve reference to Element named 'Engien'.
+exit=1
+```
+
+## Your project's configuration is honoured
+
+The validator reads the settings your team commits, in the editor's own
+precedence — `.vscode/settings.json` first, then `.vscode/sysml/project.json`:
+
+| Setting | Effect |
+|---|---|
+| `sysml.lint.profile` | `default` / `quiet` / `strict` style-notice volume |
+| `sysml.validation.severities` | Per-code severity overrides (e.g. `{ "SEM006": "warning" }`) |
+| `sysml.diagnostics.unusedImports` | `off` / `warning` / `error` |
+| `sysml.diagnostics.units` | UNIT001–UNIT005 dimensional analysis on/off |
+
+`--lint-profile` overrides the profile for one run, and `--no-config` ignores
+both files. Note that `sysml.validation.severities` covers the validator's own
+codes; unresolved-reference errors (`RES001`) come from the linker and are
+always errors.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | no blocking diagnostics |
+| `1` | errors, or warnings under `--strict` / `--max-warnings` |
+| `2` | the command line or the environment was wrong (bad flag, unreadable path) |
+
+Informational notices and hints never fail a run; they are only printed with
+`--all`.
+
+## GitHub Actions
+
+Fail the build on model errors, with inline annotations on the diff:
+
+```yaml
+- uses: actions/setup-node@v4
+  with: { node-version: 20 }
+
+- name: Validate the SysML model
+  run: npx sysml-validate models/ --format github --strict
+```
+
+Or upload SARIF so diagnostics land in **Security → Code scanning** and on the
+pull request:
+
+```yaml
+- name: Validate the SysML model
+  run: npx sysml-validate models/ --format sarif --out sysml.sarif
+  continue-on-error: true
+
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: sysml.sarif
+```
+
+## License
+
+The CLI uses the extension's Freeware License (see `LICENSE`). The vendored OMG
+standard library under `resources/sysml.library` keeps its upstream OMG
+LICENSE / LICENSE-GPL terms; see that directory's `NOTICE.md`.