@isl-lang/isl-core

@isl-lang/isl-core

The "thin waist" API for the Intent Specification Language (ISL). This package provides the essential compiler flow for parsing, checking, formatting, linting, and verifying ISL specifications.

What's Included

Core APIs (Stable)

Module	Export	Description
Parse	parseISL()	Parse ISL source code into an AST
Check	check()	Type check and semantic analysis
Format	format(), fmt()	Pretty-print AST back to source
Lint	lint()	Style and best-practice checks
Compile	compile()	Full compilation pipeline

Additional APIs (Stable)

Module	Export	Description
Imports	resolveImports()	Import resolution between ISL files
Verification	verification.*	Verify implementations against specs

Experimental APIs

Module	Export	Description
TestGen	testgen.*	Generate tests from specifications

Note: Experimental APIs may change in minor versions. Stable APIs follow semver.

Installation

npm install @isl-lang/isl-core
# or
pnpm add @isl-lang/isl-core

Quick Usage

Parse ISL Source

import { parseISL } from '@isl-lang/isl-core';

const source = `
domain MyDomain {
  entity User {
    id: UUID
    email: String
  }
}
`;

const result = parseISL(source);

if (result.errors.length > 0) {
  console.error('Parse errors:', result.errors);
} else {
  console.log('AST:', result.ast);
}

Full Compilation Pipeline

import { compile } from '@isl-lang/isl-core';

const result = compile(source, {
  check: { strict: true },
  lint: { rules: { 'naming/entity-pascal-case': true } },
});

console.log('Success:', result.success);
console.log('Diagnostics:', result.check?.diagnostics);
console.log('Lint messages:', result.lint?.messages);
console.log('Formatted:\n', result.formatted);

Type Checking Only

import { parseISL, check } from '@isl-lang/isl-core';

const { ast } = parseISL(source);
if (ast) {
  const checkResult = check(ast, { strict: true });
  
  for (const diag of checkResult.diagnostics) {
    console.log(`${diag.severity}: ${diag.message}`);
  }
}

Formatting

import { parseISL, format } from '@isl-lang/isl-core';

const { ast } = parseISL(source);
if (ast) {
  const formatted = format(ast, {
    indent: '  ',
    maxWidth: 80,
    sortDeclarations: true,
  });
  console.log(formatted);
}

Linting

import { parseISL, lint, getRules } from '@isl-lang/isl-core';

// See available rules
console.log(getRules());

const { ast } = parseISL(source);
if (ast) {
  const result = lint(ast, {
    rules: {
      'best-practice/require-description': true,
      'naming/field-camel-case': true,
    },
  });
  
  for (const msg of result.messages) {
    console.log(`[${msg.ruleId}] ${msg.message}`);
  }
}

Verification

import { verification } from '@isl-lang/isl-core';

const sourceCode = `
// @isl-bindings
// CreateUser.pre.1 -> guard at L15
// @end-isl-bindings

function createUser(input) {
  if (!input.email.includes('@')) {  // L15
    throw new Error('Invalid email');
  }
  // ...
}
`;

const result = verification.verify(sourceCode, {
  clauses: [
    { id: 'CreateUser.pre.1', type: 'precondition', expression: 'email.contains("@")' },
  ],
});

console.log(verification.formatVerificationSummary(result));

Test Generation (Experimental)

import { parseISL, testgen } from '@isl-lang/isl-core';

const { ast } = parseISL(source);
if (ast) {
  const suite = testgen.generateTests(ast, {
    framework: 'vitest',
    includeBoundary: true,
    includeErrors: true,
  });
  
  for (const test of suite.tests) {
    console.log(`${test.category}: ${test.name}`);
  }
}

Subpath Exports

For tree-shaking, you can import specific modules:

import { check } from '@isl-lang/isl-core/check';
import { format } from '@isl-lang/isl-core/fmt';
import { lint } from '@isl-lang/isl-core/lint';
import { resolveImports } from '@isl-lang/isl-core/imports';
import { verify } from '@isl-lang/isl-core/verification';
import { generateTests } from '@isl-lang/isl-core/testgen';

API Reference

parseISL(source: string, filename?: string): ParseResult

Parse ISL source code into an AST.

compile(source: string, options?): CompileResult

Run the full compilation pipeline (parse → check → lint → format).

check(ast: DomainDeclaration, options?): CheckResult

Type check and semantic analysis.

Options:

• allowUndefinedTypes: Allow undefined type references
• strict: Treat warnings as errors

format(ast: DomainDeclaration, options?): string

Format AST back to source code.

Options:

• indent: Indentation string (default: 2 spaces)
• maxWidth: Maximum line width (default: 80)
• sortDeclarations: Sort declarations alphabetically

lint(ast: DomainDeclaration, options?): LintResult

Check for style and best-practice issues.

Options:

• rules: Enable/disable specific rules
• severities: Override rule severities

verification.verify(sourceCode: string, spec: SpecInfo, options?): VerificationResult

Verify implementation code against ISL specification.

testgen.generateTests(ast: DomainDeclaration, options?): TestSuite

Generate test cases from behavior specifications.

Version Information

import { VERSION, API_VERSION } from '@isl-lang/isl-core';

console.log(`Version: ${VERSION}`);  // "0.1.0"
console.log(`API Version: ${API_VERSION}`);  // 1

License

MIT