@lanexio/parser-grammar-kit

This page documents @lanexio/parser-grammar-kit, the grammar authoring toolkit for building and validating Lanexio Parser grammar packages. This is a build-time utility, not a runtime dependency.

• Version: Internal
• Module name: parser-grammar-kit
• Package: @lanexio/parser-grammar-kit
• Import path: @lanexio/parser-grammar-kit
• Layer: Build
• Runtime: Node.js (build-time only)
• Module format: ESM
• Stability: Internal (build-time utility)
• Primary use case: Validate grammar metadata and generate kind module source.

Layer contract

Build layer rules

This package is build-time only. It is never a runtime dependency for any Lanexio Parser package. It validates grammar metadata and generates TypeScript source for kind constants.

When to use this module

• You are authoring a new grammar package for Lanexio Parser.
• You need to validate grammar metadata before code generation.
• You need to emit a deterministic TypeScript kind module from grammar metadata.

Module boundary

Boundary	Description
Inputs	GrammarMetadata, EmitKindModuleOptions
Outputs	GrammarMetadataValidationResult, KindModuleEmitResult (with source string)
Side effects	None
Determinism	Yes (same metadata + options produce same output)
External dependencies	@lanexio/parser-core
Never-throw guarantee	No: validation returns { ok: false, diagnostics } on error.
Security surface	None (build-time tool, no input processing)

Installation

1. Install the package.

   pnpm

   pnpm add -D @lanexio/parser-grammar-kit

   npm

   npm install --save-dev @lanexio/parser-grammar-kit

   yarn

   yarn add --dev @lanexio/parser-grammar-kit

2. Import the named export.

   import { validateGrammarMetadata, emitKindModule } from '@lanexio/parser-grammar-kit';

Peer dependencies

Requirement	Required	Layer	Notes
@lanexio/parser-core	Yes	1	^1.0.0

Basic Usage

import { validateGrammarMetadata, emitKindModule } from '@lanexio/parser-grammar-kit';

const metadata = {
  name: '@lanexio/parser-grammar-example',
  version: '1.0.0',
  protocolVersion: 3,
  kinds: [
    { name: 'Document', id: 0x100, named: true },
  ],
  fields: [
    { name: 'value', id: 1 },
  ],
};

const validation = validateGrammarMetadata(metadata);
if (validation.ok) {
  const result = emitKindModule(metadata, { exportName: 'ExampleKind' });
  if (result.ok) {
    console.log(result.source);
  }
}

Exports

Export	Type	Description
validateGrammarMetadata	(metadata: GrammarMetadata) => GrammarMetadataValidationResult	Validate grammar metadata shape. Returns { ok, diagnostics }.
emitKindModule	(metadata: GrammarMetadata, options: EmitKindModuleOptions) => KindModuleEmitResult	Emit a deterministic TypeScript kind module.

Options

EmitKindModuleOptions

Field	Type	Required	Default	Description
exportName	string	Yes	-	PascalCase name for the exported kind constant object.
fieldExportName	string	No	{exportName}Field	PascalCase name for the exported field constant object.

Return shape

GrammarMetadataValidationResult

Property	Type	Description
ok	boolean	Whether validation passed.
metadata	GrammarMetadata	The validated metadata (when ok: true).
diagnostics	GrammarMetadataDiagnostic[]	List of validation errors (when ok: false).

KindModuleEmitResult

Property	Type	Description
ok	boolean	Whether emission succeeded.
source	string	The generated TypeScript source (when ok: true).
diagnostics	GrammarMetadataDiagnostic[]	List of errors (when ok: false).

Exported types

Type	Purpose	Notes
GrammarMetadata	Grammar metadata descriptor	{ name, version, protocolVersion, kinds, fields? }
GrammarKindDefinition	One grammar node kind	{ name, id, named }
GrammarFieldDefinition	One grammar field	{ name, id }
GrammarMetadataDiagnostic	Validation diagnostic	{ code, path, message }
GrammarMetadataDiagnosticCode	Diagnostic code constants	InvalidName, InvalidVersion, etc.
GrammarMetadataValidationResult	Validation result	Discriminated union
KindModuleEmitResult	Kind module emission result	Discriminated union
EmitKindModuleOptions	Options for emitKindModule	See options table above.

Accessibility

Accessibility requirements

• No direct accessibility surface. This is a build-time code generation tool.

Security

Security considerations

• Input validation returns diagnostics rather than throwing.
• Generated source code includes a standard ADT Studios LLC copyright header.

Threat	Mitigation	Status
Invalid metadata input	Returns { ok: false, diagnostics } instead of throwing	Implemented

Companion packages

Package	Relationship	Layer	Notes
@lanexio/parser-core	Requires	1	Protocol version constant for validation

Changelog

Version	Date	Status	Notable changes
1.0.0	2026-05-29	Current	Initial stable release. Internal build utility.

Migration notes

• This package is a build-time utility. It is never a production dependency.

Related Content

Flat AST How the 16-byte node layout works.

Stability Guarantees Never-throw, panic-free, and 3-token recovery.