@hatchingpoint/point 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Point
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# Point
+
+Point is an AI-first general-purpose language core for coding-agent-native software engineering.
+
+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
+
+Core workflow:
+
+```bash
+bun run point:fmt-check:all
+bun run point:check:all
+bun run point:build:all
+```
+
+`point:build:all` emits TypeScript that can be imported by 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

@@ -0,0 +1,30 @@
+{
+  "name": "@hatchingpoint/point",
+  "version": "0.0.3",
+  "private": false,
+  "type": "module",
+  "description": "Point language compiler and CLI.",
+  "homepage": "https://github.com/HatchingPoint/point#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HatchingPoint/point.git",
+    "directory": "packages/point"
+  },
+  "bugs": {
+    "url": "https://github.com/HatchingPoint/point/issues"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "point": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cli": "./src/cli.ts",
+    "./core": "./src/core/index.ts"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env bun
+import { main } from "./core/cli.ts";
+
+main().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exit(1);
+});

package/src/core/ast.ts

@@ -0,0 +1,117 @@
+export type PointCorePrimitiveType = "Text" | "Int" | "Float" | "Bool" | "Void";
+
+export interface PointSourcePosition {
+	line: number;
+	column: number;
+	offset: number;
+}
+
+export interface PointSourceSpan {
+	start: PointSourcePosition;
+	end: PointSourcePosition;
+}
+
+export interface PointCoreProgram {
+	kind: "coreProgram";
+	module?: string;
+	declarations: PointCoreDeclaration[];
+	span?: PointSourceSpan;
+}
+
+export type PointCoreDeclaration =
+	| PointCoreImportDeclaration
+	| PointCoreValueDeclaration
+	| PointCoreFunctionDeclaration
+	| PointCoreTypeDeclaration;
+
+export interface PointCoreImportDeclaration {
+	kind: "import";
+	names: string[];
+	from: string;
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreValueDeclaration {
+	kind: "value";
+	name: string;
+	type: PointCoreTypeExpression;
+	value: PointCoreExpression;
+	mutable: boolean;
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreFunctionDeclaration {
+	kind: "function";
+	name: string;
+	params: PointCoreParameter[];
+	returnType: PointCoreTypeExpression;
+	body: PointCoreStatement[];
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreTypeDeclaration {
+	kind: "type";
+	name: string;
+	fields: PointCoreParameter[];
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreParameter {
+	name: string;
+	type: PointCoreTypeExpression;
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreTypeExpression {
+	kind: "typeRef";
+	name: PointCorePrimitiveType | string;
+	args: PointCoreTypeExpression[];
+	span?: PointSourceSpan;
+}
+
+export interface PointCoreRecordField {
+	name: string;
+	value: PointCoreExpression;
+	span?: PointSourceSpan;
+}
+
+export type PointCoreStatement =
+	| { kind: "return"; value?: PointCoreExpression; span?: PointSourceSpan }
+	| PointCoreValueDeclaration
+	| {
+			kind: "if";
+			condition: PointCoreExpression;
+			thenBody: PointCoreStatement[];
+			elseBody: PointCoreStatement[];
+			span?: PointSourceSpan;
+	  }
+	| { kind: "expression"; value: PointCoreExpression; span?: PointSourceSpan };
+
+export type PointCoreExpression =
+	| { kind: "literal"; value: string | number | boolean; 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: "binary";
+			operator: PointCoreBinaryOperator;
+			left: PointCoreExpression;
+			right: PointCoreExpression;
+			span?: PointSourceSpan;
+	  }
+	| { kind: "call"; callee: string; args: PointCoreExpression[]; span?: PointSourceSpan };
+
+export type PointCoreBinaryOperator =
+	| "+"
+	| "-"
+	| "*"
+	| "/"
+	| "=="
+	| "!="
+	| "<"
+	| "<="
+	| ">"
+	| ">="
+	| "and"
+	| "or";

package/src/core/check.ts

@@ -0,0 +1,442 @@
+import type {
+	PointCoreDeclaration,
+	PointCoreExpression,
+	PointCoreFunctionDeclaration,
+	PointCoreProgram,
+	PointCoreStatement,
+	PointCoreTypeDeclaration,
+	PointCoreTypeExpression,
+	PointCoreValueDeclaration,
+	PointSourceSpan,
+} from "./ast.ts";
+
+export interface PointCoreDiagnostic {
+	code: string;
+	message: string;
+	path: string;
+	ref: string;
+	severity: "error";
+	span: PointSourceSpan | null;
+	expected?: string | string[];
+	actual?: string;
+	repair?: string;
+	relatedRefs?: string[];
+}
+
+type DiagnosticMetadata = Partial<Pick<PointCoreDiagnostic, "expected" | "actual" | "repair" | "relatedRefs">>;
+
+const PRIMITIVE_TYPES = new Set(["Text", "Int", "Float", "Bool", "Void", "List"]);
+
+export function checkPointCore(program: PointCoreProgram): PointCoreDiagnostic[] {
+	const checker = new CoreChecker(program);
+	return checker.check();
+}
+
+class CoreChecker {
+	private readonly diagnostics: PointCoreDiagnostic[] = [];
+	private readonly types = new Set(PRIMITIVE_TYPES);
+	private readonly typeDeclarations = new Map<string, PointCoreTypeDeclaration>();
+	private readonly globals = new Map<string, PointCoreTypeExpression>();
+	private readonly functions = new Map<string, PointCoreFunctionDeclaration>();
+
+	constructor(private readonly program: PointCoreProgram) {}
+
+	check(): PointCoreDiagnostic[] {
+		this.collectDeclarations();
+		for (const declaration of this.program.declarations) this.checkDeclaration(declaration);
+		return this.diagnostics;
+	}
+
+	private collectDeclarations() {
+		for (const declaration of this.program.declarations) {
+			if (declaration.kind === "type") {
+				if (this.types.has(declaration.name)) {
+					this.push("duplicate-type", `Duplicate type ${declaration.name}`, `type.${declaration.name}`, declaration.span);
+				}
+				this.types.add(declaration.name);
+				this.typeDeclarations.set(declaration.name, declaration);
+			}
+			if (declaration.kind === "value") this.addGlobal(declaration);
+			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);
+			}
+		}
+	}
+
+	private addGlobal(declaration: PointCoreValueDeclaration) {
+		if (this.globals.has(declaration.name)) {
+			this.push("duplicate-value", `Duplicate value ${declaration.name}`, `value.${declaration.name}`, declaration.span);
+		}
+		this.globals.set(declaration.name, declaration.type);
+	}
+
+	private checkDeclaration(declaration: PointCoreDeclaration) {
+		if (declaration.kind === "import") return;
+		if (declaration.kind === "type") {
+			for (const field of declaration.fields) this.checkType(field.type, `type.${declaration.name}.${field.name}`);
+			return;
+		}
+		if (declaration.kind === "value") {
+			this.checkType(declaration.type, `value.${declaration.name}.type`);
+			this.checkExpressionAssignable(declaration.value, declaration.type, `value.${declaration.name}.value`, this.globals);
+			return;
+		}
+		this.checkFunction(declaration);
+	}
+
+	private checkFunction(declaration: PointCoreFunctionDeclaration) {
+		this.checkType(declaration.returnType, `fn.${declaration.name}.return`);
+		const locals = new Map(this.globals);
+		for (const param of declaration.params) {
+			this.checkType(param.type, `fn.${declaration.name}.${param.name}.type`);
+			locals.set(param.name, param.type);
+		}
+		for (const statement of declaration.body) {
+			this.checkStatement(statement, declaration, locals);
+		}
+	}
+
+	private checkStatement(
+		statement: PointCoreStatement,
+		fn: PointCoreFunctionDeclaration,
+		locals: Map<string, PointCoreTypeExpression>,
+	) {
+		if (statement.kind === "return") {
+			if (!statement.value) {
+				if (fn.returnType.name !== "Void") {
+					this.push("return-type-mismatch", `Function ${fn.name} must return ${fn.returnType.name}`, `fn.${fn.name}.return`, statement.span);
+				}
+				return;
+			}
+			this.checkExpressionAssignable(statement.value, fn.returnType, `fn.${fn.name}.return`, locals);
+			return;
+		}
+		if (statement.kind === "value") {
+			this.checkType(statement.type, `fn.${fn.name}.${statement.name}.type`);
+			this.checkExpressionAssignable(statement.value, statement.type, `fn.${fn.name}.${statement.name}.value`, locals);
+			locals.set(statement.name, statement.type);
+			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`);
+	}
+
+	private checkExpressionAssignable(
+		expression: PointCoreExpression,
+		expected: PointCoreTypeExpression,
+		path: string,
+		scope: Map<string, PointCoreTypeExpression>,
+	) {
+		if (expression.kind === "list") {
+			this.checkListAssignable(expression, expected, path, scope);
+			return;
+		}
+		if (expression.kind === "record") {
+			this.checkRecordAssignable(expression, expected, path, scope);
+			return;
+		}
+		const actual = this.typeOfExpression(expression, scope, path);
+		if (actual && !sameType(actual, expected)) {
+			this.push("type-mismatch", `Expected ${formatType(expected)}, got ${formatType(actual)}`, path, expression.span, {
+				expected: formatType(expected),
+				actual: formatType(actual),
+				repair: `Return or assign a ${formatType(expected)} value here.`,
+			});
+		}
+	}
+
+	private checkListAssignable(
+		expression: Extract<PointCoreExpression, { kind: "list" }>,
+		expected: PointCoreTypeExpression,
+		path: string,
+		scope: Map<string, PointCoreTypeExpression>,
+	) {
+		if (expected.name !== "List" || expected.args.length !== 1) {
+			this.push("type-mismatch", `Expected ${formatType(expected)}, got List`, path, expression.span, {
+				expected: formatType(expected),
+				actual: "List",
+				repair: `Annotate this value as List<T> or replace the list with a ${formatType(expected)} value.`,
+			});
+			return;
+		}
+		for (const [index, item] of expression.items.entries()) {
+			this.checkExpressionAssignable(item, expected.args[0]!, `${path}.${index}`, scope);
+		}
+	}
+
+	private checkRecordAssignable(
+		expression: Extract<PointCoreExpression, { kind: "record" }>,
+		expected: PointCoreTypeExpression,
+		path: string,
+		scope: Map<string, PointCoreTypeExpression>,
+	) {
+		const declaration = this.typeDeclarations.get(String(expected.name));
+		if (!declaration) {
+			this.push("type-mismatch", `Expected ${formatType(expected)}, got record`, path, expression.span, {
+				expected: formatType(expected),
+				actual: "record",
+				repair: "Assign record literals to a named type with declared fields.",
+			});
+			return;
+		}
+		const provided = new Map(expression.fields.map((field) => [field.name, field]));
+		for (const field of declaration.fields) {
+			const value = provided.get(field.name);
+			if (!value) {
+				this.push("missing-field", `Missing field ${field.name}`, `${path}.${field.name}`, expression.span, {
+					expected: declaration.fields.map((candidate) => candidate.name),
+					actual: [...provided.keys()].join(", "),
+					repair: `Add field ${field.name}: ${formatType(field.type)} to this record literal.`,
+					relatedRefs: this.fieldRefsFor(declaration),
+				});
+				continue;
+			}
+			this.checkExpressionAssignable(value.value, field.type, `${path}.${field.name}`, scope);
+			provided.delete(field.name);
+		}
+		for (const extra of provided.values()) {
+			this.push("unknown-field", `Unknown field ${extra.name}`, `${path}.${extra.name}`, extra.span, {
+				expected: declaration.fields.map((field) => field.name),
+				actual: extra.name,
+				repair: `Use one of: ${declaration.fields.map((field) => field.name).join(", ")}.`,
+				relatedRefs: this.fieldRefsFor(declaration),
+			});
+		}
+	}
+
+	private typeOfExpression(
+		expression: PointCoreExpression,
+		scope: Map<string, PointCoreTypeExpression>,
+		path: string,
+	): PointCoreTypeExpression | null {
+		if (expression.kind === "literal") {
+			const valueType =
+				typeof expression.value === "string"
+					? "Text"
+					: typeof expression.value === "boolean"
+						? "Bool"
+						: Number.isInteger(expression.value)
+							? "Int"
+							: "Float";
+			return { kind: "typeRef", name: valueType, args: [], span: expression.span };
+		}
+		if (expression.kind === "list") return this.typeOfListExpression(expression, scope, path);
+		if (expression.kind === "record") {
+			this.push("record-type-required", "Record literals require an expected named type", path, expression.span);
+			return null;
+		}
+		if (expression.kind === "identifier") {
+			const type = scope.get(expression.name);
+			if (!type) {
+				this.push("unknown-identifier", `Unknown identifier ${expression.name}`, path, expression.span, {
+					actual: expression.name,
+					repair: `Declare ${expression.name}, pass it as a parameter, or replace it with an in-scope symbol.`,
+				});
+				return null;
+			}
+			return type;
+		}
+		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) {
+			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`,
+				repair: `Call ${expression.callee} with ${target.params.length} argument(s).`,
+				relatedRefs: [this.refFor(`fn.${target.name}`)],
+			});
+		}
+		for (const [index, arg] of expression.args.entries()) {
+			const param = target.params[index];
+			if (param) this.checkExpressionAssignable(arg, param.type, `${path}.arg${index}`, scope);
+		}
+		return target.returnType;
+	}
+
+	private typeOfListExpression(
+		expression: Extract<PointCoreExpression, { kind: "list" }>,
+		scope: Map<string, PointCoreTypeExpression>,
+		path: string,
+	): PointCoreTypeExpression | null {
+		if (expression.items.length === 0) {
+			this.push("list-type-required", "Empty lists require an expected List type", path, expression.span);
+			return null;
+		}
+		const first = this.typeOfExpression(expression.items[0]!, scope, `${path}.0`);
+		if (!first) return null;
+		for (const [index, item] of expression.items.slice(1).entries()) {
+			const actual = this.typeOfExpression(item, scope, `${path}.${index + 1}`);
+			if (actual && !sameType(actual, first)) {
+				this.push("type-mismatch", `Expected ${formatType(first)}, got ${formatType(actual)}`, `${path}.${index + 1}`, item.span);
+			}
+		}
+		return { kind: "typeRef", name: "List", args: [first], span: expression.span };
+	}
+
+	private typeOfPropertyExpression(
+		expression: Extract<PointCoreExpression, { kind: "property" }>,
+		scope: Map<string, PointCoreTypeExpression>,
+		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));
+		if (!declaration) {
+			this.push("not-a-record", `${formatType(targetType)} has no fields`, path, expression.span, {
+				actual: formatType(targetType),
+				repair: "Only access fields on named record types.",
+			});
+			return null;
+		}
+		const field = declaration.fields.find((candidate) => candidate.name === expression.name);
+		if (!field) {
+			this.push("unknown-field", `Unknown field ${expression.name} on ${targetType.name}`, path, expression.span, {
+				expected: declaration.fields.map((candidate) => candidate.name),
+				actual: expression.name,
+				repair: `Use one of: ${declaration.fields.map((candidate) => candidate.name).join(", ")}.`,
+				relatedRefs: this.fieldRefsFor(declaration),
+			});
+			return null;
+		}
+		return field.type;
+	}
+
+	private typeOfBinaryExpression(
+		expression: Extract<PointCoreExpression, { kind: "binary" }>,
+		scope: Map<string, PointCoreTypeExpression>,
+		path: string,
+	): PointCoreTypeExpression | null {
+		const left = this.typeOfExpression(expression.left, scope, `${path}.left`);
+		const right = this.typeOfExpression(expression.right, scope, `${path}.right`);
+		if (!left || !right) return null;
+		if (expression.operator === "and" || expression.operator === "or") {
+			if (left.name !== "Bool" || right.name !== "Bool") {
+				this.push("operator-type-mismatch", `${expression.operator} requires Bool operands`, path, expression.span, {
+					expected: "Bool operands",
+					actual: `${formatType(left)} and ${formatType(right)}`,
+					repair: `Use Bool expressions on both sides of ${expression.operator}.`,
+				});
+			}
+			return { kind: "typeRef", name: "Bool", args: [], span: expression.span };
+		}
+		if (expression.operator === "==" || expression.operator === "!=") {
+			if (left.name !== right.name) {
+				this.push("operator-type-mismatch", `${expression.operator} requires matching operand types`, path, expression.span, {
+					expected: formatType(left),
+					actual: formatType(right),
+					repair: "Compare values with the same Point type.",
+				});
+			}
+			return { kind: "typeRef", name: "Bool", args: [], span: expression.span };
+		}
+		if (expression.operator === "+" && left.name === "Text" && right.name === "Text") {
+			return { kind: "typeRef", name: "Text", args: [], span: expression.span };
+		}
+		if (!isNumeric(left.name) || !isNumeric(right.name)) {
+			this.push("operator-type-mismatch", `${expression.operator} requires numeric operands`, path, expression.span, {
+				expected: "Int or Float operands",
+				actual: `${formatType(left)} and ${formatType(right)}`,
+				repair: `Use numeric expressions on both sides of ${expression.operator}.`,
+			});
+			return null;
+		}
+		if (["<", "<=", ">", ">="].includes(expression.operator)) {
+			return { kind: "typeRef", name: "Bool", args: [], span: expression.span };
+		}
+		return { kind: "typeRef", name: left.name === "Float" || right.name === "Float" ? "Float" : "Int", args: [], span: expression.span };
+	}
+
+	private checkType(type: PointCoreTypeExpression, path: string) {
+		if (!this.types.has(type.name)) {
+			this.push("unknown-type", `Unknown type ${type.name}`, path, type.span, {
+				expected: [...this.types].sort(),
+				actual: String(type.name),
+				repair: `Declare type ${type.name} or use an existing type.`,
+			});
+		}
+		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))) {
+			this.push("invalid-type-arity", `${type.name} does not accept type arguments`, path, type.span, {
+				expected: String(type.name),
+				actual: formatType(type),
+				repair: `Remove type arguments from ${type.name}.`,
+			});
+		}
+		for (const arg of type.args) this.checkType(arg, `${path}.arg`);
+	}
+
+	private push(
+		code: string,
+		message: string,
+		path: string,
+		span: PointSourceSpan | undefined,
+		metadata: DiagnosticMetadata = {},
+	) {
+		this.diagnostics.push({
+			code,
+			message,
+			path,
+			ref: this.refFor(path),
+			severity: "error",
+			span: span ?? null,
+			...metadata,
+		});
+	}
+
+	private refFor(path: string): string {
+		return `point://core/${this.program.module ?? "anonymous"}/${path}`;
+	}
+
+	private fieldRefsFor(declaration: PointCoreTypeDeclaration): string[] {
+		return declaration.fields.map((field) => this.refFor(`type.${declaration.name}.${field.name}`));
+	}
+}
+
+function isNumeric(type: string): boolean {
+	return type === "Int" || type === "Float";
+}
+
+function sameType(left: PointCoreTypeExpression, right: PointCoreTypeExpression): boolean {
+	const leftArgs = left.args ?? [];
+	const rightArgs = right.args ?? [];
+	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 typeRef(name: string, args: PointCoreTypeExpression[] = [], span?: PointSourceSpan): PointCoreTypeExpression {
+	return { kind: "typeRef", name, args, span };
+}