@plurnk/plurnk-grammar 0.1.1 → 0.2.1

package/src/AstBuilder.ts

@@ -0,0 +1,372 @@
+import { ParserRuleContext } from "antlr4ng";
+import * as xpath from "xpath";
+import { JSONPath } from "jsonpath-plus";
+import type {
+    CopyStatement,
+    EditStatement,
+    ExecStatement,
+    FindStatement,
+    HideStatement,
+    LineMarker,
+    MatcherBody,
+    MoveStatement,
+    ParsedPath,
+    PlurnkOp,
+    PlurnkStatement,
+    Position,
+    ReadStatement,
+    SendBody,
+    SendStatement,
+    ShowStatement,
+} from "./types.ts";
+import type {
+    CopyStatementContext,
+    EditStatementContext,
+    ExecModifiersContext,
+    ExecStatementContext,
+    FindStatementContext,
+    HideStatementContext,
+    MoveStatementContext,
+    ReadStatementContext,
+    SendModifiersContext,
+    SendStatementContext,
+    ShowStatementContext,
+    StatementContext,
+    TagOpModifiersContext,
+} from "./generated/plurnkParser.ts";
+import {
+    IdentSignalContext,
+    IntSignalContext,
+    LineMarkerContext,
+    PathContext,
+    TagSignalContext,
+} from "./generated/plurnkParser.ts";
+import PlurnkParseError from "./PlurnkParseError.ts";
+
+// The xpath package's .d.ts omits its `parse` function; augment here.
+declare module "xpath" {
+    export function parse(expression: string): unknown;
+}
+
+type Ctor<T> = new (...args: any[]) => T;
+
+type TagSlots = { signal: string[] | null; path: ParsedPath | null; lineMarker: LineMarker | null };
+type SendSlots = { signal: number | null; path: ParsedPath | null };
+type ExecSlots = { signal: string | null; path: ParsedPath | null };
+
+export default class AstBuilder {
+    static #SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+    static build(ctx: StatementContext): PlurnkStatement {
+        const find = ctx.findStatement(); if (find) return AstBuilder.#buildFind(find);
+        const read = ctx.readStatement(); if (read) return AstBuilder.#buildRead(read);
+        const edit = ctx.editStatement(); if (edit) return AstBuilder.#buildEdit(edit);
+        const copy = ctx.copyStatement(); if (copy) return AstBuilder.#buildCopy(copy);
+        const move = ctx.moveStatement(); if (move) return AstBuilder.#buildMove(move);
+        const show = ctx.showStatement(); if (show) return AstBuilder.#buildShow(show);
+        const hide = ctx.hideStatement(); if (hide) return AstBuilder.#buildHide(hide);
+        const send = ctx.sendStatement(); if (send) return AstBuilder.#buildSend(send);
+        const exec = ctx.execStatement(); if (exec) return AstBuilder.#buildExec(exec);
+        throw new Error("statement context has no recognized alternative");
+    }
+
+    static #buildFind(ctx: FindStatementContext): FindStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "FIND",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_FIND().getText(), "FIND"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildRead(ctx: ReadStatementContext): ReadStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "READ",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_READ().getText(), "READ"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildShow(ctx: ShowStatementContext): ShowStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "SHOW",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_SHOW().getText(), "SHOW"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildHide(ctx: HideStatementContext): HideStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "HIDE",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_HIDE().getText(), "HIDE"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parseMatcherBody(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildEdit(ctx: EditStatementContext): EditStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        return {
+            op: "EDIT",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_EDIT().getText(), "EDIT"),
+            ...slots,
+            body: AstBuilder.#bodyTextOf(ctx),
+            position,
+        };
+    }
+
+    static #buildCopy(ctx: CopyStatementContext): CopyStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "COPY",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_COPY().getText(), "COPY"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parsePath(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildMove(ctx: MoveStatementContext): MoveStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractTagSlots(ctx.tagOpModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "MOVE",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_MOVE().getText(), "MOVE"),
+            ...slots,
+            body: raw !== null ? AstBuilder.#parsePath(raw, position) : null,
+            position,
+        };
+    }
+
+    static #buildSend(ctx: SendStatementContext): SendStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractSendSlots(ctx.sendModifiers(), position);
+        const raw = AstBuilder.#bodyTextOf(ctx);
+        return {
+            op: "SEND",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_SEND().getText(), "SEND"),
+            ...slots,
+            lineMarker: null,
+            body: raw !== null ? AstBuilder.#parseSendBody(raw) : null,
+            position,
+        };
+    }
+
+    static #buildExec(ctx: ExecStatementContext): ExecStatement {
+        const position = AstBuilder.#positionOf(ctx);
+        const slots = AstBuilder.#extractExecSlots(ctx.execModifiers(), position);
+        return {
+            op: "EXEC",
+            suffix: AstBuilder.#splitSuffix(ctx.OPEN_EXEC().getText(), "EXEC"),
+            ...slots,
+            lineMarker: null,
+            body: AstBuilder.#bodyTextOf(ctx),
+            position,
+        };
+    }
+
+    static #extractTagSlots(modCtx: TagOpModifiersContext | null, pos: Position): TagSlots {
+        return {
+            signal: AstBuilder.#tagsFromSignal(AstBuilder.#findFirst(modCtx, TagSignalContext)),
+            path: AstBuilder.#pathFromCtx(AstBuilder.#findFirst(modCtx, PathContext), pos),
+            lineMarker: AstBuilder.#lineMarkerFromCtx(AstBuilder.#findFirst(modCtx, LineMarkerContext)),
+        };
+    }
+
+    static #extractSendSlots(modCtx: SendModifiersContext | null, pos: Position): SendSlots {
+        const intCtx = AstBuilder.#findFirst(modCtx, IntSignalContext);
+        const intNode = intCtx?.INT() ?? null;
+        return {
+            signal: intNode !== null ? Number.parseInt(intNode.getText(), 10) : null,
+            path: AstBuilder.#pathFromCtx(AstBuilder.#findFirst(modCtx, PathContext), pos),
+        };
+    }
+
+    static #extractExecSlots(modCtx: ExecModifiersContext | null, pos: Position): ExecSlots {
+        const identCtx = AstBuilder.#findFirst(modCtx, IdentSignalContext);
+        const identNode = identCtx?.IDENT() ?? null;
+        return {
+            signal: identNode !== null ? identNode.getText() : null,
+            path: AstBuilder.#pathFromCtx(AstBuilder.#findFirst(modCtx, PathContext), pos),
+        };
+    }
+
+    static #findFirst<T extends ParserRuleContext>(
+        root: ParserRuleContext | null,
+        type: Ctor<T>,
+    ): T | null {
+        if (root === null) return null;
+        if (root instanceof type) return root;
+        const children = root.children;
+        if (!children) return null;
+        for (const child of children) {
+            if (child instanceof ParserRuleContext) {
+                const found = AstBuilder.#findFirst(child, type);
+                if (found !== null) return found;
+            }
+        }
+        return null;
+    }
+
+    static #tagsFromSignal(ctx: TagSignalContext | null): string[] | null {
+        if (ctx === null) return null;
+        const tags = ctx.TAG();
+        return Array.isArray(tags) ? tags.map((t) => t.getText()) : [];
+    }
+
+    static #pathFromCtx(ctx: PathContext | null, pos: Position): ParsedPath | null {
+        if (ctx === null) return null;
+        const text = ctx.PATH_TEXT()?.getText() ?? "";
+        return AstBuilder.#parsePath(text, pos);
+    }
+
+    static #lineMarkerFromCtx(ctx: LineMarkerContext | null): LineMarker | null {
+        if (ctx === null) return null;
+        const text = ctx.L_MARKER()?.getText() ?? "";
+        return AstBuilder.#parseLineMarker(text);
+    }
+
+    static #positionOf(ctx: { start: { line: number; column: number } | null }): Position {
+        const start = ctx.start;
+        return { line: start?.line ?? 0, column: start?.column ?? 0 };
+    }
+
+    static #bodyTextOf(ctx: { body(): { getText(): string } | null }): string | null {
+        const bodyCtx = ctx.body();
+        return bodyCtx ? bodyCtx.getText() : null;
+    }
+
+    static #splitSuffix(openTagText: string, op: PlurnkOp): string {
+        return openTagText.slice(2 + op.length);
+    }
+
+    static #isDigit(c: string | undefined): boolean {
+        return c !== undefined && c >= "0" && c <= "9";
+    }
+
+    static #parseLineMarker(text: string): LineMarker {
+        const inner = text.slice(1, -1);
+        let i = 0;
+        if (inner[i] === "-") i++;
+        while (AstBuilder.#isDigit(inner[i])) i++;
+        const first = Number.parseInt(inner.slice(0, i), 10);
+        if (i >= inner.length) return { first, last: null };
+        i++;
+        const last = Number.parseInt(inner.slice(i), 10);
+        return { first, last };
+    }
+
+    static #parsePath(raw: string, pos: Position): ParsedPath | null {
+        if (raw.length === 0) return null;
+        if (!AstBuilder.#SCHEME_PATTERN.test(raw)) {
+            return { kind: "local", raw };
+        }
+        let url: URL;
+        try {
+            url = new URL(raw);
+        } catch (e: any) {
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid URI in path: ${e?.message ?? raw}`);
+        }
+        const params: Record<string, string | string[]> = {};
+        for (const [key, value] of url.searchParams) {
+            const existing = params[key];
+            if (existing === undefined) {
+                params[key] = value;
+            } else if (Array.isArray(existing)) {
+                existing.push(value);
+            } else {
+                params[key] = [existing, value];
+            }
+        }
+        return {
+            kind: "url",
+            raw,
+            scheme: url.protocol.replace(/:$/, ""),
+            username: url.username || null,
+            password: url.password || null,
+            hostname: url.hostname || null,
+            port: url.port ? Number.parseInt(url.port, 10) : null,
+            pathname: url.pathname,
+            params,
+            fragment: url.hash ? url.hash.slice(1) : null,
+        };
+    }
+
+    static #detectMatcherDialect(body: string): "xpath" | "regex" | "jsonpath" | "glob" {
+        if (body.startsWith("//")) return "xpath";
+        if (body.startsWith("/")) return "regex";
+        if (body.startsWith("$")) return "jsonpath";
+        return "glob";
+    }
+
+    static #parseRegexLiteral(body: string, pos: Position): { pattern: string; flags: string } {
+        let i = 1;
+        while (i < body.length) {
+            if (body[i] === "\\") { i += 2; continue; }
+            if (body[i] === "/") break;
+            i++;
+        }
+        if (i >= body.length) {
+            throw new PlurnkParseError(pos.line, pos.column, "visitor", "regex body missing closing /");
+        }
+        return { pattern: body.slice(1, i), flags: body.slice(i + 1) };
+    }
+
+    static #parseMatcherBody(body: string, pos: Position): MatcherBody {
+        const dialect = AstBuilder.#detectMatcherDialect(body);
+        if (dialect === "regex") {
+            const { pattern, flags } = AstBuilder.#parseRegexLiteral(body, pos);
+            try {
+                new RegExp(pattern, flags);
+            } catch (e: any) {
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid regex: ${e?.message ?? body}`);
+            }
+            return { dialect: "regex", raw: body, pattern, flags };
+        }
+        if (dialect === "xpath") {
+            try {
+                xpath.parse(body);
+            } catch (e: any) {
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid xpath: ${e?.message ?? body}`);
+            }
+            return { dialect: "xpath", raw: body };
+        }
+        if (dialect === "jsonpath") {
+            try {
+                JSONPath({ path: body, json: {} });
+            } catch (e: any) {
+                throw new PlurnkParseError(pos.line, pos.column, "visitor", `invalid jsonpath: ${e?.message ?? body}`);
+            }
+            return { dialect: "jsonpath", raw: body };
+        }
+        return { dialect: "glob", raw: body };
+    }
+
+    static #parseSendBody(raw: string): SendBody {
+        let json: unknown | null = null;
+        try { json = JSON.parse(raw); } catch { /* best-effort */ }
+        return { raw, json };
+    }
+}

package/src/PlurnkErrorStrategy.ts

@@ -0,0 +1,139 @@
+import {
+    DefaultErrorStrategy,
+    InputMismatchException,
+    NoViableAltException,
+    Token,
+    type Parser,
+    type RecognitionException,
+} from "antlr4ng";
+import { plurnkParser } from "./generated/plurnkParser.ts";
+import { plurnkLexer } from "./generated/plurnkLexer.ts";
+
+export default class PlurnkErrorStrategy extends DefaultErrorStrategy {
+    static #OFFENDING_CHAR_RE = /at: '([^']*)'$/;
+
+    static #LEXER_MODE_CONTEXT: Record<string, string> = {
+        DEFAULT_MODE: "between statements",
+        SLOTS: "in slot region — expected `[signal]`, `(path)`, `<L>`, or `:body:` (any order)",
+        SIGNAL_TAGS: "in tag signal — expected tag, `,`, or `]`",
+        SIGNAL_INT: "in signal — expected integer for SEND, then `]`",
+        SIGNAL_IDENT: "in signal — expected Runtime Tag for EXEC, then `]`",
+        PATH: "in path slot — expected path characters or `)`",
+        BODY: "in body",
+    };
+
+    static #SLOT_BY_TOKEN: Record<number, string> = {
+        [plurnkParser.OPEN_FIND]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_READ]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_EDIT]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_COPY]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_MOVE]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_SHOW]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_HIDE]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_SEND]: "open tag `<<OPsuffix`",
+        [plurnkParser.OPEN_EXEC]: "open tag `<<OPsuffix`",
+        [plurnkParser.LBRACKET]: "`[` (signal slot opener)",
+        [plurnkParser.RBRACKET]: "`]` (signal slot closer)",
+        [plurnkParser.LPAREN]: "`(` (path slot opener)",
+        [plurnkParser.RPAREN]: "`)` (path slot closer)",
+        [plurnkParser.L_MARKER]: "`<L>` line marker",
+        [plurnkParser.COLON]: "`:` (body fence)",
+        [plurnkParser.COMMA]: "`,`",
+        [plurnkParser.INT]: "integer (SEND signal)",
+        [plurnkParser.IDENT]: "Runtime Tag (EXEC signal)",
+        [plurnkParser.TAG]: "tag",
+        [plurnkParser.PATH_TEXT]: "path content",
+        [plurnkParser.BODY_TEXT]: "body content",
+        [plurnkParser.CLOSE_TAG]: "close tag `:OPsuffix`",
+        [plurnkParser.TEXT]: "text between statements",
+    };
+
+    static translateLexerMessage(lexer: plurnkLexer, originalMsg: string): string {
+        const modeName = lexer.modeNames[lexer.mode] ?? "DEFAULT_MODE";
+        const context = PlurnkErrorStrategy.#LEXER_MODE_CONTEXT[modeName] ?? "between statements";
+        const ch = PlurnkErrorStrategy.#extractOffendingChar(originalMsg);
+        return `unrecognized character ${ch} ${context}`;
+    }
+
+    static #extractOffendingChar(msg: string): string {
+        const m = PlurnkErrorStrategy.#OFFENDING_CHAR_RE.exec(msg);
+        if (!m) return "input";
+        const text = m[1];
+        return text === "" ? "end of input" : `'${text}'`;
+    }
+
+    static #describeToken(tok: Token | null): string {
+        if (!tok || tok.type === Token.EOF) return "end of input";
+        const slot = PlurnkErrorStrategy.#SLOT_BY_TOKEN[tok.type];
+        if (slot) return slot;
+        const text = tok.text ?? "";
+        return text.length > 0 ? `'${text}'` : "input";
+    }
+
+    static #describeExpected(e: RecognitionException): string | null {
+        const expected = e.getExpectedTokens();
+        if (!expected) return null;
+        const types: number[] = expected.toArray();
+        if (types.length === 0) return null;
+        const names = types
+            .map((t) => PlurnkErrorStrategy.#SLOT_BY_TOKEN[t])
+            .filter((s): s is string => Boolean(s));
+        if (names.length === 0) return null;
+        if (names.length === 1) return names[0];
+        if (names.length === 2) return `${names[0]} or ${names[1]}`;
+        return `${names.slice(0, -1).join(", ")}, or ${names[names.length - 1]}`;
+    }
+
+    public override reportError(recognizer: Parser, e: RecognitionException): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+
+        const got = PlurnkErrorStrategy.#describeToken(e.offendingToken);
+        const expected = PlurnkErrorStrategy.#describeExpected(e);
+
+        let msg: string;
+        if (e instanceof InputMismatchException || e instanceof NoViableAltException) {
+            msg = expected ? `unexpected ${got}; expected ${expected}` : `unexpected ${got}`;
+        } else {
+            msg = `unexpected ${got}`;
+        }
+
+        recognizer.notifyErrorListeners(msg, e.offendingToken, e);
+    }
+
+    public override reportMissingToken(recognizer: Parser): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+        const tok = recognizer.getCurrentToken();
+        const expectedTokens = this.getExpectedTokens(recognizer);
+        const expectedNames = expectedTokens
+            .toArray()
+            .map((t) => PlurnkErrorStrategy.#SLOT_BY_TOKEN[t])
+            .filter((s): s is string => Boolean(s));
+        const expected = expectedNames.length > 0
+            ? (expectedNames.length === 1 ? expectedNames[0] : expectedNames.join(" or "))
+            : "more input";
+        const got = PlurnkErrorStrategy.#describeToken(tok);
+        const msg = `expected ${expected}; got ${got}`;
+        recognizer.notifyErrorListeners(msg, tok, null);
+    }
+
+    public override reportUnwantedToken(recognizer: Parser): void {
+        if (this.inErrorRecoveryMode(recognizer)) return;
+        this.beginErrorCondition(recognizer);
+        const tok = recognizer.getCurrentToken();
+        const got = PlurnkErrorStrategy.#describeToken(tok);
+        const expectedTokens = this.getExpectedTokens(recognizer);
+        const expectedNames = expectedTokens
+            .toArray()
+            .map((t) => PlurnkErrorStrategy.#SLOT_BY_TOKEN[t])
+            .filter((s): s is string => Boolean(s));
+        const expected = expectedNames.length > 0
+            ? (expectedNames.length === 1 ? expectedNames[0] : expectedNames.join(" or "))
+            : null;
+        const msg = expected
+            ? `unexpected ${got}; expected ${expected}`
+            : `unexpected ${got}`;
+        recognizer.notifyErrorListeners(msg, tok, null);
+    }
+}

package/src/{errors.ts → PlurnkParseError.ts}

@@ -1,6 +1,6 @@
 export type ErrorSource = "lexer" | "parser" | "visitor";
 
-export class PlurnkParseError extends Error {
+export default class PlurnkParseError extends Error {
     readonly line: number;
     readonly column: number;
     readonly source: ErrorSource;
@@ -13,7 +13,6 @@ export class PlurnkParseError extends Error {
         this.source = source;
     }
 
-    /** JSON serialization — `JSON.stringify` picks this up automatically. */
     toJSON(): { line: number; column: number; source: ErrorSource; message: string } {
         return {
             line: this.line,

package/src/PlurnkParser.ts

@@ -0,0 +1,92 @@
+import { CharStream, CommonTokenStream } from "antlr4ng";
+import { plurnkLexer } from "./generated/plurnkLexer.ts";
+import { plurnkParser } from "./generated/plurnkParser.ts";
+import AstBuilder from "./AstBuilder.ts";
+import PlurnkParseError from "./PlurnkParseError.ts";
+import PlurnkErrorStrategy from "./PlurnkErrorStrategy.ts";
+import RecordingListener from "./RecordingListener.ts";
+import type { ParseItem, ParseResult, Position } from "./types.ts";
+
+export default class PlurnkParser {
+    static parse(input: string): ParseResult {
+        const lexer = new plurnkLexer(CharStream.fromString(input));
+        const errors: PlurnkParseError[] = [];
+        lexer.removeErrorListeners();
+        lexer.addErrorListener(new RecordingListener("lexer", errors));
+
+        const tokenStream = new CommonTokenStream(lexer);
+        const parser = new plurnkParser(tokenStream);
+        parser.removeErrorListeners();
+        parser.addErrorListener(new RecordingListener("parser", errors));
+        parser.errorHandler = new PlurnkErrorStrategy();
+
+        const tree = parser.document();
+
+        const items: ParseItem[] = [];
+        const consumedErrors = new Set<PlurnkParseError>();
+
+        for (const child of tree.children ?? []) {
+            const ctx = child as any;
+            const start = ctx.start ?? ctx.symbol;
+            const stop = ctx.stop ?? ctx.symbol;
+            if (!start) continue;
+
+            if (ctx.ruleIndex === plurnkParser.RULE_statement) {
+                const errForStatement = errors.find(
+                    (e) => !consumedErrors.has(e) && PlurnkParser.#errorInRange(e, start, stop ?? start),
+                );
+                if (errForStatement) {
+                    consumedErrors.add(errForStatement);
+                    items.push({ kind: "error", error: errForStatement });
+                } else {
+                    try {
+                        items.push({ kind: "statement", statement: AstBuilder.build(ctx) });
+                    } catch (e) {
+                        if (e instanceof PlurnkParseError) {
+                            items.push({ kind: "error", error: e });
+                        } else {
+                            throw e;
+                        }
+                    }
+                }
+            } else if (ctx.symbol?.type === plurnkLexer.TEXT) {
+                const position: Position = { line: start.line, column: start.column };
+                items.push({ kind: "text", text: ctx.symbol.text ?? "", position });
+            }
+        }
+
+        for (const err of errors) {
+            if (!consumedErrors.has(err)) {
+                items.push({ kind: "error", error: err });
+            }
+        }
+
+        let unparsedTail: ParseResult["unparsedTail"];
+        if (lexer.mode !== 0) {
+            const openTag = lexer.getOpenTag();
+            const from = { line: lexer.getOpenTagLine(), column: lexer.getOpenTagColumn() };
+            const modeName = lexer.modeNames[lexer.mode] ?? "";
+            const reason = modeName === "BODY"
+                ? `body of \`<<${openTag}\` opened at line ${from.line} but never closed — add \`:${openTag}\` to terminate`
+                : modeName === "SIGNAL_TAGS" || modeName === "SIGNAL_INT" || modeName === "SIGNAL_IDENT"
+                    ? `signal slot of \`<<${openTag}\` opened at line ${from.line} but never closed — add \`]\` to terminate the signal`
+                    : modeName === "PATH"
+                        ? `path slot of \`<<${openTag}\` opened at line ${from.line} but never closed — add \`)\` to terminate the path`
+                        : `statement \`<<${openTag}\` opened at line ${from.line} but never reached its close tag — add \`:${openTag}\` to terminate`;
+            unparsedTail = { from, reason };
+        }
+
+        return { items, unparsedTail };
+    }
+
+    static #errorInRange(
+        err: PlurnkParseError,
+        start: { line: number; column: number },
+        stop: { line: number; column: number },
+    ): boolean {
+        if (err.line < start.line || err.line > stop.line) return false;
+        if (err.line === start.line && err.column < start.column) return false;
+        if (err.line === stop.line && err.column > stop.column) return false;
+        return true;
+    }
+}

package/src/RecordingListener.ts

@@ -0,0 +1,34 @@
+import {
+    BaseErrorListener,
+    type RecognitionException,
+    type Recognizer,
+    type Token,
+} from "antlr4ng";
+import { plurnkLexer } from "./generated/plurnkLexer.ts";
+import PlurnkParseError from "./PlurnkParseError.ts";
+import PlurnkErrorStrategy from "./PlurnkErrorStrategy.ts";
+
+export default class RecordingListener extends BaseErrorListener {
+    readonly errors: PlurnkParseError[];
+    readonly source: "lexer" | "parser";
+
+    constructor(source: "lexer" | "parser", errors: PlurnkParseError[]) {
+        super();
+        this.source = source;
+        this.errors = errors;
+    }
+
+    override syntaxError(
+        recognizer: Recognizer<any>,
+        _offendingSymbol: Token | null,
+        line: number,
+        column: number,
+        msg: string,
+        _e: RecognitionException | null,
+    ): void {
+        const translated = this.source === "lexer"
+            ? PlurnkErrorStrategy.translateLexerMessage(recognizer as plurnkLexer, msg)
+            : msg;
+        this.errors.push(new PlurnkParseError(line, column, this.source, translated));
+    }
+}