Tooling and JSON

The stage-0 compiler ships one executable, bin/sprig, built by scripts/build.sh. It has no daemon or language server. The VS Code preview integrates highlighting, CLI diagnostics, Run and generated Java viewing.

Commands

check <file.spr> [--json] [--syntax-only]   parse and type-check
run   <file.spr> [--json] [--keep] [--stacktrace] [-- a b] compile and execute on the JVM
test [PATH] [--filter TEXT] [--json]        run ordinary project test programs
build <file.spr> [-d dir] [--emit-java-only] [--json]          emit Java sources + .class files
help [topic] [--json]                      versioned language reference
capabilities [--json]                     implemented feature inventory
api <Java.Class> [--member NAME] [--classpath JAR] [--json] inspect JVM signatures
wrap <Java.Class> --out FILE.spr [--member NAME] [--force] [--json] generate an editable Sprig wrapper
doctor [--classpath JAR] [--json]         environment report
explain <SPR-CODE> [--json]                 structured diagnostic explanation
codes [--json]                              list every diagnostic code
version

check, build, run, api, wrap and doctor accept repeated --classpath values for local JARs/directories and use the same resolved path. No dependency is downloaded. Use sprig api java.time.LocalDate --json to inspect real JDK signatures.

The published v0.5.0-beta.1 SDK includes the commands above, including test, wrap, run --stacktrace and schema-4 portable locks. Sprig remains an experimental Beta; check the release assets and sprig capabilities --json from the installed SDK for the exact feature set.

• check stops before code generation. --syntax-only stops even earlier, after lexing, layout and parsing.
• run accepts program arguments after -- and --keep for inspecting generated files. Uncaught runtime failures report stable codes (SPR-RUNTIME-ERROR/SPR-RUNTIME-EXCEPTION) with a wrapped message and source range; --stacktrace adds the raw JVM stack for debugging.
• build writes generated Java and .class files to -d (default sprig-build). A failed check produces no class files.
• test runs tests/**/*.spr in isolated child JVMs and checks tests/compile_fail/**/*.spr against sibling diagnostic-code expectations. See the testing contract.
• wrap generates editable Sprig source from a real classpath: it refuses to overwrite without --force, checks the file under the same classpath before writing, and reports generated/skipped members with stable reasons in --json. See the wrapper contract and Fabric / JVM framework integration.
• explain and codes document the stable diagnostic vocabulary in Diagnostic codes.

JSON results

With --json, stdout contains exactly one JSON document, including when the program itself fails. programOutput carries what the program printed, and diagnostics carries structured errors.

A successful run:

{
  "schemaVersion": 1,
  "toolVersion": "sprig-compiler 0.5.0-beta.1",
  "command": "run",
  "exitCode": 0,
  "programOutput": "Hello, Ada!\n",
  "environment": {"classpath": []},
  "diagnostics": []
}

A failed check (path shortened here; the real uri is a file: URI):

{
  "schemaVersion": 1,
  "toolVersion": "sprig-compiler 0.5.0-beta.1",
  "command": "check",
  "exitCode": 1,
  "environment": {"classpath": []},
  "diagnostics": [
    {
      "code": "SPR-MATCH-NONEXHAUSTIVE",
      "phase": "FLOW",
      "severity": "error",
      "uri": "file:///project/tests/semantics/missing_case.spr",
      "range": {
        "start": { "line": 4, "character": 4 },
        "end": { "line": 6, "character": 29 }
      },
      "message": "Missing case: Expr.Add",
      "hint": "Add 'case Expr.Add:' (there is no default case)",
      "related": [],
      "suggestedEdits": []
    }
  ]
}

Positions are zero-based. CLI option and tooling errors use exit code 2; source and runtime failures normally use 1. run forwards the program's process status, so an explicit exit may also return 2 or another value. A nonzero exit without a JVM exception is reported as SPR-PROGRAM-EXIT, with the child status in JSON data.programExitCode.

What the tooling does not do yet

The following are proposed, not implemented:

• an LSP / IDE language server,
• publishing or a module registry,
• incremental checking.

The historical Agent tool protocol contains further proposals. Check sprig capabilities --json for current behavior, and JVM interop for api boundaries.

For agent-assisted workflows

• sprig check --json is the cheapest reliable gate before run: parse, resolve and type-check without generating or executing code.
• Diagnostics carry stable codes, a phase (LEX, SYNTAX, NAME, TYPE, FLOW, JVM, RUNTIME), a range and often a hint naming the next fix.
• run --json keeps program output separate from diagnostics, so a failing program still yields a parseable result.
• The repository's own quality gates are deliberate: see the AI-assisted development disclosure.

sprig build file.spr --emit-java-only -d generated --json performs static checking and writes Java without javac. JSON returns javaSources, mainClass and javacInvoked=false. Use explicit import "@std/files.spr" as files for the SDK bundled standard package. Windows remains experimental.

Canonical formatting

Use sprig fmt file.spr or sprig fmt --check . --json. Formatting is comment-preserving, deterministic and configless, with no aggressive wrapping. See formatter contract. Other commands never rewrite source.