sysml-validate 0.10.15

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,190 @@
+# 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>    Project root holding .vscode/ (default: auto-detected).
+  --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.
+
+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**, letting the rest of the project resolve around it:
+
+```console
+$ git diff --name-only --diff-filter=d origin/main | grep -E '\.(sysml|kerml)$' | xargs -r sysml-validate
+```
+
+Cross-file references still resolve: the whole project is indexed for lookups,
+while only the files you name are reported on.
+
+**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`.