isl-lang.org / parser

@isl-lang/parser

First published: 2026-05-11 · commit 62d62246

Zero-dependency TypeScript parser for the ISL grammar. Ships ESM and CJS builds. Strict types, no any.

Installation

npm / pnpm / yarn

npm install @isl-lang/parser
# or
pnpm add @isl-lang/parser
# or
yarn add @isl-lang/parser

npmjs.com/package/@isl-lang/parser · github.com/isl-lang/parser

1. Parse

Feed source text to parse(). Returns a typed result object containing all discovered intent blocks and any parse diagnostics.

parse.ts

import { parse } from '@isl-lang/parser';

const source = `
  @isl:begin
    pure: true;
    maxComplexity: 5;
  @isl:end
  export function computeHash(input: string): string {
    // …
  }
`;

const result = parse(source);
// result.ok === true
// result.intentBlocks[0].constraints[0].key === 'pure'

2. Walk the AST

Use walk() to visit every constraint and violation node without traversing the raw AST manually.

walk.ts

import { parse, walk } from '@isl-lang/parser';

const result = parse(source);

walk(result.intentBlocks, {
  onConstraint(node) {
    console.log(node.key, '->', node.value);
    // pure -> true
    // maxComplexity -> 5
  },
  onViolation(violation) {
    console.error(violation.code, violation.message);
  },
});

3. Serialize

serialize() converts a parsed (and optionally mutated) result back to canonical ISL annotation text.

serialize.ts

import { parse, serialize } from '@isl-lang/parser';

const result = parse(source);

// Round-trip: parse → mutate → serialize
result.intentBlocks[0]!.constraints.push({
  key: 'sideEffects',
  value: false,
});

const output = serialize(result);
// Emits canonical ISL annotation text

Full API reference at github.com/isl-lang/parser →