Overview

@intend-it/parser is the lexer and parser for the Intend programming language. It transforms .intent source files into a structured Abstract Syntax Tree (AST) that can be used for code generation, analysis, or tooling.

Read the full documentation 📖

Built with Chevrotain for robust, fast parsing.

Installation

npm install @intend-it/parser
# or
bun add @intend-it/parser

Usage

Parse to AST

import { parseToAST } from "@intend-it/parser";

const source = `
export intent Greet(name: string) -> string {
    step "Create a greeting message" => const message
    ensure message is defined
}
`;

const result = parseToAST(source);

console.log(result.ast);
// {
//   type: "IntendFile",
//   imports: [],
//   intents: [{
//     name: "Greet",
//     parameters: [{ name: "name", type: "string" }],
//     returnType: { base: "string" },
//     body: { ... }
//   }]
// }

Parse to CST (Concrete Syntax Tree)

import { parse } from "@intend-it/parser";

const result = parse(source);

if (result.lexingErrors.length > 0) {
  console.error("Lexing errors:", result.lexingErrors);
}
if (result.parsingErrors.length > 0) {
  console.error("Parsing errors:", result.parsingErrors);
}

console.log(result.cst); // Raw CST from Chevrotain

AST Structure

IntendFile

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

IntentDeclaration

interface IntentDeclaration {
  name: string;
  isExported: boolean;
  isEntry: boolean;
  parameters: Parameter[];
  returnType: ReturnType;
  body: {
    invariants: InvariantNode[];
    steps: StepNode[];
    ensures: EnsureNode[];
  };
}

Language Features Supported

| Feature | Syntax | Example | |---------|--------|---------| | Intents | intent Name(params) -> Type { ... } | intent Add(a: number, b: number) -> number | | Steps | step "instruction" | step "Validate the input" | | Direct Calls | Intent(args) | Log(msg) => const res | | Result Variables | => const x or => let x | step "Calculate" => const result | | Invariants | invariant "rule" | invariant "Input must be positive" | | Ensures | ensure expression | ensure result is defined | | Imports | import { X } from "path" | import { User } from "./types" | | Context | context "Message" | context "Handle currency as integers" | | Entry Points | entry intent Main() | export entry intent Main() -> void |

Related Packages

• @intend-it/core - AI-powered code generator
• @intend-it/cli - Command-line interface

License

MIT © Intend Team