Abstract Syntax Tree (AST)

The AST is the bridge between human-readable .intent files and the machine-understandable context sent to the AI.

Parsing Library

We use Chevrotain for high-performance lexing and parsing. It allows us to define a fault-tolerant grammar that can evolve easily.

AST Structure

The root node is IntendFile, which represents a single parsed file.

export interface IntendFile {
  type: "IntendFile";
  imports: ImportNode[];
  intents: IntentDeclaration[];
}

IntentDeclaration

Represents a single intent FunctionName(...) -> ReturnType block.

export interface IntentDeclaration {
  type: "IntentDeclaration";
  name: string;
  parameters: ArgumentNode[];
  returnType: ReturnTypeNode;
  body: BodyNode;
  entryPoint?: boolean; // true if 'entry' keyword used
}

BodyNode

The body separates the different "goals" of the intent:

export interface BodyNode {
  invariants: InvariantNode[]; // Safety contracts
  steps: StepNode[];           // Logic instructions
  ensures: EnsureNode[];       // Post-conditions
  returnStmt?: ReturnNode;     // Explicit return
}

StepNode

Steps are the core logic units.

export interface StepNode {
  type: "Step";
  
  // The natural language instructions
  instruction: string; // e.g., "Calculate hash"
  
  // Optional variable binding
  // step "..." => const hash
  resultVariable?: string; // "hash"
  variableKind?: "const" | "let";
}

Why not just send the text?

Parsing to an AST allows us to:

1. Validate References: We can check if you are importing non-existent intents before generating code.
2. Smart Prompting: We can restructure the prompt. For example, we put invariants (safety rules) at the top of the system prompt to ensure they have higher attention weight than the steps.
3. Tooling: The AST powers the CLI, VS Code extension (future), and potential linters.