sacm-cli 0.3.0

Validate and convert OMG SACM 2.3 assurance cases
sacm-cli-0.3.0 is not a library.

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; …)) is invalid too: the check could not confirm the file, which does not mean that the file breaks SACM 2.3.
  • --tolerant reads 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 repeated xmi:id and an encoding it cannot decode (exit 2). Its summary says readable, never valid, and invalid when 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:

{"format":1,"file":"case.sacm.xmi","mode":"strict","result":"invalid","refusal":null,"diagnostics":[{"code":"SACM-MULT-001","severity":"error","requirement":"SACM23-VAL-018","clause":"8.6","location":null,"affected":["c1"],"message":"Claim \"c1\" has no name (name:LangString[1])"}]}
  • mode is strict or tolerant.
  • result is valid or invalid in strict mode, readable or invalid with --tolerant, and unreadable for 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) and message. clause is a clause number in the standard that the requirement row cites: SACM 2.3, or XMI 2.5.1 for SACM-ID-* and SACM-XMI-*.
  • refusal is null, 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. location is where the refusal is (for SACM-ID-001, the first repeat); locations is every place it names. code is null for an I/O error and for an Unsupported refusal: input this version cannot read yet, or a defect such as an attribute on xmi:XMI that is neither SACM 2.3 nor XMI 2.5.1. An I/O error also has "location":null and "locations":[].
  • Every key is always present, with null where a value is absent. A location is {"line":L,"column":C}.
  • "format":1 is 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.