From 1ee5ecc63645f5dc3bf0e38cd363b99524cd96af Mon Sep 17 00:00:00 2001 From: SammyBytes Date: Tue, 17 Nov 2026 00:31:29 -0400 Subject: [PATCH 1/2] feat: add edition directive support to the parser - tokenize `edition` as a keyword and track the Sam edition on the AST - default the program edition to "2026" when no directive is present - parse `edition "2026"` at the top of the file and reject unsupported editions with the supported list - reject edition directives that appear after another declaration - add parser tests for the default, valid, unsupported, and misplaced edition cases --- packages/compiler/src/lexer/tokens.ts | 2 + packages/compiler/src/parser/ast.ts | 9 +++++ packages/compiler/src/parser/index.test.ts | 35 ++++++++++++++++- packages/compiler/src/parser/index.ts | 45 +++++++++++++++++++++- packages/compiler/src/parser/types.ts | 2 + 5 files changed, 90 insertions(+), 3 deletions(-) diff --git a/packages/compiler/src/lexer/tokens.ts b/packages/compiler/src/lexer/tokens.ts index 17c7633..cc0d646 100644 --- a/packages/compiler/src/lexer/tokens.ts +++ b/packages/compiler/src/lexer/tokens.ts @@ -2,6 +2,7 @@ export type TokenType = | "SCHEMA" | "AGENT" | "PROVIDER" + | "EDITION" | "FLOW" | "PRIVATE" | "PARALLEL" @@ -45,6 +46,7 @@ export interface Token { export const KEYWORDS: Record = { schema: "SCHEMA", agent: "AGENT", + edition: "EDITION", provider: "PROVIDER", env: "ENV", true: "BOOLEAN", diff --git a/packages/compiler/src/parser/ast.ts b/packages/compiler/src/parser/ast.ts index 0f3b9cd..557fe18 100644 --- a/packages/compiler/src/parser/ast.ts +++ b/packages/compiler/src/parser/ast.ts @@ -135,6 +135,14 @@ export interface ProviderNode { properties: ProviderPropertyNode[]; // Array of provider properties } +//------------------------------------------------------------------ +// Edition Supported (v0.6.0) +//------------------------------------------------------------------ + +export const SUPPORTED_EDITIONS = ["2026"] as const; +export type SamEdition = (typeof SUPPORTED_EDITIONS)[number]; // The edition of the Sam language, e.g., "2026" +export const DEFAULT_EDITION: SamEdition = "2026"; // The default edition of the Sam language + //------------------------------------------------------------------ // AST Node Types //------------------------------------------------------------------ @@ -143,5 +151,6 @@ export type ASTNode = SchemaNode | AgentNode | FlowNode | ProviderNode; export interface ProgramNode { type: "Program"; + edition: SamEdition; // The edition of the Sam language, e.g., "2026" body: ASTNode[]; // Array of AST nodes, which can include schema declarations and other constructs } diff --git a/packages/compiler/src/parser/index.test.ts b/packages/compiler/src/parser/index.test.ts index 0ccb38e..75ebaea 100644 --- a/packages/compiler/src/parser/index.test.ts +++ b/packages/compiler/src/parser/index.test.ts @@ -728,4 +728,37 @@ test("should reject a non-boolean strict_schema provider property", () => { expect(() => new Parser(tokenize(code)).parse()).toThrow( /strict_schema/, ); -}); \ No newline at end of file +}); +test("defaults the edition to 2026 when no directive is present", () => { + const ast = new Parser(tokenize(`flow main() {}`)).parse(); + + expect(ast.edition).toBe("2026"); +}); + +test("accepts an edition directive at the top of the file", () => { + const ast = new Parser( + tokenize(`edition "2026"\n\nflow main() {}`), + ).parse(); + + expect(ast.edition).toBe("2026"); +}); + +test("rejects an unsupported edition", () => { + expect(() => + new Parser(tokenize(`edition "2099"\n\nflow main() {}`)).parse(), + ).toThrow(/Unsupported edition '2099'/); +}); + +test("rejects an edition directive below another declaration", () => { + const code = ` + provider Groq { + protocol: "openai-compatible" + base_url: "https://api.groq.com/openai/v1" + } + edition "2026" + `; + + expect(() => new Parser(tokenize(code)).parse()).toThrow( + /'edition' directive must appear only once at the top of the file \(line 6, column 5\)/, + ); +}); diff --git a/packages/compiler/src/parser/index.ts b/packages/compiler/src/parser/index.ts index 5327e5d..0f0acac 100644 --- a/packages/compiler/src/parser/index.ts +++ b/packages/compiler/src/parser/index.ts @@ -1,5 +1,11 @@ import type { Token, TokenType } from "../lexer/tokens"; -import type { ASTNode, ProgramNode } from "./ast"; +import { + DEFAULT_EDITION, + SUPPORTED_EDITIONS, + type ASTNode, + type ProgramNode, + type SamEdition, +} from "./ast"; import { parseAgent } from "./parsers/parseAgent"; import { parseFlow } from "./parsers/parseFlow"; import { parseProvider } from "./parsers/parseProvider"; @@ -10,9 +16,11 @@ import { validateProgram } from "./validator"; export class Parser implements IParserContext { private tokens: Token[]; private current: number; + public edition: SamEdition; - constructor(tokens: Token[]) { + constructor(tokens: Token[], edition: SamEdition = DEFAULT_EDITION) { this.tokens = tokens; + this.edition = edition; this.current = 0; } @@ -57,10 +65,22 @@ export class Parser implements IParserContext { public parse(): ProgramNode { const body: ASTNode[] = []; + switch (this.peek().type) { + case "EDITION": + this.edition = this.parseHeaderEdition(); + break; + default: + this.edition = DEFAULT_EDITION; // Default to 2026 if no edition is specified + } + while (!this.isAtEnd()) { const token = this.peek(); switch (token.type) { + case "EDITION": + throw new Error( + `SyntaxError: 'edition' directive must appear only once at the top of the file (line ${token.line}, column ${token.column})`, + ); case "SCHEMA": body.push(parseSchema(this)); break; @@ -83,10 +103,31 @@ export class Parser implements IParserContext { const programNode: ProgramNode = { type: "Program", + edition: this.edition, body, }; validateProgram(programNode); return programNode; } + + private parseHeaderEdition(): SamEdition { + const editionToken = this.peek(); + if (editionToken.type === "EDITION") { + this.advance(); // Consume the "EDITION" token + const editionValueToken = this.consume( + "STRING", + 'Expected a string value for the edition (e.g., edition "2026")', + ); + + const editionValue = editionValueToken.value; + if (!SUPPORTED_EDITIONS.includes(editionValue as SamEdition)) { + throw new Error( + `SyntaxError: Unsupported edition '${editionValue}' at line ${editionValueToken.line}, column ${editionValueToken.column}. Supported editions: ${SUPPORTED_EDITIONS.join(", ")}`, + ); + } + return editionValue as SamEdition; + } + return DEFAULT_EDITION; // Default to 2026 if no edition is specified + } } diff --git a/packages/compiler/src/parser/types.ts b/packages/compiler/src/parser/types.ts index f47722a..e3bde1a 100644 --- a/packages/compiler/src/parser/types.ts +++ b/packages/compiler/src/parser/types.ts @@ -1,8 +1,10 @@ import type { Token, TokenType } from "../lexer"; +import type { SamEdition } from "./ast"; export interface IParserContext { peek(): Token; advance(): Token; isAtEnd(): boolean; consume(type: TokenType, errorMessage: string): Token; + readonly edition: SamEdition; // The edition of the Sam language being used } From 5f1d13bd541984d59ac66cda7946cfbbba02f0fa Mon Sep 17 00:00:00 2001 From: SammyBytes Date: Tue, 17 Nov 2026 00:33:22 -0400 Subject: [PATCH 2/2] refactor: simplify edition parsing and tighten its tests - import Token types directly from `../lexer/tokens` in parser/types.ts - resolve the edition once in parse() instead of checking EDITION twice - add a test asserting the line and column of an edition directive that follows a flow --- packages/compiler/src/parser/index.test.ts | 8 +++++ packages/compiler/src/parser/index.ts | 39 ++++++++++------------ packages/compiler/src/parser/types.ts | 2 +- 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/packages/compiler/src/parser/index.test.ts b/packages/compiler/src/parser/index.test.ts index 75ebaea..6304cdd 100644 --- a/packages/compiler/src/parser/index.test.ts +++ b/packages/compiler/src/parser/index.test.ts @@ -762,3 +762,11 @@ test("rejects an edition directive below another declaration", () => { /'edition' directive must appear only once at the top of the file \(line 6, column 5\)/, ); }); + +test("reports the exact position of an edition directive that is not first", () => { + const code = `flow main() {}\nedition "2026"`; + + expect(() => new Parser(tokenize(code)).parse()).toThrow( + /'edition' directive must appear only once at the top of the file \(line 2, column 1\)/, + ); +}); diff --git a/packages/compiler/src/parser/index.ts b/packages/compiler/src/parser/index.ts index 0f0acac..28e40a2 100644 --- a/packages/compiler/src/parser/index.ts +++ b/packages/compiler/src/parser/index.ts @@ -65,13 +65,11 @@ export class Parser implements IParserContext { public parse(): ProgramNode { const body: ASTNode[] = []; - switch (this.peek().type) { - case "EDITION": - this.edition = this.parseHeaderEdition(); - break; - default: - this.edition = DEFAULT_EDITION; // Default to 2026 if no edition is specified - } + // The edition directive, when present, must be the first token. + this.edition = + this.peek().type === "EDITION" + ? this.parseHeaderEdition() + : DEFAULT_EDITION; while (!this.isAtEnd()) { const token = this.peek(); @@ -111,23 +109,20 @@ export class Parser implements IParserContext { return programNode; } + /** Consumes `edition ""`; the caller has already checked the token. */ private parseHeaderEdition(): SamEdition { - const editionToken = this.peek(); - if (editionToken.type === "EDITION") { - this.advance(); // Consume the "EDITION" token - const editionValueToken = this.consume( - "STRING", - 'Expected a string value for the edition (e.g., edition "2026")', - ); + this.advance(); // Consume the "EDITION" token + const editionValueToken = this.consume( + "STRING", + 'Expected a string value for the edition (e.g., edition "2026")', + ); - const editionValue = editionValueToken.value; - if (!SUPPORTED_EDITIONS.includes(editionValue as SamEdition)) { - throw new Error( - `SyntaxError: Unsupported edition '${editionValue}' at line ${editionValueToken.line}, column ${editionValueToken.column}. Supported editions: ${SUPPORTED_EDITIONS.join(", ")}`, - ); - } - return editionValue as SamEdition; + const editionValue = editionValueToken.value; + if (!SUPPORTED_EDITIONS.includes(editionValue as SamEdition)) { + throw new Error( + `SyntaxError: Unsupported edition '${editionValue}' at line ${editionValueToken.line}, column ${editionValueToken.column}. Supported editions: ${SUPPORTED_EDITIONS.join(", ")}`, + ); } - return DEFAULT_EDITION; // Default to 2026 if no edition is specified + return editionValue as SamEdition; } } diff --git a/packages/compiler/src/parser/types.ts b/packages/compiler/src/parser/types.ts index e3bde1a..77e6674 100644 --- a/packages/compiler/src/parser/types.ts +++ b/packages/compiler/src/parser/types.ts @@ -1,4 +1,4 @@ -import type { Token, TokenType } from "../lexer"; +import type { Token, TokenType } from "../lexer/tokens"; import type { SamEdition } from "./ast"; export interface IParserContext {