@plurnk/plurnk-parser 1.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PossumTech Laboratories, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @plurnk/plurnk-parser
+
+The parser for the PLURNK model language: the ANTLR grammars, the generated
+lexer and parser, the AST builder, and path decomposition. It implements the
+language that [`@plurnk/plurnk-contracts`](../plurnk-contracts) specifies and
+teaches; the AST and wire types it produces are the contracts package's.
+
+## Install
+
+```sh
+npm install @plurnk/plurnk-parser
+```
+
+The service's execution path is the consumer. A client that validates or
+presents the wire needs only `@plurnk/plurnk-contracts`, which carries no parser
+runtime.
+
+## Parser
+
+```ts
+import { PlurnkParser } from "@plurnk/plurnk-parser";
+
+const result = PlurnkParser.parse(input);
+
+for (const item of result.items) {
+    if (item.kind === "statement") {
+        console.log(item.statement.op);
+    }
+}
+```
+
+Parse items are ordered and discriminate as `statement` or `error`.
+Outside-block text is ignored in every tier; literal bodies remain exact.
+The parser entry points deliberately accept different document tiers:
+
+| Entry point                    | Accepted input                                        |
+|--------------------------------|-------------------------------------------------------|
+| `PlurnkParser.parse`           | One operation-bearing model turn; omitted TASK continues silently |
+| `PlurnkParser.parseStatements` | A sequence of protocol statements                     |
+| `PlurnkParser.parseLog`        | Consecutive disposition-ended turns                    |
+| `PlurnkParser.parseClient`     | Protocol statements plus the client-only LOOK         |
+| `parsePath`                    | One path or URI using parser-equivalent decomposition |
+
+See the contracts SPEC {§turn-shape} and {§tier-entrypoints} for the tier
+boundaries. The AST, parse-result, and wire types come from
+`@plurnk/plurnk-contracts`.
+
+## CLI
+
+```text
+plurnk-parser [file]    parse a file, or standard input when omitted
+plurnk-parser --help    show usage
+```
+
+The CLI prints the parse result as JSON and exits `0` for a clean parse or `1`
+when the result contains an error or unparsed tail.
+
+## Development
+
+```sh
+npm run build
+npm test
+npm run test:installation
+```
+
+`npm run build:grammar` regenerates the parser from `plurnkLexer.g4` and
+`plurnkParser.g4`. Change the grammar rather than editing generated output.
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,35 @@
+# @plurnk/plurnk-parser — SPEC
+
+## §parser-package 1. What this package is
+
+`@plurnk/plurnk-parser` implements the PLURNK language that
+`@plurnk/plurnk-contracts` specifies. It owns the ANTLR grammars
+(`plurnkLexer.g4`, `plurnkParser.g4`), the generated lexer, parser and visitor,
+`AstBuilder`, the error strategy and the recording listener, the `PlurnkParser`
+tier entry points, `parsePath`, and the `plurnk-parser` command line. It depends
+on contracts for the AST and wire types, the schemas, `PathSyntax`,
+`PlurnkParseError`, `PlanValue`, `TurnDisposition`, and the constants. Contracts
+depends on nothing here.
+
+§parser-boundary **The contract lives in contracts; the implementation lives here.**
+Accepted syntax, document tiers, recovery, whitespace, framing, and diagnostics
+are specified by `plurnk-contracts/SPEC.md` ({§contract-layers},
+{§path-syntax}, {§parser-architecture}, {§turn-shape}, {§tier-entrypoints}) and
+taught by `plurnk-contracts/plurnk.md`. This package's tests are the evidence for
+those anchors and cite them. Nothing that only validates, presents, or transports
+the wire needs this package.
+
+§parser-consumers **Who imports the parser.** The service's execution path (core,
+agui, execs) imports `PlurnkParser` and `parsePath` from this package.
+`@plurnk/plurnk-contracts` exports neither and declares no parser dependency, so a
+client that installs contracts installs no `antlr4ng`, `xpath`, or `json-p3`.
+
+## §parser-build 2. Build and artifacts
+
+`npm run build:grammar` regenerates `src/generated` from the grammars with
+antlr-ng; generated files are artifacts, never edited, and are not tracked.
+`npm run build` emits `dist`. `npm run test:installation` packs the built parser
+and contracts candidates, installs both into a clean consumer, verifies their
+installed versions, and exercises every tier entry point, `parsePath`, the CLI,
+and a browser-Worker bundle. Prepublication checks must not resolve the candidate
+contracts version from the registry.

package/bin/plurnk-parser.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { PlurnkParser } from "../dist/index.js";
+
+const USAGE = `Usage:
+  plurnk-parser [file]      Parse plurnk source from a file (or stdin if omitted or '-')
+                     and print the result as JSON.
+  plurnk-parser --help      Show this message.
+
+Exit codes:
+  0   parse succeeded with no errors and no unparsed tail
+  1   parse produced one or more errors, or left an unparsed tail`;
+
+const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+});
+
+if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    process.exit(0);
+}
+
+const target = positionals[0];
+const input = !target || target === "-"
+    ? readFileSync(0, "utf8")
+    : readFileSync(target, "utf8");
+
+const result = PlurnkParser.parse(input);
+
+const serialized = JSON.stringify(
+    result,
+    (_key, value) => (value instanceof RegExp ? value.toString() : value),
+    2,
+);
+process.stdout.write(`${serialized}\n`);
+
+const hasIssues = result.items.some((i) => i.kind === "error") || result.unparsedTail !== undefined;
+process.exit(hasIssues ? 1 : 0);

package/dist/AstBuilder.d.ts

@@ -0,0 +1,21 @@
+import type { ClientStatement, ParsedPath, PlurnkStatement, Position } from "@plurnk/plurnk-contracts";
+import type { ClientStatementContext, StatementContext, MidStatementContext } from "./generated/plurnkParser.ts";
+import { DispositionStatementContext, SendStatementContext } from "./generated/plurnkParser.ts";
+import { PlurnkParseError } from "@plurnk/plurnk-contracts";
+declare module "xpath" {
+    function parse(expression: string): unknown;
+}
+export default class AstBuilder {
+    #private;
+    static takeAdvisories(): PlurnkParseError[];
+    static build(ctx: StatementContext | MidStatementContext | DispositionStatementContext | SendStatementContext): PlurnkStatement;
+    static buildClient(ctx: ClientStatementContext): ClientStatement;
+    static executorSpellings: ReadonlyMap<string, string>;
+    /**
+     * Apply target-slot decomposition without round-tripping through a statement.
+     * Returns null for empty input and throws PlurnkParseError when a scheme URL
+     * fails WHATWG admission. {§path-syntax}
+     */
+    static parsePath(raw: string, pos?: Position): ParsedPath | null;
+}
+//# sourceMappingURL=AstBuilder.d.ts.map

package/dist/AstBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AstBuilder.d.ts","sourceRoot":"","sources":["../src/AstBuilder.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAER,eAAe,EAcf,UAAU,EACV,eAAe,EACf,QAAQ,EAOX,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAER,sBAAsB,EActB,gBAAgB,EAChB,mBAAmB,EACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAIH,2BAA2B,EAC3B,oBAAoB,EAGvB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAyB,gBAAgB,EAAmB,MAAM,0BAA0B,CAAC;AAGpG,OAAO,QAAQ,OAAO,CAAC;IACnB,SAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACtD;AAQD,MAAM,CAAC,OAAO,OAAO,UAAU;;IAK3B,MAAM,CAAC,cAAc,IAAI,gBAAgB,EAAE,CAI1C;IAwJD,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,GAAG,2BAA2B,GAAG,oBAAoB,GAAG,eAAe,CAmB9H;IA8BD,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,sBAAsB,GAAG,eAAe,CAI/D;IA4ID,MAAM,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAa;IA+RlE;;;;OAIG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,QAAiC,GAAG,UAAU,GAAG,IAAI,CAmCvF;CAiLJ"}