Grammar import

[curtisman]

Add Import System to Action Grammar

Summary

This PR introduces a comprehensive import/module system for action grammars, enabling better code organization and reusability. Grammar definitions can now be split across multiple files and composed through explicit imports, similar to module systems in modern programming languages.

Key Features

Grammar Imports

• Import grammar rules from other .agr files using @import syntax
• Support for named imports: @import { RuleA, RuleB } from "./rules.agr"
• Support for wildcard imports: @import * from "./rules.agr"
• Relative path resolution with proper file loading abstraction

Type Imports

• Import TypeScript types from .ts files for compile-time validation
• Separate handling for type imports vs grammar imports
• Types are validated at compile-time but don't require file loading
• Example: @import { CustomType } from "./types.ts"

File Extension Change

• Grammar files now use .agr extension instead of .grammar in tests.
• More concise and distinctive file extension for action grammars

Circular Dependency Support

• Full support for circular imports between grammar files (A->B->A)
• Multi-file circular dependencies (A->B->C->A)
• Proper resolution and context reuse to prevent infinite loops

File Loading Abstraction

• New FileLoader interface for customizable file resolution and loading
• Default file loader implementation using Node.js fs and path modules
• Enables testing with in-memory file systems
• Cross-platform path handling (tested on Windows and Unix)

Technical Changes

New Files

• defaultFileLoader.ts - Default file system implementation
• grammarImports.spec.ts - Comprehensive test suite (824 lines)
• grammarCompileError.spec.ts - Validation error tests

Modified Core Files

• grammarCompiler.ts - Import resolution, validation, and circular dependency handling
• grammarRuleParser.ts - Parse @import statements, distinguish grammar vs type imports
• grammarLoader.ts - File loading integration and context management

Test Coverage

The PR includes test coverage for:

• ✅ Basic single and multiple rule imports
• ✅ Imports from multiple files
• ✅ Wildcard imports
• ✅ Multi-level import chains
• ✅ Nested directory imports
• ✅ Complex directory structures
• ✅ Missing file error handling
• ✅ Undefined import error handling
• ✅ Type imports from .ts files
• ✅ Circular dependency support (2-way and 3-way)
• ✅ Cross-platform path handling

Example Usage

// colors.agr
@<Red> = red -> "red"
@<Blue> = blue -> "blue"
@<Green> = green -> "green"

// actions.agr
@import { Red, Blue, Green } from "./colors.agr"
@<SetColor> = set color to (<Red> | <Blue> | <Green>) -> { action: "setColor", color: $(1) }

// main.agr
@import { SetColor } from "./actions.agr"
@import { CustomType } from "./types.ts"

@<Start> = <SetColor> | <OtherCommand>

Migration Notes

• Grammar files should have extention .agr
• All non-built-in type references now require explicit imports
• File loader can be customized by passing a `FileLoader` implementation to `loadGrammarRules`