cluaupp 1.5.2 → 2.0.0-beta.1

package/src/compiler/ast.ts

@@ -0,0 +1,336 @@
+/** CL++ syntax tree. The checker annotates nodes in place (`ty`, `res`, `sym`). */
+
+import type { Span } from "./source.js";
+import type { Type } from "./types.js";
+
+// ---------- types as written ----------
+
+export type TypeNode =
+	| { kind: "Named"; name: string; qualifier?: string; args: TypeNode[]; span: Span }
+	| { kind: "Literal"; value: string | number | boolean; span: Span }
+	| { kind: "Union"; members: TypeNode[]; span: Span }
+	| { kind: "Intersection"; members: TypeNode[]; span: Span }
+	| { kind: "Optional"; inner: TypeNode; span: Span }
+	| { kind: "Func"; params: TypeNode[]; ret: TypeNode | null; span: Span };
+
+// ---------- expressions ----------
+
+export interface ExprBase {
+	span: Span;
+	/** Type inferred by the checker. */
+	ty?: Type;
+	/** Resolution details for the emitter (what a name or member refers to). */
+	res?: Resolution;
+	/** CL++ value semantics: this read must be copied (struct/list/dictionary flowing into a new owner). */
+	copy?: boolean;
+	/** Type the checker narrowed this read to (`if (p != null)`), when it differs from the declared one. */
+	narrowedFrom?: Type;
+}
+
+export interface Arg {
+	name: string | null;
+	nameSpan?: Span;
+	value: Expr;
+}
+
+export interface Param {
+	name: string;
+	span: Span;
+	type: TypeNode | null;
+	variadic: boolean;
+	defaultValue: Expr | null;
+	/** Filled by the checker. */
+	ty?: Type;
+	sym?: SymbolRef;
+}
+
+export type Expr =
+	| (ExprBase & { kind: "Number"; value: number; isFloat: boolean; raw: string })
+	| (ExprBase & { kind: "String"; value: string })
+	| (ExprBase & { kind: "Template"; parts: Array<string | Expr> })
+	| (ExprBase & { kind: "Bool"; value: boolean })
+	| (ExprBase & { kind: "Null" })
+	| (ExprBase & { kind: "Name"; name: string; typeArgs: TypeNode[] | null })
+	| (ExprBase & { kind: "SelfField"; name: string; nameSpan: Span })
+	| (ExprBase & { kind: "Member"; object: Expr; name: string; nameSpan: Span; typeArgs: TypeNode[] | null })
+	| (ExprBase & { kind: "Scope"; object: Expr; name: string; nameSpan: Span })
+	| (ExprBase & { kind: "Index"; object: Expr; index: Expr })
+	| (ExprBase & { kind: "Call"; callee: Expr; args: Arg[]; legacyConnect?: boolean })
+	| (ExprBase & { kind: "New"; target: Expr; args: Arg[]; hasParens: boolean })
+	| (ExprBase & { kind: "Unary"; op: "-" | "not" | "~"; operand: Expr; loose: boolean })
+	| (ExprBase & { kind: "Binary"; op: BinaryOp; left: Expr; right: Expr; opSpan: Span })
+	| (ExprBase & { kind: "Ternary"; cond: Expr; then: Expr; else: Expr })
+	| (ExprBase & { kind: "Function"; params: Param[]; returnType: TypeNode | null; body: Stmt[] | Expr; isLambda: boolean; fn?: FuncInfo })
+	| (ExprBase & { kind: "Spawn"; call: Expr })
+	| (ExprBase & { kind: "Await"; operand: Expr })
+	| (ExprBase & { kind: "Thread"; call: Expr })
+	| (ExprBase & { kind: "Join"; operand: Expr })
+	| (ExprBase & { kind: "Move"; operand: Expr })
+	| (ExprBase & { kind: "PCall"; operand: Expr })
+	| (ExprBase & { kind: "Parallel"; calls: Expr[] })
+	| (ExprBase & { kind: "Update"; target: Expr; delta: 1 | -1; prefix: boolean })
+	| (ExprBase & { kind: "Cast"; operand: Expr; type: TypeNode })
+	| (ExprBase & { kind: "Error" });
+
+export type BinaryOp =
+	| "+" | "-" | "*" | "/" | "%" | ".:" | ".."
+	| "==" | "!=" | "<" | "<=" | ">" | ">="
+	| "and" | "or"
+	| "&" | "|" | "^" | "shl" | "shr";
+
+// ---------- statements ----------
+
+export interface StmtBase {
+	span: Span;
+	attributes?: Attribute[];
+}
+
+export interface Attribute {
+	name: string;
+	args: string[];
+	span: Span;
+}
+
+export type DeclKind = "let" | "let mut" | "typed" | "auto" | "const" | "constexpr" | "observable" | "atomic" | "decltype";
+
+export interface VarName {
+	name: string;
+	span: Span;
+	sym?: SymbolRef;
+}
+
+export interface MatchArm {
+	pattern: Pattern;
+	guard: Expr | null;
+	body: Stmt[];
+	span: Span;
+}
+
+export type Pattern =
+	| { kind: "Wildcard"; span: Span }
+	| { kind: "Value"; expr: Expr; span: Span }
+	| { kind: "Case"; name: string; qualifier: Expr | null; binding: VarName | null; span: Span; res?: Resolution; valueExpr?: Expr };
+
+export interface SwitchCase {
+	test: Expr | null;
+	body: Stmt[];
+	span: Span;
+}
+
+export type Stmt =
+	| (StmtBase & {
+			kind: "Var";
+			declKind: DeclKind;
+			names: VarName[];
+			unpack: boolean;
+			declaredType: TypeNode | null;
+			decltypeOf: Expr | null;
+			init: Expr | null;
+			/** Top-level `const` hoisted by the checker. */
+			predeclared?: boolean;
+	  })
+	| (StmtBase & { kind: "Assign"; target: Expr; op: "=" | "+=" | "-=" | "*=" | "/=" | "%="; value: Expr })
+	| (StmtBase & { kind: "Expr"; expr: Expr })
+	| (StmtBase & { kind: "If"; cond: Expr; letName: VarName | null; then: Stmt[]; else: Stmt[] | null })
+	| (StmtBase & { kind: "While"; cond: Expr; body: Stmt[] })
+	| (StmtBase & { kind: "For"; init: Stmt | null; cond: Expr | null; step: Stmt | null; body: Stmt[] })
+	| (StmtBase & { kind: "ForIn"; name: VarName; mutable: boolean; iterable: Expr; body: Stmt[]; declaredType?: TypeNode; iterKind?: IterKind; downcast?: boolean })
+	| (StmtBase & { kind: "Break" })
+	| (StmtBase & { kind: "Continue" })
+	| (StmtBase & { kind: "Return"; value: Expr | null })
+	| (StmtBase & { kind: "Switch"; subject: Expr; cases: SwitchCase[] })
+	| (StmtBase & { kind: "Match"; subject: Expr; arms: MatchArm[]; exhaustive?: boolean })
+	| (StmtBase & { kind: "Try"; body: Stmt[]; catchName: VarName | null; handler: Stmt[] })
+	| (StmtBase & { kind: "Output"; channel: "post" | "warn" | "report" | "cout"; value: Expr })
+	| (StmtBase & { kind: "Connect"; signal: Expr; handler: Expr; target?: "cl" | "rbx" })
+	| (StmtBase & { kind: "Signal"; name: VarName; params: TypeNode[] })
+	| (StmtBase & { kind: "Using"; module: string; member: string; memberSpan: Span; target?: Expr; sym?: SymbolRef })
+	| (StmtBase & { kind: "Block"; body: Stmt[] })
+	| (StmtBase & { kind: "Decl"; decl: Decl });
+
+export type IterKind = "range" | "list" | "string" | "dict" | "roblox-array" | "generic";
+
+// ---------- declarations ----------
+
+export interface FuncDecl {
+	kind: "Func";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	typeParams: string[];
+	params: Param[];
+	returnType: TypeNode | null;
+	/** null = declaration only (`func f();`, `extern func`, abstract). */
+	body: Stmt[] | null;
+	isAsync: boolean;
+	isExtern: boolean;
+	isStatic: boolean;
+	isAbstract: boolean;
+	isOverride: boolean;
+	isFinal: boolean;
+	isPrivate: boolean;
+	operator: "+" | "-" | "[]" | null;
+	where: Array<{ name: string; type: TypeNode }>;
+	attributes: Attribute[];
+	doc?: string;
+	fn?: FuncInfo;
+}
+
+export interface FieldDecl {
+	name: string;
+	nameSpan: Span;
+	type: TypeNode;
+	isPrivate: boolean;
+	span: Span;
+	defaultValue?: Expr;
+	doc?: string;
+}
+
+export interface StructDecl {
+	kind: "Struct";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	typeParams: string[];
+	bases: TypeNode[];
+	fields: FieldDecl[];
+	methods: FuncDecl[];
+	isAbstract: boolean;
+	isFinal: boolean;
+	attributes: Attribute[];
+	doc?: string;
+}
+
+export interface EnumDecl {
+	kind: "Enum";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	cases: Array<{ name: string; span: Span; payload: TypeNode | null }>;
+	attributes: Attribute[];
+	doc?: string;
+}
+
+export interface VariantDecl {
+	kind: "Variant";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	alternatives: TypeNode[];
+	attributes: Attribute[];
+}
+
+export interface TypeAliasDecl {
+	kind: "TypeAlias";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	type: TypeNode;
+	attributes: Attribute[];
+}
+
+export interface NamespaceDecl {
+	kind: "Namespace";
+	name: string;
+	nameSpan: Span;
+	span: Span;
+	funcs: FuncDecl[];
+	attributes: Attribute[];
+}
+
+export interface LinkDecl {
+	kind: "Link";
+	/** `@clpp.axiom` (with the @) or the quoted path text. */
+	path: string;
+	isPackage: boolean;
+	alias: string;
+	aliasExplicit: boolean;
+	pathSpan: Span;
+	aliasSpan: Span;
+	span: Span;
+	attributes: Attribute[];
+}
+
+export type Decl = FuncDecl | StructDecl | EnumDecl | VariantDecl | TypeAliasDecl | NamespaceDecl | LinkDecl;
+
+export interface Program {
+	file: string;
+	mode: "nonstrict" | "strict" | "nocheck";
+	directives: string[];
+	/** Declarations and statements in source order. */
+	body: Stmt[];
+}
+
+// ---------- checker annotations ----------
+
+/** Opaque handle to a checker symbol. */
+export interface SymbolRef {
+	id: number;
+	name: string;
+	/** Name used in the emitted Luau (after renaming collisions). */
+	luauName?: string;
+}
+
+export interface FuncInfo {
+	/** Is this function (or one it calls) able to yield? */
+	mayYield?: boolean;
+	isMethod?: boolean;
+	ownerStruct?: string;
+	selfMutated?: boolean;
+	capturesTopLevel?: boolean;
+}
+
+export type Resolution =
+	| { kind: "local"; sym: SymbolRef }
+	| { kind: "global"; luau: string }
+	| { kind: "service"; service: string }
+	| { kind: "func"; sym: SymbolRef }
+	| { kind: "struct"; name: string; sym: SymbolRef }
+	| { kind: "enum"; name: string; sym: SymbolRef }
+	| { kind: "enumCase"; enumName: string; index: number; hasPayload: boolean; anyPayload: boolean }
+	| { kind: "module"; alias: string; moduleId: string }
+	| { kind: "moduleMember"; alias: string; moduleId: string; member: string; memberKind: "func" | "const" | "struct" | "enum" | "value" }
+	| { kind: "const"; value: number | string | boolean | null }
+	| { kind: "field"; struct: string }
+	| { kind: "method"; struct: string; name: string; isStatic: boolean }
+	| { kind: "rbxProperty"; owner: string }
+	| { kind: "rbxMethod"; owner: string }
+	| { kind: "rbxEvent"; owner: string }
+	| { kind: "rbxChild"; owner: string; childName: string; safe: boolean }
+	| { kind: "rbxEnum"; enumName: string }
+	| { kind: "rbxEnumItem"; enumName: string; item: string }
+	| { kind: "datatypeStatic"; datatype: string; member: string }
+	| { kind: "datatypeMember"; datatype: string; member: string; isMethod: boolean }
+	| { kind: "library"; lib: string; member: string; stringMethod?: boolean }
+	| { kind: "vectorComponent"; component: string }
+	| { kind: "stdlib"; module: string; member: string }
+	| { kind: "builtin"; name: string }
+	| { kind: "signal"; sym: SymbolRef }
+	| { kind: "dynamic" }
+	| { kind: "luauMethod" }
+	| { kind: "sharedField"; name: string }
+	| { kind: "dataModel" }
+	| { kind: "call"; call: CallForm; args: Array<Expr | null>; variadicArgs?: Expr[] };
+
+/** How the emitter lowers a call (decided by the checker). */
+export type CallForm =
+	| { form: "call" }
+	| { form: "struct"; id: string }
+	| { form: "instance"; cls: string; props: Arg[]; parent: Expr | null }
+	| { form: "datatype"; name: string; props: Arg[] }
+	| { form: "enumCase"; enumId: string; index: number }
+	| { form: "some" }
+	| { form: "ok" }
+	| { form: "err" }
+	| { form: "variant" }
+	| { form: "builtin"; name: string; elemType?: Type }
+	| { form: "std"; module: string; fn: string }
+	| { form: "signalFire"; sym: SymbolRef }
+	| { form: "classArg"; cls: string; cast: boolean }
+	| { form: "cast"; to: Type }
+	| { form: "service"; service: string }
+	| { form: "convert"; to: "int" | "float" | "string" | "bool" }
+	| { form: "luauMethod" }
+	| { form: "stringMethod"; name: string }
+	| { form: "observe"; sym: SymbolRef }
+	| { form: "table"; keys: string[] };