@stackables/bridge-compiler 0.0.1 → 1.0.0

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-format.d.ts

@@ -1,8 +1,8 @@
-import type { Instruction } from "@stackables/bridge-core";
+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): Instruction[];
-export declare function serializeBridge(instructions: Instruction[]): string;
+export declare function parseBridge(text: string): BridgeDocument;
+export declare function serializeBridge(doc: BridgeDocument): string;
 //# sourceMappingURL=bridge-format.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bridge-format.d.ts","sourceRoot":"","sources":["../src/bridge-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAKV,WAAW,EAIZ,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAEvD;AAcD,wBAAgB,eAAe,CAAC,YAAY,EAAE,WAAW,EAAE,GAAG,MAAM,CAgCnE"}
+{"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

@@ -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/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/index.d.ts.map

@@ -1 +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,GACvB,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,EAAE,WAAW,IAAI,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIvF,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,QAAQ,EACR,KAAK,GACN,MAAM,uBAAuB,CAAC"}
+{"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

@@ -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/language-service.d.ts.map

@@ -1 +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;AAU1D,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;IA+BpC;;OAEG;IACH,cAAc,CAAC,GAAG,EAAE,QAAQ,GAAG,gBAAgB,EAAE;IA4CjD;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,WAAW,GAAG,IAAI;CAqE5C"}
+{"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

@@ -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/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/parser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}
+{"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/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/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/parser/lexer.d.ts.map

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

package/build/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/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/parser/parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/parser/parser.ts"],"names":[],"mappings":"AAmEA,OAAO,KAAK,EAMV,WAAW,EAMZ,MAAM,yBAAyB,CAAC;AAimCjC,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAEjE;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,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,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"}
+{"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"}

package/build/parser/parser.js

@@ -5,7 +5,7 @@
  * Produces the *exact same* AST types (`Instruction[]`).
  */
 import { CstParser } from "chevrotain";
-import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, BridgeLexer, } from "./lexer.js";
+import { allTokens, Identifier, VersionKw, ToolKw, BridgeKw, DefineKw, ConstKw, WithKw, AsKw, FromKw, InputKw, OutputKw, ContextKw, OnKw, ErrorKw, Arrow, ForceKw, AliasKw, AndKw, OrKw, NotKw, ThrowKw, PanicKw, ContinueKw, BreakKw, NullCoalesce, ErrorCoalesce, SafeNav, CatchKw, LParen, RParen, LCurly, RCurly, LSquare, RSquare, Equals, Dot, Colon, Comma, StringLiteral, NumberLiteral, PathToken, TrueLiteral, FalseLiteral, NullLiteral, Star, Slash, Plus, Minus, GreaterEqual, LessEqual, DoubleEquals, NotEquals, GreaterThan, LessThan, QuestionMark, VersionTag, BridgeLexer, } from "./lexer.js";
 import { SELF_MODULE } from "@stackables/bridge-core";
 // ── Reserved-word guards (mirroring the regex parser) ──────────────────────
 const RESERVED_KEYWORDS = new Set([
@@ -160,6 +160,9 @@ class BridgeParser extends CstParser {
                 },
                 ALT: () => {
                     this.SUBRULE(this.dottedName, { LABEL: "toolName" });
+                    this.OPTION3(() => {
+                        this.CONSUME(VersionTag, { LABEL: "toolVersion" });
+                    });
                     this.CONSUME3(AsKw);
                     this.SUBRULE3(this.nameToken, { LABEL: "toolAlias" });
                 },
@@ -350,6 +353,9 @@ class BridgeParser extends CstParser {
                 },
                 ALT: () => {
                     this.SUBRULE(this.dottedName, { LABEL: "refName" });
+                    this.OPTION6(() => {
+                        this.CONSUME(VersionTag, { LABEL: "refVersion" });
+                    });
                     this.OPTION5(() => {
                         this.CONSUME5(AsKw);
                         this.SUBRULE5(this.nameToken, { LABEL: "refAlias" });
@@ -1051,6 +1057,19 @@ const parserInstance = new BridgeParser();
 // Lenient instance: error recovery enabled (used by parseBridgeDiagnostics)
 const diagParserInstance = new BridgeParser({ recovery: true });
 const BRIDGE_VERSION = "1.5";
+/** Minimum major version the parser can handle (inclusive). */
+const BRIDGE_MIN_MAJOR = 1;
+/** Maximum major version the parser can handle (inclusive). */
+const BRIDGE_MAX_MAJOR = 1;
+/** Exported parser version metadata for runtime use. */
+export const PARSER_VERSION = {
+    /** Current bridge language version */
+    current: BRIDGE_VERSION,
+    /** Minimum supported major version (inclusive) */
+    minMajor: BRIDGE_MIN_MAJOR,
+    /** Maximum supported major version (inclusive) */
+    maxMajor: BRIDGE_MAX_MAJOR,
+};
 // ═══════════════════════════════════════════════════════════════════════════
 //  Public API
 // ═══════════════════════════════════════════════════════════════════════════
@@ -1100,11 +1119,11 @@ export function parseBridgeDiagnostics(text) {
         });
     }
     // 3. Visit → AST (semantic errors thrown as "Line N: ..." messages)
-    let instructions = [];
+    let document = { instructions: [] };
     let startLines = new Map();
     try {
         const result = toBridgeAst(cst, []);
-        instructions = result.instructions;
+        document = { version: result.version, instructions: result.instructions };
         startLines = result.startLines;
     }
     catch (err) {
@@ -1120,7 +1139,7 @@ export function parseBridgeDiagnostics(text) {
             },
         });
     }
-    return { instructions, diagnostics, startLines };
+    return { document, diagnostics, startLines };
 }
 function internalParse(text, previousInstructions) {
     // 1. Lex
@@ -1137,7 +1156,8 @@ function internalParse(text, previousInstructions) {
         throw new Error(e.message);
     }
     // 3. Visit → AST
-    return toBridgeAst(cst, previousInstructions).instructions;
+    const result = toBridgeAst(cst, previousInstructions);
+    return { version: result.version, instructions: result.instructions };
 }
 // ═══════════════════════════════════════════════════════════════════════════
 //  CST → AST transformation (imperative visitor)
@@ -2204,9 +2224,22 @@ function toBridgeAst(cst, previousInstructions) {
     }
     const versionTok = tok(versionDecl, "ver");
     const versionNum = versionTok?.image;
-    if (versionNum !== BRIDGE_VERSION) {
-        throw new Error(`Unsupported bridge version "${versionNum}". This parser requires: version ${BRIDGE_VERSION}`);
+    if (!versionNum) {
+        throw new Error(`Missing version number. Bridge files must begin with: version ${BRIDGE_VERSION}`);
+    }
+    // Accept any version whose major falls within the supported range.
+    // When the parser supports multiple majors (e.g. 1.x through 2.x),
+    // bridge files from any of them are valid syntax.
+    const vParts = versionNum.split(".");
+    const vMajor = parseInt(vParts[0], 10);
+    const supportedRange = BRIDGE_MIN_MAJOR === BRIDGE_MAX_MAJOR
+        ? `${BRIDGE_MIN_MAJOR}.x`
+        : `${BRIDGE_MIN_MAJOR}.x – ${BRIDGE_MAX_MAJOR}.x`;
+    if (isNaN(vMajor) || vMajor < BRIDGE_MIN_MAJOR || vMajor > BRIDGE_MAX_MAJOR) {
+        throw new Error(`Unsupported bridge major version "${versionNum}". This parser supports version ${supportedRange}`);
     }
+    // Store the declared version (lives on BridgeDocument, not in instructions).
+    const version = versionNum;
     const tagged = [];
     for (const n of subs(cst, "constDecl"))
         tagged.push({
@@ -2270,7 +2303,7 @@ function toBridgeAst(cst, previousInstructions) {
             }
         }
     }
-    return { instructions, startLines };
+    return { version, instructions, startLines };
 }
 // ── Const ───────────────────────────────────────────────────────────────
 function buildConstDef(node) {
@@ -2319,7 +2352,13 @@ function buildToolDef(node, previousInstructions) {
             else if (wc.toolName) {
                 const tName = extractDottedName(wc.toolName[0]);
                 const tAlias = extractNameToken(wc.toolAlias[0]);
-                deps.push({ kind: "tool", handle: tAlias, tool: tName });
+                const tVersion = wc.toolVersion?.[0]?.image.slice(1);
+                deps.push({
+                    kind: "tool",
+                    handle: tAlias,
+                    tool: tName,
+                    ...(tVersion ? { version: tVersion } : {}),
+                });
             }
             continue;
         }
@@ -2400,10 +2439,10 @@ function buildBridge(node, previousInstructions) {
             `}`,
         ].join("\n");
         const result = internalParse(expandedText, previousInstructions);
-        const bridgeInst = result.find((i) => i.kind === "bridge");
+        const bridgeInst = result.instructions.find((i) => i.kind === "bridge");
         if (bridgeInst)
             bridgeInst.passthrough = passthroughName;
-        return result;
+        return result.instructions;
     }
     // Full bridge block
     const bodyLines = subs(node, "bridgeBodyLine");
@@ -2530,6 +2569,7 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
         }
         else if (wc.refName) {
             const name = extractDottedName(wc.refName[0]);
+            const versionTag = wc.refVersion?.[0]?.image.slice(1);
             const lastDot = name.lastIndexOf(".");
             const defaultHandle = lastDot !== -1 ? name.substring(lastDot + 1) : name;
             const handle = wc.refAlias
@@ -2554,7 +2594,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
                 const key = `${modulePart}:${fieldPart}`;
                 const instance = (instanceCounters.get(key) ?? 0) + 1;
                 instanceCounters.set(key, instance);
-                handleBindings.push({ handle, kind: "tool", name });
+                handleBindings.push({
+                    handle,
+                    kind: "tool",
+                    name,
+                    ...(versionTag ? { version: versionTag } : {}),
+                });
                 handleRes.set(handle, {
                     module: modulePart,
                     type: bridgeType,
@@ -2566,7 +2611,12 @@ function buildBridgeBody(bodyLines, bridgeType, bridgeField, previousInstruction
                 const key = `Tools:${name}`;
                 const instance = (instanceCounters.get(key) ?? 0) + 1;
                 instanceCounters.set(key, instance);
-                handleBindings.push({ handle, kind: "tool", name });
+                handleBindings.push({
+                    handle,
+                    kind: "tool",
+                    name,
+                    ...(versionTag ? { version: versionTag } : {}),
+                });
                 handleRes.set(handle, {
                     module: SELF_MODULE,
                     type: "Tools",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackables/bridge-compiler",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "Bridge DSL parser, serializer, and language service",
   "main": "./build/index.js",
   "type": "module",
@@ -23,8 +23,8 @@
   "license": "MIT",
   "dependencies": {
     "chevrotain": "^11.1.2",
-    "@stackables/bridge-core": "0.0.1",
-    "@stackables/bridge-stdlib": "0.0.1"
+    "@stackables/bridge-core": "1.0.0",
+    "@stackables/bridge-stdlib": "1.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.2",