Diagnostics

The bwslc compiler reports diagnostics with a severity, compiler phase, message name, and BWSL... code. Human-readable diagnostics are printed by default. Tooling can request structured JSON with -errors-json.

Single-file JSON keeps the original per-file shape. Batch mode and watch mode wrap those per-file documents in aggregate build reports so tools can compile many shaders without losing individual file context.

Text Diagnostics

Without extra flags, diagnostics are written as formatted text on stderr:

Diagnostics: 1 error(s), 0 warning(s)
Error[BWSL1000-6CD49A7E] at line 5, column 9
Expected ';' after expression
Token: '}' (type RIGHT_BRACE)

When a source range is available, the compiler includes nearby source lines and a caret. Stage-level diagnostics can also include the pass and stage that produced the failure.

JSON Diagnostics

Use -errors-json when an editor, CI job, or build tool needs machine-readable output:

bwslc shader.bwsl -errors-json

The long option --errors-json is also accepted. Compatibility aliases -json-errors and --json-errors are recognized as well.

In JSON mode, progress output, timing output, and IR dumps are suppressed so stdout stays parseable. The process exits with a nonzero status when errors remain.

Example output for a missing semicolon:

{
  "schemaVersion": 2,
  "tool": "bwslc",
  "version": "0.8.0",
  "success": false,
  "file": "/path/to/shader.bwsl",
  "errorCount": 1,
  "warningCount": 0,
  "diagnostics": [
    {
      "severity": "error",
      "phase": "parse",
      "code": "BWSL1000-6CD49A7E",
      "name": "ParseError",
      "message": "Expected ';' after expression",
      "file": "/path/to/shader.bwsl",
      "line": 5,
      "column": 9,
      "endLine": 5,
      "endColumn": 10,
      "offset": 128,
      "length": 1,
      "token": "}",
      "tokenType": "RIGHT_BRACE",
      "context": [
        { "line": 4, "text": "            output.position = float4(0.0, 0.0, 0.0, 1.0)" },
        { "line": 5, "text": "        }" },
        { "line": 6, "text": "" }
      ]
    }
  ]
}

Batch JSON

When multiple files, a directory, or -manifest is used with -errors-json, stdout contains one aggregate document for the whole batch:

bwslc shaders/ -check -errors-json

{
  "schemaVersion": 2,
  "tool": "bwslc",
  "version": "0.8.0",
  "batch": true,
  "success": false,
  "fileCount": 2,
  "succeededCount": 1,
  "failedCount": 1,
  "errorCount": 1,
  "warningCount": 0,
  "files": [
    {
      "success": true,
      "file": "/project/shaders/valid.bwsl",
      "errorCount": 0,
      "warningCount": 0,
      "diagnostics": []
    },
    {
      "success": false,
      "file": "/project/shaders/broken.bwsl",
      "errorCount": 1,
      "warningCount": 0,
      "diagnostics": [
        {
          "severity": "error",
          "phase": "parse",
          "code": "BWSL1000-6CD49A7E",
          "name": "ParseError",
          "message": "Expected ';' after expression",
          "file": "/project/shaders/broken.bwsl"
        }
      ]
    }
  ]
}

The nested files entries use the same fields as single-file diagnostic JSON, but omit the shared schemaVersion, tool, and version header.

Watch JSON

With -watch -errors-json, the compiler stays resident and emits one aggregate JSON document per build event:

bwslc shaders/ -modules modules/ -watch -errors-json

{
  "schemaVersion": 2,
  "tool": "bwslc",
  "version": "0.8.0",
  "watch": true,
  "event": "build",
  "buildId": 3,
  "trigger": ["/project/modules/Lighting.bwsl"],
  "removed": [],
  "success": true,
  "fileCount": 1,
  "succeededCount": 1,
  "failedCount": 0,
  "errorCount": 0,
  "warningCount": 0,
  "elapsedMs": 18.4,
  "files": [
    {
      "success": true,
      "file": "/project/shaders/lighting.bwsl",
      "errorCount": 0,
      "warningCount": 0,
      "diagnostics": []
    }
  ]
}

Each watch report is a complete JSON object. Consumers can frame the stdout stream by reading one object at a time.

Schema Fields

Top-level fields:

Aggregate batch/watch fields:

Diagnostic record fields:

Error Code Format

Most diagnostics use a fixed code such as BWSL0103. Some broad diagnostic families add a deterministic fingerprint suffix:

BWSL1000-6CD49A7E

For fingerprinted codes, the base code identifies the category and the suffix distinguishes the phase/message identity. Treat the full string as the unique code for a concrete diagnostic, and group by the base prefix when you want category-level handling.

Fingerprint suffixes are used for:

Code Reference

Integration Tips

• Use code for stable routing, suppression, or issue matching.
• Use severity and success for build failure decisions.
• Use line, column, endLine, endColumn, and context for editor markers.
• Use pass and stage to attach backend or lowering failures to the right pipeline stage.
• Use phase to separate command-line, parser, specialization, lowering, backend, and validation problems.
• For batch and watch integrations, handle the aggregate files array and keep routing errors by each nested file's file field.

See Also

• CLI Reference - Full command-line flag reference
• Integration - Build-system and engine integration
• Language Specification - Source-tree spec and BNF grammar