[teo1747]

What it adds

emb-hwgen validate, generate and check take --format json. The command then prints a single JSON document on standard output and nothing else. hw/schemas/diagnostics.schema.json defines the document. EmbLink Studio's first stage (S1) reads it, so the IDE never parses text.

{
  "tool": "emb-hwgen", "version": "0.1.0", "format": 1, "command": "validate",
  "status": "errors", "exit_code": 2, "files": [],
  "diagnostics": [
    {"severity": "error", "rule": "HW-002", "file": "boards/st/nucleo_f446re/board.yaml", "line": 26,
     "path": "console.baud", "message": "expected integer, found string 'fast'",
     "text": "boards/st/nucleo_f446re/board.yaml:26: console.baud: expected integer, found string 'fast'"}
  ]
}

• status and exit_code:
  • ok (exit 0): warnings are still possible;
  • errors (exit 2): the descriptions are wrong;
  • stale (exit 1): check found outdated outputs or hardware facts outside a description;
  • internal-error (exit 3): the generator itself failed. The document carries the exception's type and message, and the traceback goes to stderr. The Python 3.11 crash (hw/gen, ci: the generator's clock errors on Python 3.10 and 3.11 #142) would have reached the IDE this way.
• Findings:
  • each finding keeps its file, line, node path and message as separate fields, plus the original text line;
  • rule is HW-002, HW-001 or HW-003;
  • HW-003 findings carry the diff.
• files lists what generate wrote, and boards counts what check checked.
• format is the document's own version: a new field keeps it, and a changed or removed field bumps it.

Text output is unchanged.

How it's built and tested

• One parser: findings are split from the existing HW-002 text (file:line: node.path: message) in one place, emb_hwgen/diagnostics.py.
• Round-trip check: every error that the negative tests raise must rebuild exactly from its parts. That check found node paths containing a compatible (bindings.st,stm32f4-iwdg.class), which the pattern now allows.
• Seven new tests (110 total) cover every status: OK with warnings, a located description error, generate's file list, stale output with its diff, a board root without boards/, an internal error, and Windows and HW-001 lines. Each document is validated against the schema with the in-tree validator.
• Python 3.10: five tests fail there, the Fraction bug that hw/gen, ci: the generator's clock errors on Python 3.10 and 3.11 #142 fixes.
• Docs: docs/engineering/hwgen.md documents the output, with an example taken from a real run, and the docs build passes.

Signed-off-by: teo1747 motsoujunior17@gmail.com