@hatchingpoint/point 0.0.5 → 0.0.6

package/README.md

@@ -2,20 +2,33 @@
 
 Point is an AI-first general-purpose language core for coding-agent-native software engineering.
 
+## Install
+
+Requires [Bun](https://bun.sh) on PATH.
+
+```bash
+npm install -g @hatchingpoint/point
+point check examples/math.point
+```
+
+Pair with the [Point Language](https://marketplace.visualstudio.com/items?itemName=hatchingpoint.point) extension in VS Code or Cursor.
+
+Point's public source language is semantic product logic. The compiler lowers that source into an internal typed core and emits TypeScript for existing JavaScript infrastructure.
+
 This package is the source of truth for Point. It exposes:
 
 - `point` CLI through `src/cli.ts`
 - core language APIs through `@hatchingpoint/point/core`
-- core parser, formatter, checker, and TypeScript emitter APIs
+- semantic parser/lowering, core checker, formatter, and TypeScript emitter APIs
 
 Core workflow:
 
 ```bash
-bun run point:fmt-check:all
-bun run point:check:all
-bun run point:build:all
+bun run fmt-check
+bun run check
+bun run build
 ```
 
-`point:build:all` emits TypeScript that can be imported by React, Vue, Bun, Node, and Vite projects.
+`bun run build` emits TypeScript into `generated/` for React, Vue, Bun, Node, and Vite projects.
 
 When Point is extracted, this package can move into a standalone repo with the same package name and public entrypoints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatchingpoint/point",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "private": false,
   "type": "module",
   "description": "Point language compiler and CLI.",

package/src/core/ast.ts

@@ -1,3 +1,5 @@
+import type { PointSemanticProgram } from "../semantic/ast.ts";
+
 export type PointCorePrimitiveType = "Text" | "Int" | "Float" | "Bool" | "Void";
 
 export interface PointSourcePosition {
@@ -16,10 +18,13 @@ export interface PointCoreProgram {
 	module?: string;
 	declarations: PointCoreDeclaration[];
 	span?: PointSourceSpan;
+	semantic?: PointSemanticProgramMetadata;
+	semanticSource?: PointSemanticProgram;
 }
 
 export type PointCoreDeclaration =
 	| PointCoreImportDeclaration
+	| PointCoreExternalDeclaration
 	| PointCoreValueDeclaration
 	| PointCoreFunctionDeclaration
 	| PointCoreTypeDeclaration;
@@ -47,6 +52,18 @@ export interface PointCoreFunctionDeclaration {
 	returnType: PointCoreTypeExpression;
 	body: PointCoreStatement[];
 	span?: PointSourceSpan;
+	semantic?: PointSemanticDeclarationMetadata;
+}
+
+export interface PointCoreExternalDeclaration {
+	kind: "external";
+	name: string;
+	params: PointCoreParameter[];
+	returnType: PointCoreTypeExpression;
+	from: string;
+	importName?: string;
+	span?: PointSourceSpan;
+	semantic?: PointSemanticDeclarationMetadata;
 }
 
 export interface PointCoreTypeDeclaration {
@@ -54,12 +71,25 @@ export interface PointCoreTypeDeclaration {
 	name: string;
 	fields: PointCoreParameter[];
 	span?: PointSourceSpan;
+	semantic?: PointSemanticDeclarationMetadata;
 }
 
 export interface PointCoreParameter {
 	name: string;
 	type: PointCoreTypeExpression;
 	span?: PointSourceSpan;
+	semanticName?: string;
+}
+
+export interface PointSemanticProgramMetadata {
+	source: "semantic";
+}
+
+export interface PointSemanticDeclarationMetadata {
+	kind: "record" | "calculation" | "rule" | "label" | "external" | "action" | "policy" | "view" | "route" | "workflow" | "command";
+	name: string;
+	outputName?: string;
+	effects?: string[];
 }
 
 export interface PointCoreTypeExpression {
@@ -81,7 +111,7 @@ export type PointCoreStatement =
 	| {
 			kind: "assignment";
 			name: string;
-			operator: "=" | "+=";
+			operator: "=" | "+=" | "-=";
 			value: PointCoreExpression;
 			span?: PointSourceSpan;
 	  }
@@ -92,14 +122,22 @@ export type PointCoreStatement =
 			elseBody: PointCoreStatement[];
 			span?: PointSourceSpan;
 	  }
+	| {
+			kind: "for";
+			itemName: string;
+			iterable: PointCoreExpression;
+			body: PointCoreStatement[];
+			span?: PointSourceSpan;
+	  }
 	| { kind: "expression"; value: PointCoreExpression; span?: PointSourceSpan };
 
 export type PointCoreExpression =
-	| { kind: "literal"; value: string | number | boolean; span?: PointSourceSpan }
+	| { kind: "literal"; value: string | number | boolean | null; span?: PointSourceSpan }
 	| { kind: "identifier"; name: string; span?: PointSourceSpan }
 	| { kind: "list"; items: PointCoreExpression[]; span?: PointSourceSpan }
 	| { kind: "record"; fields: PointCoreRecordField[]; span?: PointSourceSpan }
 	| { kind: "property"; target: PointCoreExpression; name: string; span?: PointSourceSpan }
+	| { kind: "await"; value: PointCoreExpression; span?: PointSourceSpan }
 	| {
 			kind: "binary";
 			operator: PointCoreBinaryOperator;

package/src/core/check.ts

@@ -1,7 +1,8 @@
 import type {
 	PointCoreDeclaration,
-	PointCoreExpression,
-	PointCoreFunctionDeclaration,
+	PointCoreExpression,
+	PointCoreExternalDeclaration,
+	PointCoreFunctionDeclaration,
 	PointCoreProgram,
 	PointCoreStatement,
 	PointCoreTypeDeclaration,
@@ -27,7 +28,7 @@ type DiagnosticMetadata = Partial<Pick<PointCoreDiagnostic, "expected" | "actual
 type ScopeEntry = { type: PointCoreTypeExpression; mutable: boolean };
 type Scope = Map<string, ScopeEntry>;
 
-const PRIMITIVE_TYPES = new Set(["Text", "Int", "Float", "Bool", "Void", "List"]);
+const PRIMITIVE_TYPES = new Set(["Text", "Int", "Float", "Bool", "Void", "List", "Maybe", "Error", "Or"]);
 
 export function checkPointCore(program: PointCoreProgram): PointCoreDiagnostic[] {
 	const checker = new CoreChecker(program);
@@ -39,7 +40,7 @@ class CoreChecker {
 	private readonly types = new Set(PRIMITIVE_TYPES);
 	private readonly typeDeclarations = new Map<string, PointCoreTypeDeclaration>();
 	private readonly globals: Scope = new Map();
-	private readonly functions = new Map<string, PointCoreFunctionDeclaration>();
+	private readonly functions = new Map<string, PointCoreFunctionDeclaration | PointCoreExternalDeclaration>();
 
 	constructor(private readonly program: PointCoreProgram) {}
 
@@ -59,12 +60,18 @@ class CoreChecker {
 				this.typeDeclarations.set(declaration.name, declaration);
 			}
 			if (declaration.kind === "value") this.addGlobal(declaration);
-			if (declaration.kind === "function") {
+			if (declaration.kind === "function") {
 				if (this.functions.has(declaration.name)) {
 					this.push("duplicate-function", `Duplicate function ${declaration.name}`, `fn.${declaration.name}`, declaration.span);
 				}
-				this.functions.set(declaration.name, declaration);
-			}
+				this.functions.set(declaration.name, declaration);
+			}
+			if (declaration.kind === "external") {
+				if (this.functions.has(declaration.name)) {
+					this.push("duplicate-function", `Duplicate function ${declaration.name}`, `external.${declaration.name}`, declaration.span);
+				}
+				this.functions.set(declaration.name, declaration);
+			}
 		}
 	}
 
@@ -76,7 +83,12 @@ class CoreChecker {
 	}
 
 	private checkDeclaration(declaration: PointCoreDeclaration) {
-		if (declaration.kind === "import") return;
+		if (declaration.kind === "import") return;
+		if (declaration.kind === "external") {
+			for (const param of declaration.params) this.checkType(param.type, `external.${declaration.name}.${param.name}.type`);
+			this.checkType(declaration.returnType, `external.${declaration.name}.return`);
+			return;
+		}
 		if (declaration.kind === "type") {
 			for (const field of declaration.fields) this.checkType(field.type, `type.${declaration.name}.${field.name}`);
 			return;
@@ -126,16 +138,41 @@ class CoreChecker {
 			this.checkAssignment(statement, fn, locals);
 			return;
 		}
-		if (statement.kind === "if") {
-			this.checkExpressionAssignable(statement.condition, typeRef("Bool"), `fn.${fn.name}.if.condition`, locals);
-			const thenLocals = new Map(locals);
-			for (const child of statement.thenBody) this.checkStatement(child, fn, thenLocals);
-			const elseLocals = new Map(locals);
-			for (const child of statement.elseBody) this.checkStatement(child, fn, elseLocals);
-			return;
-		}
-		this.typeOfExpression(statement.value, locals, `fn.${fn.name}.expression`);
-	}
+		if (statement.kind === "if") {
+			this.checkExpressionAssignable(statement.condition, typeRef("Bool"), `fn.${fn.name}.if.condition`, locals);
+			const thenLocals = new Map(locals);
+			for (const child of statement.thenBody) this.checkStatement(child, fn, thenLocals);
+			const elseLocals = new Map(locals);
+			for (const child of statement.elseBody) this.checkStatement(child, fn, elseLocals);
+			return;
+		}
+		if (statement.kind === "for") {
+			this.checkForStatement(statement, fn, locals);
+			return;
+		}
+		this.typeOfExpression(statement.value, locals, `fn.${fn.name}.expression`);
+	}
+
+	private checkForStatement(
+		statement: Extract<PointCoreStatement, { kind: "for" }>,
+		fn: PointCoreFunctionDeclaration,
+		locals: Scope,
+	) {
+		const path = `fn.${fn.name}.for.${statement.itemName}`;
+		const iterableType = this.typeOfExpression(statement.iterable, locals, `${path}.iterable`);
+		if (!iterableType) return;
+		if (iterableType.name !== "List" || iterableType.args.length !== 1) {
+			this.push("iteration-type-mismatch", "for requires a List<T> iterable", path, statement.span, {
+				expected: "List<T>",
+				actual: formatType(iterableType),
+				repair: "Iterate over a List<T> value or change this expression to a list.",
+			});
+			return;
+		}
+		const loopLocals = new Map(locals);
+		loopLocals.set(statement.itemName, { type: iterableType.args[0]!, mutable: false });
+		for (const child of statement.body) this.checkStatement(child, fn, loopLocals);
+	}
 
 	private checkAssignment(
 		statement: Extract<PointCoreStatement, { kind: "assignment" }>,
@@ -158,25 +195,48 @@ class CoreChecker {
 				repair: `Declare ${statement.name} with var if it needs to change.`,
 			});
 		}
-		if (statement.operator === "+=" && !isNumeric(String(target.type.name))) {
-			this.push("operator-type-mismatch", "+= requires a numeric target", path, statement.span, {
-				expected: "Int or Float target",
-				actual: formatType(target.type),
-				repair: "Use += only with Int or Float values.",
-			});
-		}
+		if ((statement.operator === "+=" || statement.operator === "-=") && !isNumeric(String(target.type.name))) {
+			this.push("operator-type-mismatch", `${statement.operator} requires a numeric target`, path, statement.span, {
+				expected: "Int or Float target",
+				actual: formatType(target.type),
+				repair: `Use ${statement.operator} only with Int or Float values.`,
+			});
+		}
 		this.checkExpressionAssignable(statement.value, target.type, `${path}.value`, locals);
 	}
 
-	private checkExpressionAssignable(
-		expression: PointCoreExpression,
-		expected: PointCoreTypeExpression,
-		path: string,
-		scope: Scope,
-	) {
-		if (expression.kind === "list") {
-			this.checkListAssignable(expression, expected, path, scope);
-			return;
+	private checkExpressionAssignable(
+		expression: PointCoreExpression,
+		expected: PointCoreTypeExpression,
+		path: string,
+		scope: Scope,
+	) {
+		if (expected.name === "Maybe" && expected.args.length === 1) {
+			if (expression.kind === "literal" && expression.value === null) return;
+			if (expression.kind !== "record" && expression.kind !== "list") {
+				const actual = this.typeOfExpression(expression, scope, path);
+				if (actual && sameType(actual, expected)) return;
+			}
+			this.checkExpressionAssignable(expression, expected.args[0]!, path, scope);
+			return;
+		}
+		if (expected.name === "Or" && expected.args.length > 0) {
+			const diagnosticsBefore = this.diagnostics.length;
+			const actual = this.typeOfExpression(expression, scope, path);
+			if (!actual) return;
+			if (sameType(actual, expected)) return;
+			if (expected.args.some((candidate) => sameType(candidate, actual))) return;
+			this.push("type-mismatch", `Expected ${formatType(expected)}, got ${formatType(actual)}`, path, expression.span, {
+				expected: formatType(expected),
+				actual: formatType(actual),
+				repair: `Return or assign one of: ${expected.args.map(formatType).join(", ")}.`,
+			});
+			if (this.diagnostics.length > diagnosticsBefore + 1) return;
+			return;
+		}
+		if (expression.kind === "list") {
+			this.checkListAssignable(expression, expected, path, scope);
+			return;
 		}
 		if (expression.kind === "record") {
 			this.checkRecordAssignable(expression, expected, path, scope);
@@ -251,15 +311,17 @@ class CoreChecker {
 		}
 	}
 
-	private typeOfExpression(
-		expression: PointCoreExpression,
-		scope: Scope,
-		path: string,
-	): PointCoreTypeExpression | null {
-		if (expression.kind === "literal") {
-			const valueType =
-				typeof expression.value === "string"
-					? "Text"
+	private typeOfExpression(
+		expression: PointCoreExpression,
+		scope: Scope,
+		path: string,
+		awaitedCall = false,
+	): PointCoreTypeExpression | null {
+		if (expression.kind === "literal") {
+			if (expression.value === null) return { kind: "typeRef", name: "Void", args: [], span: expression.span };
+			const valueType =
+				typeof expression.value === "string"
+					? "Text"
 					: typeof expression.value === "boolean"
 						? "Bool"
 						: Number.isInteger(expression.value)
@@ -286,19 +348,45 @@ class CoreChecker {
 		if (expression.kind === "binary") {
 			return this.typeOfBinaryExpression(expression, scope, path);
 		}
-		if (expression.kind === "property") {
-			return this.typeOfPropertyExpression(expression, scope, path);
-		}
-		const target = this.functions.get(expression.callee);
-		if (!target) {
-			this.push("unknown-function", `Unknown function ${expression.callee}`, path, expression.span, {
-				actual: expression.callee,
-				expected: [...this.functions.keys()],
-				repair: `Define fn ${expression.callee}(...) or call an existing function.`,
-			});
-			return null;
-		}
-		if (target.params.length !== expression.args.length) {
+		if (expression.kind === "property") {
+			return this.typeOfPropertyExpression(expression, scope, path);
+		}
+		if (expression.kind === "await") {
+			return this.typeOfExpression(expression.value, scope, path, true);
+		}
+		if (expression.callee === "Error") {
+			if (expression.args.length !== 1) {
+				this.push("arity-mismatch", "Error expects 1 message argument", path, expression.span, {
+					expected: "1 arg",
+					actual: `${expression.args.length} args`,
+					repair: "Construct errors as Error(\"message\").",
+				});
+			}
+			const message = expression.args[0];
+			if (message) this.checkExpressionAssignable(message, typeRef("Text"), `${path}.message`, scope);
+			return typeRef("Error", [], expression.span);
+		}
+		if (expression.callee === "Ok") {
+			return expression.args[0] ? this.typeOfExpression(expression.args[0], scope, `${path}.value`) : typeRef("Void", [], expression.span);
+		}
+		const target = this.functions.get(expression.callee);
+		if (!target) {
+			this.push("unknown-function", `Unknown function ${expression.callee}`, path, expression.span, {
+				actual: expression.callee,
+				expected: [...this.functions.keys()],
+				repair: `Define fn ${expression.callee}(...) or call an existing function.`,
+			});
+			return null;
+		}
+		if ((target.semantic?.kind === "action" || target.semantic?.kind === "workflow") && !awaitedCall) {
+			this.push("missing-await", `Action ${expression.callee} must be awaited`, path, expression.span, {
+				expected: `await ${expression.callee}(...)`,
+				actual: `${expression.callee}(...)`,
+				repair: "Prefix this action call with await.",
+				relatedRefs: [this.refFor(`fn.${target.name}`)],
+			});
+		}
+		if (target.params.length !== expression.args.length) {
 			this.push("arity-mismatch", `Function ${expression.callee} expects ${target.params.length} args`, path, expression.span, {
 				expected: `${target.params.length} args`,
 				actual: `${expression.args.length} args`,
@@ -338,9 +426,17 @@ class CoreChecker {
 		scope: Scope,
 		path: string,
 	): PointCoreTypeExpression | null {
-		const targetType = this.typeOfExpression(expression.target, scope, `${path}.target`);
-		if (!targetType) return null;
-		const declaration = this.typeDeclarations.get(String(targetType.name));
+		const targetType = this.typeOfExpression(expression.target, scope, `${path}.target`);
+		if (!targetType) return null;
+		if (targetType.name === "Maybe" && targetType.args.length === 1) {
+			this.push("nullable-field-access", `Cannot access field ${expression.name} on nullable ${formatType(targetType)}`, path, expression.span, {
+				expected: formatType(targetType.args[0]!),
+				actual: formatType(targetType),
+				repair: "Check that this Maybe value is present before accessing its fields.",
+			});
+			return null;
+		}
+		const declaration = this.typeDeclarations.get(String(targetType.name));
 		if (!declaration) {
 			this.push("not-a-record", `${formatType(targetType)} has no fields`, path, expression.span, {
 				actual: formatType(targetType),
@@ -414,14 +510,28 @@ class CoreChecker {
 				repair: `Declare type ${type.name} or use an existing type.`,
 			});
 		}
-		if (type.name === "List" && type.args.length !== 1) {
+		if (type.name === "List" && type.args.length !== 1) {
 			this.push("invalid-type-arity", "List requires one type argument", path, type.span, {
 				expected: "List<T>",
 				actual: formatType(type),
 				repair: "Use List<Text>, List<Int>, or another concrete item type.",
 			});
-		}
-		if (type.name !== "List" && type.args.length > 0 && !this.typeDeclarations.has(String(type.name))) {
+		}
+		if (type.name === "Maybe" && type.args.length !== 1) {
+			this.push("invalid-type-arity", "Maybe requires one type argument", path, type.span, {
+				expected: "Maybe<T>",
+				actual: formatType(type),
+				repair: "Use Maybe<Text>, Maybe<User>, or another concrete optional type.",
+			});
+		}
+		if (type.name === "Or" && type.args.length < 2) {
+			this.push("invalid-type-arity", "Or requires at least two type arguments", path, type.span, {
+				expected: "A or B",
+				actual: formatType(type),
+				repair: "Use syntax such as User or Error.",
+			});
+		}
+		if (type.name !== "List" && type.name !== "Maybe" && type.name !== "Or" && type.args.length > 0 && !this.typeDeclarations.has(String(type.name))) {
 			this.push("invalid-type-arity", `${type.name} does not accept type arguments`, path, type.span, {
 				expected: String(type.name),
 				actual: formatType(type),
@@ -468,11 +578,12 @@ function sameType(left: PointCoreTypeExpression, right: PointCoreTypeExpression)
 	return left.name === right.name && leftArgs.length === rightArgs.length && leftArgs.every((arg, index) => sameType(arg, rightArgs[index]!));
 }
 
-function formatType(type: PointCoreTypeExpression): string {
-	const args = type.args ?? [];
-	if (args.length === 0) return String(type.name);
-	return `${type.name}<${args.map(formatType).join(", ")}>`;
-}
+function formatType(type: PointCoreTypeExpression): string {
+	const args = type.args ?? [];
+	if (args.length === 0) return String(type.name);
+	if (type.name === "Or") return args.map(formatType).join(" or ");
+	return `${type.name}<${args.map(formatType).join(", ")}>`;
+}
 
 function typeRef(name: string, args: PointCoreTypeExpression[] = [], span?: PointSourceSpan): PointCoreTypeExpression {
 	return { kind: "typeRef", name, args, span };