@stackables/bridge-compiler 0.0.1 → 1.0.1

package/README.md

@@ -0,0 +1,49 @@
+[![github](https://img.shields.io/badge/github-stackables/bridge-blue?logo=github)](https://github.com/stackables/bridge)
+
+# The Bridge Compiler
+
+The parser for [The Bridge](https://github.com/stackables/bridge) — turns `.bridge` source files into executable instructions.
+
+## Installing
+
+```bash
+npm install @stackables/bridge-compiler
+```
+
+## Parsing a Bridge File
+
+The most common thing you'll do — read a `.bridge` file and get instructions the engine can run:
+
+```ts
+import { parseBridge } from "@stackables/bridge-compiler";
+import { readFileSync } from "node:fs";
+
+const source = readFileSync("logic.bridge", "utf8");
+const instructions = parseBridge(source);
+
+// → Instruction[] — feed this to executeBridge() or bridgeTransform()
+```
+
+## Serializing Back to `.bridge`
+
+Round-trip support — parse a bridge file, then serialize the AST back into clean `.bridge` text:
+
+```ts
+import {
+  parseBridgeFormat,
+  serializeBridge,
+} from "@stackables/bridge-compiler";
+
+const ast = parseBridgeFormat(source);
+const formatted = serializeBridge(ast);
+```
+
+## Part of the Bridge Ecosystem
+
+| Package                                                                                  | What it does                                                   |
+| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| [`@stackables/bridge`](https://www.npmjs.com/package/@stackables/bridge)                 | **The All-in-One** — everything in a single install            |
+| [`@stackables/bridge-core`](https://www.npmjs.com/package/@stackables/bridge-core)       | **The Engine** — runs the instructions this package produces   |
+| [`@stackables/bridge-graphql`](https://www.npmjs.com/package/@stackables/bridge-graphql) | **The Adapter** — wires bridges into a GraphQL schema          |
+| [`@stackables/bridge-stdlib`](https://www.npmjs.com/package/@stackables/bridge-stdlib)   | **The Standard Library** — httpCall, strings, arrays, and more |
+| [`@stackables/bridge-types`](https://www.npmjs.com/package/@stackables/bridge-types)     | **Shared Types** — `ToolCallFn`, `ToolMap`, `CacheStore`       |

package/build/bridge-compiler/src/bridge-format.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeDocument } from "@stackables/bridge-core";
+export { parsePath } from "@stackables/bridge-core";
+/**
+ * Parse .bridge text — delegates to the Chevrotain parser.
+ */
+export declare function parseBridge(text: string): BridgeDocument;
+export declare function serializeBridge(doc: BridgeDocument): string;
+//# sourceMappingURL=bridge-format.d.ts.map

package/build/bridge-compiler/src/bridge-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-format.d.ts","sourceRoot":"","sources":["../../../src/bridge-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,cAAc,EAOf,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAExD;AAcD,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAkC3D"}

package/build/{bridge-format.js → bridge-compiler/src/bridge-format.js}

@@ -19,7 +19,9 @@ function serializeControl(ctrl) {
     return "break";
 }
 // ── Serializer ───────────────────────────────────────────────────────────────
-export function serializeBridge(instructions) {
+export function serializeBridge(doc) {
+    const version = doc.version ?? BRIDGE_VERSION;
+    const { instructions } = doc;
     const bridges = instructions.filter((i) => i.kind === "bridge");
     const tools = instructions.filter((i) => i.kind === "tool");
     const consts = instructions.filter((i) => i.kind === "const");
@@ -43,7 +45,7 @@ export function serializeBridge(instructions) {
     for (const bridge of bridges) {
         blocks.push(serializeBridgeBlock(bridge));
     }
-    return `version ${BRIDGE_VERSION}\n\n` + blocks.join("\n\n") + "\n";
+    return `version ${version}\n\n` + blocks.join("\n\n") + "\n";
 }
 /**
  * Whether a value string needs quoting to be re-parseable as a bare value.
@@ -100,7 +102,8 @@ function serializeToolBlock(tool) {
             }
         }
         else {
-            lines.push(`  with ${dep.tool} as ${dep.handle}`);
+            const depVTag = dep.version ? `@${dep.version}` : "";
+            lines.push(`  with ${dep.tool}${depVTag} as ${dep.handle}`);
         }
     }
     // Wires
@@ -210,11 +213,12 @@ function serializeBridgeBlock(bridge) {
                 // Short form `with <name>` when handle == last segment of name
                 const lastDot = h.name.lastIndexOf(".");
                 const defaultHandle = lastDot !== -1 ? h.name.substring(lastDot + 1) : h.name;
-                if (h.handle === defaultHandle) {
+                const vTag = h.version ? `@${h.version}` : "";
+                if (h.handle === defaultHandle && !vTag) {
                     lines.push(`  with ${h.name}`);
                 }
                 else {
-                    lines.push(`  with ${h.name} as ${h.handle}`);
+                    lines.push(`  with ${h.name}${vTag} as ${h.handle}`);
                 }
                 break;
             }

package/build/{bridge-lint.d.ts.map → bridge-compiler/src/bridge-lint.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"bridge-lint.d.ts","sourceRoot":"","sources":["../src/bridge-lint.ts"],"names":[],"mappings":""}
+{"version":3,"file":"bridge-lint.d.ts","sourceRoot":"","sources":["../../../src/bridge-lint.ts"],"names":[],"mappings":""}

package/build/{index.d.ts → bridge-compiler/src/index.d.ts}

@@ -1,13 +1,13 @@
 /**
  * @stackables/bridge-compiler — Bridge DSL parser, serializer, and language service.
  *
- * Turns `.bridge` source text into `Instruction[]` (JSON AST) and provides
+ * Turns `.bridge` source text into `BridgeDocument` (JSON AST) and provides
  * IDE intelligence (diagnostics, completions, hover).
  */
-export { parseBridgeChevrotain as parseBridge, parseBridgeChevrotain, parseBridgeDiagnostics, } from "./parser/index.ts";
+export { parseBridgeChevrotain as parseBridge, parseBridgeChevrotain, parseBridgeDiagnostics, PARSER_VERSION, } from "./parser/index.ts";
 export type { BridgeDiagnostic, BridgeParseResult } from "./parser/index.ts";
 export { BridgeLexer, allTokens } from "./parser/index.ts";
-export { parseBridge as parseBridgeFormat, serializeBridge } from "./bridge-format.ts";
+export { parseBridge as parseBridgeFormat, serializeBridge, } from "./bridge-format.ts";
 export { BridgeLanguageService } from "./language-service.ts";
 export type { BridgeCompletion, BridgeHover, CompletionKind, Position, Range, } from "./language-service.ts";
 //# sourceMappingURL=index.d.ts.map

package/build/bridge-compiler/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,qBAAqB,IAAI,WAAW,EACpC,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAI3D,OAAO,EACL,WAAW,IAAI,iBAAiB,EAChC,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,KAAK,GACN,MAAM,uBAAuB,CAAC"}

package/build/{index.js → bridge-compiler/src/index.js}

@@ -1,13 +1,13 @@
 /**
  * @stackables/bridge-compiler — Bridge DSL parser, serializer, and language service.
  *
- * Turns `.bridge` source text into `Instruction[]` (JSON AST) and provides
+ * Turns `.bridge` source text into `BridgeDocument` (JSON AST) and provides
  * IDE intelligence (diagnostics, completions, hover).
  */
 // ── Parser ──────────────────────────────────────────────────────────────────
-export { parseBridgeChevrotain as parseBridge, parseBridgeChevrotain, parseBridgeDiagnostics, } from "./parser/index.js";
+export { parseBridgeChevrotain as parseBridge, parseBridgeChevrotain, parseBridgeDiagnostics, PARSER_VERSION, } from "./parser/index.js";
 export { BridgeLexer, allTokens } from "./parser/index.js";
 // ── Serializer ──────────────────────────────────────────────────────────────
-export { parseBridge as parseBridgeFormat, serializeBridge } from "./bridge-format.js";
+export { parseBridge as parseBridgeFormat, serializeBridge, } from "./bridge-format.js";
 // ── Language service ────────────────────────────────────────────────────────
 export { BridgeLanguageService } from "./language-service.js";

package/build/bridge-compiler/src/language-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-service.d.ts","sourceRoot":"","sources":["../../../src/language-service.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAW1D,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,KAAK,GAAG;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,CAAC;AAoCF,qBAAa,qBAAqB;IAChC,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,iBAAiB,CAA0B;IAEnD;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAmB1B;;;;OAIG;IACH,cAAc,IAAI,gBAAgB,EAAE;IAmEpC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,gBAAgB,EAAE;IA4CjD;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI;CAqE5C"}

package/build/{language-service.js → bridge-compiler/src/language-service.js}

@@ -13,7 +13,8 @@
  *   svc.getHover({ line, character });
  */
 import { parseBridgeDiagnostics } from "./parser/index.js";
-import { std } from "@stackables/bridge-stdlib";
+import { collectVersionedHandles } from "@stackables/bridge-core";
+import { std, STD_VERSION } from "@stackables/bridge-stdlib";
 // ── Internal lookup tables (built once at module load) ─────────────────────
 const builtinToolNames = [
     ...Object.keys(std).map((k) => `std.${k}`),
@@ -63,7 +64,7 @@ export class BridgeLanguageService {
             return;
         }
         const result = parseBridgeDiagnostics(text);
-        this.instructions = result.instructions;
+        this.instructions = result.document.instructions;
         this.startLines = result.startLines;
         this.parserDiagnostics = result.diagnostics;
     }
@@ -98,6 +99,42 @@ export class BridgeLanguageService {
                 }
             }
         }
+        // Check @version tags on tool handles against the bundled std version.
+        // Versions exceeding the bundled std emit a warning: the tool must be
+        // provided at runtime via the tools map.
+        const versioned = collectVersionedHandles(this.instructions);
+        if (versioned.length > 0) {
+            const stdParts = STD_VERSION.split(".").map(Number);
+            const [stdMajor = 0, stdMinor = 0] = stdParts;
+            for (const { name, version } of versioned) {
+                if (!name.startsWith("std."))
+                    continue;
+                const vParts = version.split(".").map(Number);
+                const [vMajor = 0, vMinor = 0] = vParts;
+                if (vMajor === stdMajor && stdMinor >= vMinor)
+                    continue;
+                // Find the line that contains this version tag so we can report it
+                const versionTag = `@${version}`;
+                for (let i = 0; i < this.lines.length; i++) {
+                    const col = this.lines[i].indexOf(versionTag);
+                    if (col === -1)
+                        continue;
+                    // Make sure it's adjacent to the tool name
+                    if (!this.lines[i].includes(name + versionTag))
+                        continue;
+                    diags.push({
+                        message: `"${name}@${version}" exceeds bundled std ${STD_VERSION}. ` +
+                            `Provide this tool version at runtime via the tools map.`,
+                        severity: "warning",
+                        range: {
+                            start: { line: i, character: col },
+                            end: { line: i, character: col + versionTag.length },
+                        },
+                    });
+                    break;
+                }
+            }
+        }
         return diags;
     }
     // ── Completions ────────────────────────────────────────────────────────
@@ -217,8 +254,10 @@ function getWordAt(line, character) {
 }
 function handleBindingMarkdown(h) {
     switch (h.kind) {
-        case "tool":
-            return `**Tool handle** \`${h.handle}\`\n\nSource: \`${h.name}\``;
+        case "tool": {
+            const ver = h.version ? ` @${h.version}` : "";
+            return `**Tool handle** \`${h.handle}\`\n\nSource: \`${h.name}${ver}\``;
+        }
         case "input":
             return `**Input handle** \`${h.handle}\`\n\nGraphQL field arguments`;
         case "output":
@@ -237,7 +276,9 @@ function toolDepMarkdown(d) {
             return `**Context dep** \`${d.handle}\`\n\nGraphQL execution context`;
         case "const":
             return `**Const dep** \`${d.handle}\`\n\nNamed constants declared in this file`;
-        case "tool":
-            return `**Tool dep** \`${d.handle}\`\n\nTool: \`${d.tool}\``;
+        case "tool": {
+            const ver = d.version ? ` @${d.version}` : "";
+            return `**Tool dep** \`${d.handle}\`\n\nTool: \`${d.tool}${ver}\``;
+        }
     }
 }

package/build/{parser → bridge-compiler/src/parser}/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Re-exports the public parse function as well as the lexer for direct access.
  */
-export { parseBridgeChevrotain, parseBridgeDiagnostics } from "./parser.ts";
+export { parseBridgeChevrotain, parseBridgeDiagnostics, PARSER_VERSION, } from "./parser.ts";
 export type { BridgeDiagnostic, BridgeParseResult } from "./parser.ts";
 export { BridgeLexer, allTokens } from "./lexer.ts";
 //# sourceMappingURL=index.d.ts.map

package/build/bridge-compiler/src/parser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/parser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/build/{parser → bridge-compiler/src/parser}/index.js

@@ -3,5 +3,5 @@
  *
  * Re-exports the public parse function as well as the lexer for direct access.
  */
-export { parseBridgeChevrotain, parseBridgeDiagnostics } from "./parser.js";
+export { parseBridgeChevrotain, parseBridgeDiagnostics, PARSER_VERSION, } from "./parser.js";
 export { BridgeLexer, allTokens } from "./lexer.js";

package/build/{parser → bridge-compiler/src/parser}/lexer.d.ts

@@ -55,6 +55,7 @@ export declare const Equals: import("chevrotain").TokenType;
 export declare const Dot: import("chevrotain").TokenType;
 export declare const Colon: import("chevrotain").TokenType;
 export declare const Comma: import("chevrotain").TokenType;
+export declare const VersionTag: import("chevrotain").TokenType;
 export declare const StringLiteral: import("chevrotain").TokenType;
 export declare const NumberLiteral: import("chevrotain").TokenType;
 export declare const TrueLiteral: import("chevrotain").TokenType;

package/build/bridge-compiler/src/parser/lexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexer.d.ts","sourceRoot":"","sources":["../../../../src/parser/lexer.ts"],"names":[],"mappings":"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"}

package/build/{parser → bridge-compiler/src/parser}/lexer.js

@@ -27,38 +27,145 @@ export const Identifier = createToken({
     pattern: /[a-zA-Z_][\w-]*/,
 });
 // ── Keywords ───────────────────────────────────────────────────────────────
-export const VersionKw = createToken({ name: "VersionKw", pattern: /version/i, longer_alt: Identifier });
-export const ToolKw = createToken({ name: "ToolKw", pattern: /tool/i, longer_alt: Identifier });
-export const BridgeKw = createToken({ name: "BridgeKw", pattern: /bridge/i, longer_alt: Identifier });
-export const DefineKw = createToken({ name: "DefineKw", pattern: /define/i, longer_alt: Identifier });
-export const ConstKw = createToken({ name: "ConstKw", pattern: /const/i, longer_alt: Identifier });
-export const WithKw = createToken({ name: "WithKw", pattern: /with/i, longer_alt: Identifier });
-export const AsKw = createToken({ name: "AsKw", pattern: /as/i, longer_alt: Identifier });
-export const FromKw = createToken({ name: "FromKw", pattern: /from/i, longer_alt: Identifier });
-export const InputKw = createToken({ name: "InputKw", pattern: /input/i, longer_alt: Identifier });
-export const OutputKw = createToken({ name: "OutputKw", pattern: /output/i, longer_alt: Identifier });
-export const ContextKw = createToken({ name: "ContextKw", pattern: /context/i, longer_alt: Identifier });
-export const OnKw = createToken({ name: "OnKw", pattern: /on/i, longer_alt: Identifier });
-export const ErrorKw = createToken({ name: "ErrorKw", pattern: /error/i, longer_alt: Identifier });
-export const ForceKw = createToken({ name: "ForceKw", pattern: /force/i, longer_alt: Identifier });
-export const AliasKw = createToken({ name: "AliasKw", pattern: /alias/i, longer_alt: Identifier });
-export const CatchKw = createToken({ name: "CatchKw", pattern: /catch/i, longer_alt: Identifier });
-export const AndKw = createToken({ name: "AndKw", pattern: /and/, longer_alt: Identifier });
-export const OrKw = createToken({ name: "OrKw", pattern: /or/, longer_alt: Identifier });
-export const NotKw = createToken({ name: "NotKw", pattern: /not/, longer_alt: Identifier });
-export const ThrowKw = createToken({ name: "ThrowKw", pattern: /throw/, longer_alt: Identifier });
-export const PanicKw = createToken({ name: "PanicKw", pattern: /panic/, longer_alt: Identifier });
-export const ContinueKw = createToken({ name: "ContinueKw", pattern: /continue/, longer_alt: Identifier });
-export const BreakKw = createToken({ name: "BreakKw", pattern: /break/, longer_alt: Identifier });
+export const VersionKw = createToken({
+    name: "VersionKw",
+    pattern: /version/i,
+    longer_alt: Identifier,
+});
+export const ToolKw = createToken({
+    name: "ToolKw",
+    pattern: /tool/i,
+    longer_alt: Identifier,
+});
+export const BridgeKw = createToken({
+    name: "BridgeKw",
+    pattern: /bridge/i,
+    longer_alt: Identifier,
+});
+export const DefineKw = createToken({
+    name: "DefineKw",
+    pattern: /define/i,
+    longer_alt: Identifier,
+});
+export const ConstKw = createToken({
+    name: "ConstKw",
+    pattern: /const/i,
+    longer_alt: Identifier,
+});
+export const WithKw = createToken({
+    name: "WithKw",
+    pattern: /with/i,
+    longer_alt: Identifier,
+});
+export const AsKw = createToken({
+    name: "AsKw",
+    pattern: /as/i,
+    longer_alt: Identifier,
+});
+export const FromKw = createToken({
+    name: "FromKw",
+    pattern: /from/i,
+    longer_alt: Identifier,
+});
+export const InputKw = createToken({
+    name: "InputKw",
+    pattern: /input/i,
+    longer_alt: Identifier,
+});
+export const OutputKw = createToken({
+    name: "OutputKw",
+    pattern: /output/i,
+    longer_alt: Identifier,
+});
+export const ContextKw = createToken({
+    name: "ContextKw",
+    pattern: /context/i,
+    longer_alt: Identifier,
+});
+export const OnKw = createToken({
+    name: "OnKw",
+    pattern: /on/i,
+    longer_alt: Identifier,
+});
+export const ErrorKw = createToken({
+    name: "ErrorKw",
+    pattern: /error/i,
+    longer_alt: Identifier,
+});
+export const ForceKw = createToken({
+    name: "ForceKw",
+    pattern: /force/i,
+    longer_alt: Identifier,
+});
+export const AliasKw = createToken({
+    name: "AliasKw",
+    pattern: /alias/i,
+    longer_alt: Identifier,
+});
+export const CatchKw = createToken({
+    name: "CatchKw",
+    pattern: /catch/i,
+    longer_alt: Identifier,
+});
+export const AndKw = createToken({
+    name: "AndKw",
+    pattern: /and/,
+    longer_alt: Identifier,
+});
+export const OrKw = createToken({
+    name: "OrKw",
+    pattern: /or/,
+    longer_alt: Identifier,
+});
+export const NotKw = createToken({
+    name: "NotKw",
+    pattern: /not/,
+    longer_alt: Identifier,
+});
+export const ThrowKw = createToken({
+    name: "ThrowKw",
+    pattern: /throw/,
+    longer_alt: Identifier,
+});
+export const PanicKw = createToken({
+    name: "PanicKw",
+    pattern: /panic/,
+    longer_alt: Identifier,
+});
+export const ContinueKw = createToken({
+    name: "ContinueKw",
+    pattern: /continue/,
+    longer_alt: Identifier,
+});
+export const BreakKw = createToken({
+    name: "BreakKw",
+    pattern: /break/,
+    longer_alt: Identifier,
+});
 // ── Operators & punctuation ────────────────────────────────────────────────
 export const Arrow = createToken({ name: "Arrow", pattern: /<-/ });
-export const NullCoalesce = createToken({ name: "NullCoalesce", pattern: /\|\|/ });
-export const ErrorCoalesce = createToken({ name: "ErrorCoalesce", pattern: /\?\?/ });
+export const NullCoalesce = createToken({
+    name: "NullCoalesce",
+    pattern: /\|\|/,
+});
+export const ErrorCoalesce = createToken({
+    name: "ErrorCoalesce",
+    pattern: /\?\?/,
+});
 export const SafeNav = createToken({ name: "SafeNav", pattern: /\?\./ });
-export const QuestionMark = createToken({ name: "QuestionMark", pattern: /\?/ });
-export const GreaterEqual = createToken({ name: "GreaterEqual", pattern: />=/ });
+export const QuestionMark = createToken({
+    name: "QuestionMark",
+    pattern: /\?/,
+});
+export const GreaterEqual = createToken({
+    name: "GreaterEqual",
+    pattern: />=/,
+});
 export const LessEqual = createToken({ name: "LessEqual", pattern: /<=/ });
-export const DoubleEquals = createToken({ name: "DoubleEquals", pattern: /==/ });
+export const DoubleEquals = createToken({
+    name: "DoubleEquals",
+    pattern: /==/,
+});
 export const NotEquals = createToken({ name: "NotEquals", pattern: /!=/ });
 export const GreaterThan = createToken({ name: "GreaterThan", pattern: />/ });
 export const LessThan = createToken({ name: "LessThan", pattern: /</ });
@@ -74,6 +181,10 @@ export const Equals = createToken({ name: "Equals", pattern: /=/ });
 export const Dot = createToken({ name: "Dot", pattern: /\./ });
 export const Colon = createToken({ name: "Colon", pattern: /:/ });
 export const Comma = createToken({ name: "Comma", pattern: /,/ });
+export const VersionTag = createToken({
+    name: "VersionTag",
+    pattern: /@\d[\d.]*[\dx]*/,
+});
 // ── Literals ───────────────────────────────────────────────────────────────
 export const StringLiteral = createToken({
     name: "StringLiteral",
@@ -83,9 +194,21 @@ export const NumberLiteral = createToken({
     name: "NumberLiteral",
     pattern: /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/,
 });
-export const TrueLiteral = createToken({ name: "TrueLiteral", pattern: /true/, longer_alt: Identifier });
-export const FalseLiteral = createToken({ name: "FalseLiteral", pattern: /false/, longer_alt: Identifier });
-export const NullLiteral = createToken({ name: "NullLiteral", pattern: /null/, longer_alt: Identifier });
+export const TrueLiteral = createToken({
+    name: "TrueLiteral",
+    pattern: /true/,
+    longer_alt: Identifier,
+});
+export const FalseLiteral = createToken({
+    name: "FalseLiteral",
+    pattern: /false/,
+    longer_alt: Identifier,
+});
+export const NullLiteral = createToken({
+    name: "NullLiteral",
+    pattern: /null/,
+    longer_alt: Identifier,
+});
 export const PathToken = createToken({
     name: "PathToken",
     pattern: /\/[\w./-]+/,
@@ -120,6 +243,7 @@ export const allTokens = [
     Dot,
     Colon,
     Comma,
+    VersionTag,
     StringLiteral,
     // Keywords before Identifier (longer_alt prevents prefix stealing)
     VersionKw,

package/build/{parser → bridge-compiler/src/parser}/parser.d.ts

@@ -1,5 +1,14 @@
-import type { Instruction } from "@stackables/bridge-core";
-export declare function parseBridgeChevrotain(text: string): Instruction[];
+import type { BridgeDocument, Instruction } from "@stackables/bridge-core";
+/** Exported parser version metadata for runtime use. */
+export declare const PARSER_VERSION: {
+    /** Current bridge language version */
+    readonly current: "1.5";
+    /** Minimum supported major version (inclusive) */
+    readonly minMajor: 1;
+    /** Maximum supported major version (inclusive) */
+    readonly maxMajor: 1;
+};
+export declare function parseBridgeChevrotain(text: string): BridgeDocument;
 export type BridgeDiagnostic = {
     message: string;
     severity: "error" | "warning";
@@ -15,7 +24,7 @@ export type BridgeDiagnostic = {
     };
 };
 export type BridgeParseResult = {
-    instructions: Instruction[];
+    document: BridgeDocument;
     diagnostics: BridgeDiagnostic[];
     /** 1-based start line for each top-level instruction */
     startLines: Map<Instruction, number>;

package/build/bridge-compiler/src/parser/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/parser/parser.ts"],"names":[],"mappings":"AAoEA,OAAO,KAAK,EAEV,cAAc,EAKd,WAAW,EAMZ,MAAM,yBAAyB,CAAC;AAumCjC,wDAAwD;AACxD,eAAO,MAAM,cAAc;IACzB,sCAAsC;;IAEtC,kDAAkD;;IAElD,kDAAkD;;CAE1C,CAAC;AAMX,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAElE;AAID,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE;QACL,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,wDAAwD;IACxD,UAAU,EAAE,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA8DtE"}