sacm-cli
Command-line tool for OMG SACM 2.3 assurance cases, built on the
sacm library.
Status: early development. What the library reads and checks is tracked in the functionality matrix.
$ cargo install sacm-cli
$ sacm version
sacm 0.1.0 (SACM 2.3)
Commands
sacm validate <file> [--strict | --tolerant] [--format human|json]
Reads the file strictly, the default, validates it, and reports the read and validation
diagnostics together, sorted. A file is valid only when a strict read accepts it and no
diagnostic is an Error; a recognised variation such as xsi:type is an Error. --strict
names the default. Giving both flags is a usage error.
- A file that a strict read refuses but a tolerant read opens is
invalid(exit 1). The refusal is printed on stdout, then<file>: invalid (refused by a strict read; --tolerant opens it). - A strict refusal of conforming content this version does not read yet (its message
ends
(a limit of this version; …)) isinvalidtoo: the check could not confirm the file, which does not mean that the file breaks SACM 2.3. --tolerantreads in tolerant mode, which also opens a file that a strict read refuses for a bad value or for content this version does not read yet, and reports what a strict read refuses as Warnings. It still refuses a DOCTYPE, malformed XML, a root outside SACM 2.3, a repeatedxmi:idand an encoding it cannot decode (exit 2). Its summary saysreadable, nevervalid, andinvalidwhen a diagnostic is an Error.
$ sacm validate case.sacm.xmi
error SACM-MULT-001 [SACM23-VAL-018, clause 8.6]: Claim "c1" has no name (name:LangString[1])
case.sacm.xmi: invalid (1 error, 0 warnings, 0 info)
--format json prints one object on one line:
modeisstrictortolerant.resultisvalidorinvalidin strict mode,readableorinvalidwith--tolerant, andunreadablefor a file neither a strict nor a tolerant read opens.- Each diagnostic has the keys
code,severity("error","warning"or"info"),requirement(the matrix row),clause,location,affected(element ids) andmessage.clauseis a clause number in the standard that therequirementrow cites: SACM 2.3, or XMI 2.5.1 for SACM-ID-* and SACM-XMI-*. refusalisnull, or{"code","location","locations","message"}: the strict refusal of a file only a tolerant read opens (with"result":"invalid"and"diagnostics":[]), or the refusal of an unreadable file, in the mode asked for.locationis where the refusal is (for SACM-ID-001, the first repeat);locationsis every place it names.codeisnullfor an I/O error and for anUnsupportedrefusal: input this version cannot read yet, or a defect such as an attribute onxmi:XMIthat is neither SACM 2.3 nor XMI 2.5.1. An I/O error also has"location":nulland"locations":[].- Every key is always present, with
nullwhere a value is absent. A location is{"line":L,"column":C}. "format":1is the version of this shape. Keys may be added; a rename, a removal or a change of meaning moves it to 2. Codes are stable; message texts and the human format are not.
In JSON mode every result, including an unreadable file, is the JSON object on stdout, and stderr is empty. Only a usage error (exit 2) goes to stderr, as text, with no JSON.
sacm roundtrip <file> [--strict] [-o <out>]
Reads the file (tolerant by default), writes it in strict mode to memory, reads that
output back in strict mode, and compares the two documents. It prints
<file>: round trip ok, or each problem and then <file>: round trip failed: ….
Read diagnostics are not reported or checked; run sacm validate for them. --strict
changes only their severity, so in this release it does not change the result.
With -o, it writes the strict output to <out>, only when the round trip is faithful,
so sacm roundtrip -o converts a file to the strict form safely.
Exit codes
| Code | Meaning |
|---|---|
| 0 | The check passed. |
| 1 | The check ran and failed: for validate, an Error diagnostic, or a strict refusal of a file a tolerant read opens; for roundtrip, a refused strict save, output that does not read back, or a difference. |
| 2 | The tool could not do the job: a usage error, an I/O error, or input it cannot read: for validate, input neither a strict nor a tolerant read opens; for roundtrip, input the reader refuses. |
stdout carries the result; stderr carries only what stopped the command, such as
sacm: case.sacm.xmi: SACM-XML-001 the input is not well-formed XML at ….
License
MIT. See LICENSE.