Oska AST export

oskac parse <file.osk> --format=json writes the syntax tree as JSON. Agents and tools can build on this format.

Envelope

{
  "ast_version": 1,
  "file": "examples/hello.osk",
  "items": [ ... ]
}

Prelude mode

The prelude is Oska source embedded in the checker. It is parsed in prelude mode (parse_prelude in oska-syntax), which accepts two things user code cannot write. Both appear in the export like any other node.

• Body-less functions. Any FnItem, whether a module-level function or a method in an impl, may end after its signature, because its behavior is built in. Its body is absent. In user code a missing body is error E0101, an expected {.
• #[capability]. It marks a StructItem as a built-in capability: an opaque struct with private fields. On any other item or method it is error E0170. In user code it is an unknown attribute, error E0132.

Stability

• Within a major ast_version, changes are additive only. New node kinds and new fields can appear. Existing fields are never renamed, removed, or given a new meaning.
• Consumers must ignore fields and node kinds they don't recognize.
• Breaking changes increase ast_version. The previous version stays available through --ast-version=N for at least one release.

Nodes

Every node is a JSON object with:

• "kind": the node type, as a string, for example "FnItem" or "CallExpr".
• "span": {"start": <byte>, "end": <byte>}, a half-open byte range into the source file. These are the same spans that diagnostics use.

Diagnostics

When parsing fails, --format=json prints one diagnostic object instead of the envelope:

{
  "code": "E0151",
  "message": "an `impl` block cannot be `pub`; ...",
  "span": {"start": 0, "end": 3},
  "fix": {
    "message": "remove `pub`",
    "edits": [{"span": {"start": 0, "end": 4}, "replacement": ""}]
  }
}

• code is stable: tools should match on it, not on message. Lexer codes are E00xx and parser codes are E01xx; the full list is in the module docs of crates/oska-syntax/src/parser.rs.
• span uses the same byte ranges as nodes.
• fix is optional and omitted when absent. It is present only when the edit is unambiguous, so a tool can apply it without asking. Each edit replaces the source text at its span with replacement: an empty span inserts, and an empty replacement deletes. Edit spans refer to the original source and never overlap. Applying every edit fixes that diagnostic, though later errors in the file may remain.

Diagnostics that carry a fix:

Node schema

Conventions:

• Every node's first two fields are kind and span. The tables below list the other fields.
• Field names are snake_case. kind values are PascalCase, and end in Item, Stmt, Expr, Pattern, or Type for those node families.
• An optional field is omitted when absent. It is never written as null.
• An array field is always present, even when empty.
• "Expression node", "statement node", "pattern node", and "type node" mean any node of that family.

Items

Every item node starts with the same two fields, before its own fields:

An item's span starts at its first attribute, if it has one, and otherwise at pub or its keyword. The tables below list only each item's own fields.

public is always false for UseItem (pub use is error E0164, because re-exports are not defined in v0), TestItem (pub test is error E0163), ImplItem (error E0151), and the methods of a TraitItem (error E0162).

FnItem

A function declaration: fn name<generics>(params) -> T requires ... ensures |r| ... { body }. The contract clauses sit between the return type and the body, and may each start a new line. The same node is used for the methods of ImplItem and TraitItem.

A self or var self receiver is allowed only on a method in an impl or trait block. On a module-level function it is error E0150.

UseItem

An import: use a.b or use a.b.{X, y}. Glob imports (use a.*, error E0130) and renaming imports (use a.b as c, error E0131) are rejected, so every imported name is written out. An import is never pub (error E0164): re-exports are not defined in v0.

ConstItem

A module-level constant: const NAME: T = expr.

TestItem

A test: test "a descriptive name" { body }. Tests that need real capabilities carry #[integration]. A test is never pub (error E0163).

StructItem

A struct declaration: struct Point { x: Int, y: Int } (named fields) or struct Meters(Int) (positional fields). Fields are separated by commas, and a trailing comma is allowed.

EnumItem

An enum (sum type) declaration: enum Shape { Circle { radius: Int }, Rect(Int, Int), Empty }. Variants are separated by commas, and a trailing comma is allowed.

TraitItem

A trait declaration: trait Name<generics> { methods }. Methods are separated by line breaks. A method either ends after its signature (its FnItem has no body) or has a default body. A trait method takes its visibility from the trait, so it is never pub (error E0162) and its public is always false. Trait objects (dyn), associated types, and where clauses are not part of v0.

ImplItem

Methods for a type: impl<generics> Type { methods } for inherent methods and associated functions, or impl<generics> Trait for Type { methods } for a trait implementation. Methods are separated by line breaks, and each needs a body, except in the prelude. An impl block is never pub (error E0151), so public is always false; each method carries its own public.

Shared nodes

Ident

A name as written in source, such as a function, parameter, or field name.

Param

A function parameter, name: Type. Capability parameters such as fs: FsRead are ordinary parameters, so a function's authority can be read from its params.

SelfParam

A method's receiver: self, or var self for a mutating method. It can only be the first parameter. The span covers var when present.

GenericParam

A generic parameter with its inline bounds: T: Eq + Hash. There are no where clauses.

RequiresClause

A precondition, requires cond. The span covers the keyword and the condition.

EnsuresClause

A postcondition, ensures |r| cond, where r names the return value. The span covers the keyword and the condition.

Field

A declared field of a struct or enum variant: pub name: Type when named, or pub Type when positional. The span starts at pub when present.

Variant

An enum variant: Some(T) (positional), Circle { radius: Int } (named), or None (unit).

Block

A { ... } block. Its value is the value of its last statement if that statement is an ExprStmt.

Arg

A call argument, optionally labelled: copy(src: a). The span covers the label and the value.

Attribute

An attribute on an item: #[name] or #[name(args)]. Names come from a fixed set, currently only integration; any other name is error E0132. #[integration] is allowed only on a TestItem; on any other item or method it is error E0165. The prelude may also use capability (see Prelude mode).

ClosureParam

A closure parameter with an optional type: |x: Int, y|.

StrText

Literal text inside a string. The span covers the raw source text, escapes included.

StrHole

An interpolation hole such as {user.name}. The span includes the braces.

Statements

LetStmt

let name: T = value, or var for a mutable binding. The initializer is required.

AssignStmt

target = value.

ReturnStmt

return, with an optional value.

BreakStmt

break.

No fields beyond kind and span.

ContinueStmt

continue.

No fields beyond kind and span.

ForStmt

for binding in iter { body }.

WhileStmt

while cond { body }.

ExprStmt

An expression used as a statement.

Expressions

IntExpr

An integer literal.

StrExpr

A string literal, split into text and interpolation holes.

SinkStrExpr

A sink literal such as sql"...". It never contains holes.

BoolExpr

true or false.

UnitExpr

The unit value ().

No fields beyond kind and span.

NameExpr

A bare name. Its span is the name's span, so the name is a plain string.

SelfExpr

The receiver self.

No fields beyond kind and span.

FieldExpr

base.name: a field, method, module member, or enum variant. The parser does not resolve which.

CallExpr

callee(args). A method call is a call whose callee is a FieldExpr.

UnaryExpr

A prefix operator.

BinaryExpr

A binary operator.

TryExpr

Postfix ?.

RangeExpr

start..end, which excludes end.

ListExpr

[a, b, c].

ClosureExpr

|params| body.

IfExpr

if cond { ... } else ....

BlockExpr

A block used as an expression. Its span is the block's span, so the statements sit directly on the node.

ScopeExpr

scope |handle| { body }.

MatchExpr

match scrutinee { arms }, with one arm per line and no commas between arms.

MatchArm

One arm of a match: pattern if guard => body. The span runs from the pattern to the end of the body.

Patterns

v0 has no or-patterns (A | B), range patterns (1..5), or @ bindings. The parser rejects them with E0140, E0141, and E0142.

WildcardPattern

_, which matches anything and binds nothing. It has no other fields.

LiteralPattern

A literal to compare against: an integer, a negated integer such as -1, a string, true, false, or ().

BindingPattern

A bare name, which binds the matched value. Its span is the name's span, so the name is a plain string. The parser cannot tell a binding from a unit variant or constant written as a bare name, such as None; name resolution decides that.

ConstructorPattern

A struct or enum variant pattern. It mirrors call-style construction (ADR 0004): positional Some(x), named Shape.Circle(radius: r), or a dotted path alone, such as Shape.Empty.

PatternArg

A constructor pattern argument, optionally labelled with a field name: radius: r. The span covers the label and the pattern.

Types

PathType

A named type, possibly qualified and generic: std.io.Error, Result<T, E>.

UnitType

().

No fields beyond kind and span.

FnType

fn(T) -> U, or cap fn(T) -> U when the function may capture capabilities.