npm package: @intend-it/parser
Description: Parser for the Intend programming language
Latest version: 1.3.4

<div align="center">
  <h1>@intend-it/parser</h1>
  <p><strong>Parser for the Intend Programming Language</strong></p>
  <p>
    <a href="https://intend.fly.dev">Documentation</a> •
    <a href="https://www.npmjs.com/package/@intend-it/parser"><img src="https://img.shields.io/npm/v/@intend-it/parser.svg" alt="npm version"></a>
    <a href="https://www.npmjs.com/package/@intend-it/parser"><img src="https://img.shields.io/npm/dm/@intend-it/parser.svg" alt="npm downloads"></a>
    <a href="https://github.com/DRFR0ST/intend/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@intend-it/parser.svg" alt="license"></a>
  </p>
</div>

---

## 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 📖](https://intend.fly.dev)**

Built with [Chevrotain](https://chevrotain.io/) for robust, fast parsing.

## Installation

```bash
npm install @intend-it/parser
# or
bun add @intend-it/parser
```

## Usage

### Parse to AST

```typescript
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)

```typescript
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

```typescript
interface IntendFile {
  type: "IntendFile";
  imports: ImportNode[];
  intents: IntentDeclaration[];
}
```

### IntentDeclaration

```typescript
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`](https://www.npmjs.com/package/@intend-it/core) - AI-powered code generator
- [`@intend-it/cli`](https://www.npmjs.com/package/@intend-it/cli) - Command-line interface

## License

MIT © [Intend Team](https://github.com/DRFR0ST/intend)