Semantic validation rejects SDL with imports and reports errors only as a count #1548

Problem

raes semantic validate reads one document as text, so it cannot validate SDL that uses imports, and it hides the reason. When it does find semantic errors, it reports only how many.

1. Imports. The command parses the document with parse_sdl(), which refuses top-level imports with SDLParseError("SDL imports require file-backed parsing via parse_sdl_file()") (raes/parser.py:383 on dev a4357f9a). The CLI reports every SDLParseError with the message "SDL input was rejected at the parse stage.", and an error without structured diagnostics, like this one, only as the generic sdl.parse code (raes_cli/_semantic_sdl.py:69-87). On dev a4357f9a:

   $ raes semantic validate contracts/fixtures/sdl/variation-points-v1/composition/root.yaml
   validate: invalid
   error [sdl.parse] SDL input was rejected at the parse stage.
   

   It exits 1, although the composed scenario is valid.

2. Semantic errors. An SDLValidationError becomes one diagnostic, "SDL semantic validation reported N error(s)." (_semantic_sdl.py:88-95), which names none of the errors. docs(explain): point getting-started at raes semantic validate #1489 shows first-scenario.sdl.yaml with a broken link reported this way, while parse_sdl_file() on the same text names the error: Infrastructure 'web' links to undefined 'missing-network'.

#1489 and #1492 document both limits in docs/explain/getting-started.md and docs/public/guides/cli.md, so the guides describe current behavior, but the command still cannot validate a composed scenario.

Scope

• Parse a file argument with parse_sdl_file() so that its imports compose, and keep text parsing for standard input with a diagnostic that says file-backed parsing is needed for imports.
• Carry the parse reason into the sdl.parse diagnostic.
• Report each semantic error as its own diagnostic, with a bound like the 20-diagnostic cap on parse diagnostics.
• Update the limits that docs(explain): point getting-started at raes semantic validate #1489 and docs(guides): correct the imports, rename and CLI-reference statements in the CLI and Python guides #1492 add to the guides.
• The change is package code under implementations/python/packages, which the research-evidence digest covers, so both research captures are republished in the same pull request.

Done when

• raes semantic validate contracts/fixtures/sdl/variation-points-v1/composition/root.yaml exits 0.
• SDL with imports read from standard input gets a diagnostic that names file-backed parsing.
• A document with semantic errors gets one diagnostic per error, naming it, and the exit code is unchanged.
• The guide text matches the new behavior.

Related

• docs(explain): point getting-started at raes semantic validate #1489, docs(guides): correct the imports, rename and CLI-reference statements in the CLI and Python guides #1492 (noted it)
• docs: guide users through SDL validation, compilation, and plan inspection #613 (guide for SDL validation, compilation and plan inspection)