@seljs/checker 1.0.0 → 1.0.1-beta.9

package/dist/checker/checker.d.mts

@@ -0,0 +1,176 @@
+import { SELRule } from "../rules/types.mjs";
+import { SELSchema } from "@seljs/schema";
+
+//#region src/checker/checker.d.ts
+interface SELCheckResult {
+  valid: boolean;
+  type?: string;
+  diagnostics: SELDiagnostic[];
+}
+interface TypeAtResult {
+  type: string;
+  from: number;
+  to: number;
+}
+interface ExpectedTypeInfo {
+  /**
+   * The CEL type expected at this position.
+   */
+  expectedType: string;
+  /**
+   * How the expectation was inferred.
+   */
+  context: "operator" | "function-argument";
+  /**
+   * For function args: which parameter index.
+   */
+  paramIndex?: number;
+  /**
+   * For function args: the function/method name.
+   */
+  functionName?: string;
+}
+interface CompletionInfo {
+  kind: "top-level" | "dot-access" | "explicit";
+  receiverType?: string;
+  items: CompletionItem[];
+  /**
+   * Inferred expected type at cursor, if determinable.
+   */
+  expectedType?: string;
+}
+interface CompletionItem {
+  label: string;
+  type: string;
+  detail?: string;
+  description?: string;
+}
+/**
+ * A diagnostic message with optional position info. Used for both parse/type errors
+ * and rule violations. Positions are optional because some errors (e.g. from cel-js)
+ * may not include reliable spans, and rules may choose to report non-positional issues.
+ */
+interface SELDiagnostic {
+  message: string;
+  severity: "error" | "warning" | "info";
+  from?: number;
+  to?: number;
+}
+/**
+ * Options for configuring the SELChecker.
+ */
+interface SELCheckerOptions {
+  /**
+   * Lint rules to enable. Defaults to none (backward compatible).
+   */
+  rules?: readonly SELRule[];
+}
+/**
+ * SEL expression checker.
+ *
+ * Wraps a hydrated cel-js Environment built from a SELSchema and exposes
+ * parse/type-check, type inference, cursor-position type lookups, and
+ * type-aware completions.
+ */
+declare class SELChecker {
+  private readonly rules;
+  private env;
+  private schema;
+  private structTypeMap;
+  constructor(schema: SELSchema, options?: SELCheckerOptions);
+  /**
+   * Parse and type-check an expression, returning position-aware diagnostics.
+   *
+   * Uses a single `env.parse()` call, then `.check()` on the result
+   * to avoid double-parsing. Rules run against the AST from the same parse:
+   * - Structural rules run after successful parse (even if type-check fails)
+   * - Type-aware rules run only after both parse and type-check succeed
+   */
+  check(expression: string): SELCheckResult;
+  /**
+   * Get the inferred CEL type of the full expression.
+   * Returns undefined if the expression is invalid.
+   */
+  typeOf(expression: string): string | undefined;
+  /**
+   * Get the inferred type at a cursor position (for hover info).
+   *
+   * Attempts to identify the sub-expression under the cursor and infer its
+   * type. Falls back to the full expression type when sub-expression
+   * isolation is not possible.
+   */
+  typeAt(expression: string, offset: number): TypeAtResult | undefined;
+  /**
+   * Get type-aware completions for a cursor context.
+   *
+   * Supports:
+   * - **dot-access**: after `contract.` — lists methods of that contract
+   * - **top-level**: at the start or after operators — lists variables,
+   *   contracts, and functions
+   */
+  completionsAt(expression: string, offset: number): CompletionInfo;
+  /**
+   * Infer the expected type at a cursor position from surrounding context.
+   *
+   * Supports two contexts:
+   * - **Operator**: `expr > |` — infers the left operand type and derives the
+   *   expected right operand type from the operator.
+   * - **Function argument**: `contract.method(arg, |)` — looks up the
+   *   parameter type from the schema.
+   *
+   * Returns undefined when context cannot be determined, signaling that
+   * no narrowing should occur (safe fallback).
+   */
+  expectedTypeAt(expression: string, offset: number): ExpectedTypeInfo | undefined;
+  /**
+   * Resolve type and available members for a dot-access receiver expression.
+   */
+  dotCompletions(receiverExpression: string): CompletionInfo;
+  /**
+   * Resolve expected type from a structured context.
+   */
+  expectedTypeFor(context: {
+    kind: "operator";
+    leftExpression: string;
+    operator: string;
+  } | {
+    kind: "function-arg";
+    receiverName?: string;
+    functionName: string;
+    paramIndex: number;
+  }): string | undefined;
+  /**
+   * Rebuild the internal environment from an updated schema.
+   */
+  updateSchema(schema: SELSchema): void;
+  private buildStructTypeMap;
+  private structFieldsFor;
+  /**
+   * Scan backwards from a dot position to extract the receiver expression.
+   * Handles balanced parentheses so that `foo(erc20.name().` correctly
+   * identifies `erc20.name()` as the receiver, not `foo(erc20.name()`.
+   */
+  private extractReceiverBefore;
+  /**
+   * Find the largest call/dot-access chain node that contains the offset.
+   */
+  private findContainingChain;
+  /**
+   * Scan backwards from the end of text to find a trailing binary operator.
+   * Tries multi-character operators first (==, !=, etc.) to avoid partial matches.
+   */
+  private findTrailingOperator;
+  /**
+   * Find the enclosing function/method call around the cursor by scanning
+   * backwards for an unclosed `(`, then extracting the function name and
+   * counting commas to determine the parameter index.
+   */
+  private findEnclosingCall;
+  /**
+   * Look up the expected parameter type from the schema for a function or
+   * method call at the given parameter index.
+   */
+  private resolveRawParamType;
+}
+//#endregion
+export { CompletionItem, SELChecker, SELCheckerOptions, SELDiagnostic };

package/dist/checker/checker.mjs

@@ -0,0 +1,481 @@
+import { extractDiagnostics } from "./diagnostics.mjs";
+import { expectedTypeForOperator } from "./type-compatibility.mjs";
+import { createCheckerEnvironment } from "../environment/hydrate.mjs";
+import { findNodeWithParentAt, nodeSpan, walkAST } from "../utils/ast-utils.mjs";
+import { runRules } from "../rules/runner.mjs";
+import "../rules/index.mjs";
+import { contractTypeName } from "@seljs/common";
+//#region src/checker/checker.ts
+/**
+* SEL expression checker.
+*
+* Wraps a hydrated cel-js Environment built from a SELSchema and exposes
+* parse/type-check, type inference, cursor-position type lookups, and
+* type-aware completions.
+*/
+var SELChecker = class {
+	rules;
+	env;
+	schema;
+	structTypeMap;
+	constructor(schema, options) {
+		this.schema = schema;
+		this.env = createCheckerEnvironment(schema);
+		this.rules = options?.rules ?? [];
+		this.structTypeMap = this.buildStructTypeMap(schema);
+	}
+	/**
+	* Parse and type-check an expression, returning position-aware diagnostics.
+	*
+	* Uses a single `env.parse()` call, then `.check()` on the result
+	* to avoid double-parsing. Rules run against the AST from the same parse:
+	* - Structural rules run after successful parse (even if type-check fails)
+	* - Type-aware rules run only after both parse and type-check succeed
+	*/
+	check(expression) {
+		let parsed;
+		try {
+			parsed = this.env.parse(expression);
+		} catch (error) {
+			return {
+				valid: false,
+				diagnostics: extractDiagnostics(expression, error)
+			};
+		}
+		const structuralDiags = this.rules.length > 0 ? runRules({
+			expression,
+			ast: parsed.ast,
+			schema: this.schema,
+			rules: this.rules,
+			tier: "structural"
+		}) : [];
+		let typeResult;
+		try {
+			typeResult = parsed.check();
+		} catch (error) {
+			return {
+				valid: false,
+				diagnostics: [...extractDiagnostics(expression, error), ...structuralDiags]
+			};
+		}
+		if (!typeResult.valid) return {
+			valid: false,
+			diagnostics: [...typeResult.error ? extractDiagnostics(expression, typeResult.error) : [{
+				message: "Type check failed",
+				severity: "error",
+				from: 0,
+				to: expression.length
+			}], ...structuralDiags]
+		};
+		const typeAwareDiags = this.rules.length > 0 ? runRules({
+			expression,
+			ast: parsed.ast,
+			schema: this.schema,
+			rules: this.rules,
+			tier: "type-aware",
+			resolvedType: typeResult.type
+		}) : [];
+		const allRuleDiags = [...structuralDiags, ...typeAwareDiags];
+		return {
+			valid: !allRuleDiags.some((d) => d.severity === "error"),
+			type: typeResult.type,
+			diagnostics: allRuleDiags
+		};
+	}
+	/**
+	* Get the inferred CEL type of the full expression.
+	* Returns undefined if the expression is invalid.
+	*/
+	typeOf(expression) {
+		return this.check(expression).type;
+	}
+	/**
+	* Get the inferred type at a cursor position (for hover info).
+	*
+	* Attempts to identify the sub-expression under the cursor and infer its
+	* type. Falls back to the full expression type when sub-expression
+	* isolation is not possible.
+	*/
+	typeAt(expression, offset) {
+		if (offset < 0 || offset > expression.length) return;
+		let parsed;
+		try {
+			parsed = this.env.parse(expression);
+		} catch {
+			return;
+		}
+		const hit = findNodeWithParentAt(parsed.ast, offset);
+		if (!hit) {
+			const fullType = this.typeOf(expression);
+			return fullType ? {
+				type: fullType,
+				from: 0,
+				to: expression.length
+			} : void 0;
+		}
+		const { node } = hit;
+		if (node.op === "id") {
+			const name = node.args;
+			const span = nodeSpan(node);
+			const variable = this.schema.variables.find((v) => v.name === name);
+			if (variable) return {
+				type: variable.type,
+				from: span.from,
+				to: span.to
+			};
+			const contract = this.schema.contracts.find((c) => c.name === name);
+			if (contract) return {
+				type: contractTypeName(contract.name),
+				from: span.from,
+				to: span.to
+			};
+		}
+		const chainNode = this.findContainingChain(parsed.ast, offset);
+		if (chainNode) {
+			const chainSpan = nodeSpan(chainNode);
+			const chainExpr = expression.slice(chainSpan.from, chainSpan.to);
+			const chainType = this.typeOf(chainExpr);
+			if (chainType) return {
+				type: chainType,
+				from: chainSpan.from,
+				to: chainSpan.to
+			};
+		}
+		const fullType = this.typeOf(expression);
+		return fullType ? {
+			type: fullType,
+			from: 0,
+			to: expression.length
+		} : void 0;
+	}
+	/**
+	* Get type-aware completions for a cursor context.
+	*
+	* Supports:
+	* - **dot-access**: after `contract.` — lists methods of that contract
+	* - **top-level**: at the start or after operators — lists variables,
+	*   contracts, and functions
+	*/
+	completionsAt(expression, offset) {
+		const beforeCursor = expression.slice(0, offset);
+		const lastDotIdx = beforeCursor.lastIndexOf(".");
+		if (lastDotIdx > 0) {
+			const receiverExpr = this.extractReceiverBefore(beforeCursor, lastDotIdx);
+			if (receiverExpr) return this.dotCompletions(receiverExpr);
+		}
+		const items = [];
+		for (const variable of this.schema.variables) items.push({
+			label: variable.name,
+			type: variable.type,
+			description: variable.description
+		});
+		for (const contract of this.schema.contracts) items.push({
+			label: contract.name,
+			type: contractTypeName(contract.name),
+			description: contract.description
+		});
+		for (const fn of this.schema.functions) if (!fn.receiverType) items.push({
+			label: fn.name,
+			type: fn.returns,
+			detail: fn.signature,
+			description: fn.description
+		});
+		return {
+			kind: "top-level",
+			expectedType: this.expectedTypeAt(expression, offset)?.expectedType,
+			items
+		};
+	}
+	/**
+	* Infer the expected type at a cursor position from surrounding context.
+	*
+	* Supports two contexts:
+	* - **Operator**: `expr > |` — infers the left operand type and derives the
+	*   expected right operand type from the operator.
+	* - **Function argument**: `contract.method(arg, |)` — looks up the
+	*   parameter type from the schema.
+	*
+	* Returns undefined when context cannot be determined, signaling that
+	* no narrowing should occur (safe fallback).
+	*/
+	expectedTypeAt(expression, offset) {
+		const beforeCursor = expression.slice(0, offset);
+		const trailing = this.findTrailingOperator(beforeCursor);
+		if (trailing) {
+			const expected = this.expectedTypeFor({
+				kind: "operator",
+				leftExpression: trailing.leftExpr,
+				operator: trailing.operator
+			});
+			if (expected) return {
+				expectedType: expected,
+				context: "operator"
+			};
+		}
+		const callInfo = this.findEnclosingCall(expression, offset);
+		if (callInfo) {
+			const expected = this.expectedTypeFor({
+				kind: "function-arg",
+				receiverName: callInfo.receiverName,
+				functionName: callInfo.functionName,
+				paramIndex: callInfo.paramIndex
+			});
+			if (expected) return {
+				expectedType: expected,
+				context: "function-argument",
+				paramIndex: callInfo.paramIndex,
+				functionName: callInfo.functionName
+			};
+		}
+	}
+	/**
+	* Resolve type and available members for a dot-access receiver expression.
+	*/
+	dotCompletions(receiverExpression) {
+		const contract = this.schema.contracts.find((c) => c.name === receiverExpression);
+		if (contract) return {
+			kind: "dot-access",
+			receiverType: contractTypeName(contract.name),
+			items: contract.methods.map((method) => ({
+				label: method.name,
+				type: method.returns,
+				detail: `(${method.params.map((p) => `${p.name}: ${p.type}`).join(", ")}): ${method.returns}`,
+				description: method.description
+			}))
+		};
+		const receiverType = this.typeOf(receiverExpression);
+		if (receiverType) {
+			const contractByType = this.schema.contracts.find((c) => contractTypeName(c.name) === receiverType);
+			if (contractByType) return {
+				kind: "dot-access",
+				receiverType,
+				items: contractByType.methods.map((m) => ({
+					label: m.name,
+					type: m.returns,
+					detail: `(${m.params.map((p) => `${p.name}: ${p.type}`).join(", ")}): ${m.returns}`,
+					description: m.description
+				}))
+			};
+			const baseType = receiverType.includes("<") ? receiverType.slice(0, receiverType.indexOf("<")) : null;
+			const receiverMethods = this.schema.functions.filter((f) => f.receiverType === receiverType || baseType !== null && f.receiverType === baseType).map((f) => ({
+				label: f.name,
+				type: f.returns,
+				detail: f.signature,
+				description: f.description
+			}));
+			if (baseType === "list" || receiverType === "list") {
+				const macroItems = this.schema.macros.filter((m) => m.pattern.startsWith("list.")).map((m) => ({
+					label: m.name,
+					type: "",
+					detail: m.pattern,
+					description: m.description
+				}));
+				const seen = new Set(receiverMethods.map((m) => m.label));
+				for (const item of macroItems) if (!seen.has(item.label)) {
+					receiverMethods.push(item);
+					seen.add(item.label);
+				}
+			}
+			if (receiverMethods.length > 0) return {
+				kind: "dot-access",
+				receiverType,
+				items: receiverMethods
+			};
+			const structItems = this.structFieldsFor(receiverType);
+			if (structItems) return {
+				kind: "dot-access",
+				receiverType,
+				items: structItems
+			};
+			return {
+				kind: "dot-access",
+				receiverType,
+				items: []
+			};
+		}
+		return {
+			kind: "dot-access",
+			receiverType: receiverExpression,
+			items: []
+		};
+	}
+	/**
+	* Resolve expected type from a structured context.
+	*/
+	expectedTypeFor(context) {
+		if (context.kind === "operator") {
+			const leftType = this.typeOf(context.leftExpression);
+			if (leftType) return expectedTypeForOperator(leftType, context.operator) ?? void 0;
+			return;
+		}
+		const rawType = this.resolveRawParamType(context.receiverName, context.functionName, context.paramIndex);
+		if (rawType && !rawType.includes("|")) return rawType;
+	}
+	/**
+	* Rebuild the internal environment from an updated schema.
+	*/
+	updateSchema(schema) {
+		this.schema = schema;
+		this.env = createCheckerEnvironment(schema);
+		this.structTypeMap = this.buildStructTypeMap(schema);
+	}
+	buildStructTypeMap(schema) {
+		const map = /* @__PURE__ */ new Map();
+		for (const type of schema.types) if (type.kind === "struct") map.set(type.name, type);
+		return map;
+	}
+	structFieldsFor(typeName) {
+		const structType = this.structTypeMap.get(typeName);
+		if (!structType) return;
+		return (structType.fields ?? []).map((field) => ({
+			label: field.name,
+			type: field.type,
+			detail: field.type,
+			description: field.description
+		}));
+	}
+	/**
+	* Scan backwards from a dot position to extract the receiver expression.
+	* Handles balanced parentheses so that `foo(erc20.name().` correctly
+	* identifies `erc20.name()` as the receiver, not `foo(erc20.name()`.
+	*/
+	extractReceiverBefore(text, dotIdx) {
+		let i = dotIdx - 1;
+		while (i >= 0 && (text[i] === " " || text[i] === "	")) i--;
+		if (i < 0) return "";
+		const isIdentStart = (code) => code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95;
+		const isIdentChar = (code) => isIdentStart(code) || code >= 48 && code <= 57;
+		const collectChain = () => {
+			if (text[i] === ")") {
+				const closePos = i;
+				let depth = 1;
+				i--;
+				while (i >= 0 && depth > 0) {
+					const ch = text[i];
+					if (ch === ")") depth++;
+					else if (ch === "(") depth--;
+					if (depth > 0) i--;
+				}
+				if (depth !== 0) {
+					i = closePos;
+					return;
+				}
+				i--;
+			}
+			if (i >= 0 && isIdentChar(text.charCodeAt(i))) {
+				while (i >= 0 && isIdentChar(text.charCodeAt(i))) i--;
+				const start = i + 1;
+				if (!isIdentStart(text.charCodeAt(start))) return;
+				if (i >= 0 && text[i] === ".") {
+					i--;
+					collectChain();
+				}
+			}
+		};
+		collectChain();
+		const start = i + 1;
+		return text.slice(start, dotIdx).trimEnd();
+	}
+	/**
+	* Find the largest call/dot-access chain node that contains the offset.
+	*/
+	findContainingChain(root, offset) {
+		let best;
+		walkAST(root, (node) => {
+			if (node.op !== "." && node.op !== ".?" && node.op !== "rcall") return;
+			const span = nodeSpan(node);
+			if (offset >= span.from && offset <= span.to) {
+				if (!best || span.to - span.from > nodeSpan(best).to - nodeSpan(best).from) best = node;
+			}
+		});
+		return best;
+	}
+	/**
+	* Scan backwards from the end of text to find a trailing binary operator.
+	* Tries multi-character operators first (==, !=, etc.) to avoid partial matches.
+	*/
+	findTrailingOperator(text) {
+		const trimmed = text.trimEnd();
+		for (const op of [
+			"==",
+			"!=",
+			">=",
+			"<=",
+			"&&",
+			"||",
+			"in"
+		]) if (trimmed.endsWith(op)) {
+			const left = trimmed.slice(0, -op.length).trimEnd();
+			if (left) return {
+				leftExpr: left,
+				operator: op
+			};
+		}
+		for (const op of [
+			">",
+			"<",
+			"+",
+			"-",
+			"*",
+			"/",
+			"%"
+		]) if (trimmed.endsWith(op)) {
+			const before = trimmed.slice(0, -1);
+			const lastChar = before.at(-1);
+			if (lastChar === ">" || lastChar === "<" || lastChar === "=" || lastChar === "!" || lastChar === "&" || lastChar === "|") continue;
+			const left = before.trimEnd();
+			if (left) return {
+				leftExpr: left,
+				operator: op
+			};
+		}
+	}
+	/**
+	* Find the enclosing function/method call around the cursor by scanning
+	* backwards for an unclosed `(`, then extracting the function name and
+	* counting commas to determine the parameter index.
+	*/
+	findEnclosingCall(expression, offset) {
+		let depth = 0;
+		let commas = 0;
+		let parenPos = -1;
+		for (let i = offset - 1; i >= 0; i--) {
+			const ch = expression[i];
+			if (ch === ")") depth++;
+			else if (ch === "(") {
+				if (depth === 0) {
+					parenPos = i;
+					break;
+				}
+				depth--;
+			} else if (ch === "," && depth === 0) commas++;
+		}
+		if (parenPos < 0) return;
+		const beforeParen = expression.slice(0, parenPos);
+		const callMatch = /(?:(\w+)\.)?(\w+)\s*$/.exec(beforeParen);
+		if (!callMatch?.[2]) return;
+		return {
+			receiverName: callMatch[1],
+			functionName: callMatch[2],
+			paramIndex: commas
+		};
+	}
+	/**
+	* Look up the expected parameter type from the schema for a function or
+	* method call at the given parameter index.
+	*/
+	resolveRawParamType(receiverName, functionName, paramIndex) {
+		if (receiverName) {
+			const contract = this.schema.contracts.find((c) => c.name === receiverName);
+			if (contract) {
+				const method = contract.methods.find((m) => m.name === functionName);
+				if (method && paramIndex < method.params.length) return method.params[paramIndex].type;
+			}
+		} else {
+			const fn = this.schema.functions.find((f) => f.name === functionName);
+			if (fn && paramIndex < fn.params.length) return fn.params[paramIndex].type;
+		}
+	}
+};
+//#endregion
+export { SELChecker };