Collie

A linter and formatter for Lrama Style BNF grammar files (.y files).

Collie checks grammar files for common mistakes, formats them consistently, and supports Lrama-specific syntax such as parameterized rules, named references, and inline rules.

Installation

gem install collie

Or add it to your Gemfile:

gem "collie", require: false

Collie requires Ruby 3.2 or newer.

Quick Start

# Lint files, globs, or directories
collie lint parse.y
collie lint "src/**/*.y"
collie lint grammars/

# Format
collie fmt parse.y
collie fmt --check parse.y
collie fmt --diff parse.y

# Auto-correct supported lint offenses
collie lint -a parse.y

# Inspect rules
collie rules
collie explain DuplicateToken

Configuration

Generate a config file:

collie init
collie init --profile lrama
collie init --profile strict --path .collie.yml

Profiles: default, lrama, bison, strict, minimal.

Minimal .collie.yml:

include:
  - "src/**/*.y"
exclude:
  - "vendor/**/*"

formatter:
  indent_size: 2
  max_line_length: 120

rules:
  TokenNaming:
    severity: convention
  LeftRecursion:
    enabled: false

Commands

Command	Purpose
collie lint [OPTIONS] FILES	Lint grammar files. Supports `--format text\
collie fmt [OPTIONS] FILES	Format grammar files. Supports --check, --diff, --config, and --stdin.
`collie rules [--format text\	json]`
`collie explain RULE [--format text\	json]`
collie config-schema	Print the JSON Schema for .collie.yml.
collie tokens FILE	Print lexer tokens as JSON.
collie ast FILE	Print the parsed AST as JSON.
collie version	Print the installed version.

Run collie help COMMAND for all options.

CI

Use the reusable GitHub Actions workflow:

name: Lint Grammar Files

on: [push, pull_request]

jobs:
  lint:
    uses: ydah/collie/.github/workflows/lint.yml@main
    with:
      files: "src/**/*.y"
      config: ".collie.yml"
      fail-on-warnings: true

For code scanning integrations:

collie lint --format sarif parse.y

Development

bundle install
bundle exec rspec
bundle exec rake

Documentation

• Tutorial
• Changelog

License

MIT License. See LICENSE.txt.