Skip to content

Diagnose and inspect a failed build

This tutorial introduces a deliberate type error, captures the compiler's structured diagnostic, asks the compiler to explain its stable code, then verifies the repaired backend output.

  1. BreakCreate one type mismatch
  2. CaptureKeep the diagnostic JSON
  3. ExplainUse the stable code
  4. VerifyRepair and inspect

Step 1: create a deliberate mismatch

In a starter project's src/main.incn, put:

def double(value: int) -> int:
    return value + "2"  # (1)

def main() -> None:
    println(double(21))
  1. This is the only intentional defect: the integer operation receives a string operand.

The function promises an integer calculation but supplies a string operand.

Step 2: capture the diagnostic

Create the report directory, run the check, and preserve its non-zero status:

mkdir -p target
set +e
incan check src/main.incn --format json > target/diagnostics.json  # (1)
check_status=$?
set -e
test "$check_status" -ne 0  # (2)
jq '.diagnostics[0] | {code, phase, message, primary_span, hints}' target/diagnostics.json
  1. Machine-readable output preserves compiler-owned fields without scraping the human rendering.
  2. The failing check is expected here, but the shell still proves that it actually failed.

The JSON record carries the compiler-owned code, phase, message, source span, and hints. CI or an editor can consume those fields without parsing the human terminal rendering.

Step 3: ask the same compiler to explain the code

code="$(jq -r '.diagnostics[0].code' target/diagnostics.json)"
incan explain "$code"

Diagnostic codes and their explanations are versioned with the compiler. Use the code from the captured report rather than hard-coding one in automation.

Step 4: repair and inspect

Make the operation type-correct:

def double(value: int) -> int:
    return value * 2

def main() -> None:
    println(double(21))

Now verify the source and inspect what the current backend would emit:

incan check src/main.incn
incan inspect rust src/main.incn --format json > target/rust-inspection.json
jq '{mode, source_files, rust_files}' target/rust-inspection.json
incan build src/main.incn

incan inspect rust is a debugging and reporting surface. Generated Rust is not the stable source or ABI contract.

You turned one failed check into structured evidence, explained it through the matching compiler catalog, repaired the source, and verified both checking and backend inspection.

Continue