FS FormScript
Package@formscript/spec-lint
Specification1, 3.5, 4.14, 14, 20
Depends onnothing — it is a leaf

@formscript/spec-lint

A static consistency checker for the FormScript specification itself, per §1–§20.

The specification is the contract for everything else in this repository, so it is checked mechanically rather than by eye.

Usage

bash
npm run verify:spec

The checker parses the specification into sections, numbered statements, error codes, grammar productions and keyword lists, and then checks:

Rule Checks
duplicate-statement a Spec-N.N defined twice
unresolved-statement-reference a Spec-N.N cited but never defined
statement-sequence statement numbers not dense and ascending within a chapter
unresolved-section-reference a §N.N cited but never defined
section-order subsection headings not ascending within a chapter
duplicate-error-code, unresolved-error-code §14 catalogue drift
unused-error-code a catalogue entry the prose never cites (informational)
keyword-list-mismatch §3.5 and §20 disagreeing about a keyword
soft-keyword-unresolved a soft keyword with no row in the §4.14 table
grammar-unreachable-production a production not reachable from document
grammar-unknown-nonterminal a production naming an undefined non-terminal

It found 67 errors and 58 warnings in draft r5. Every one was a real defect.

Why it is a package

The checker found three defects in itself during the first cycle — a greedy terminal stripper, a definition regex that missed (G4)-style qualifiers, and an over-strict keyword check. A tool that checks the specification needs its own tests, or it is just a different source of opinions.

Renumbering

scripts/renumber.ts reassigns statement numbers densely per chapter and rewrites every cross-reference mechanically, including the ones in prose. It is idempotent once the numbering is dense.

Public API

12 exported symbols.

Finding interface
FindingSeverity type
GrammarProduction interface
LintReport interface
lintSpec function
parseSpec re-export
SpecErrorCode interface
SpecModel interface
SpecSection interface
SpecStatement interface

Parses the FormScript specification markdown into a structural model. Line-oriented; the spec's markdown is regular enough that a full AST is unnecessary.

stripProse function

Removes EBNF inline comments and `? prose ?` annotations.

stripTerminals function

Removes EBNF terminals (double-quoted literals) from a production body. A scanner is required: a regex cannot distinguish `"\""` (an escaped quote inside a t…