@seljs/checker 1.0.0

package/dist/checker/checker.js

@@ -0,0 +1,567 @@
+import { contractTypeName } from "@seljs/common";
+import { extractDiagnostics } from "./diagnostics.js";
+import { expectedTypeForOperator } from "./type-compatibility.js";
+import { createCheckerEnvironment } from "../environment/hydrate.js";
+import { runRules } from "../rules/index.js";
+import { findNodeWithParentAt, nodeSpan, walkAST } from "../utils/index.js";
+/**
+ * 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.
+ */
+export class SELChecker {
+    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) {
+            // Parse error — no AST available, no rules can run
+            return {
+                valid: false,
+                diagnostics: extractDiagnostics(expression, error),
+            };
+        }
+        // Run structural rules (these run regardless of type-check result)
+        const structuralDiags = this.rules.length > 0
+            ? runRules({
+                expression,
+                ast: parsed.ast,
+                schema: this.schema,
+                rules: this.rules,
+                tier: "structural",
+            })
+            : [];
+        // Type-check using the same parse result (no second parse)
+        let typeResult;
+        try {
+            typeResult = parsed.check();
+        }
+        catch (error) {
+            return {
+                valid: false,
+                diagnostics: [
+                    ...extractDiagnostics(expression, error),
+                    ...structuralDiags,
+                ],
+            };
+        }
+        if (!typeResult.valid) {
+            const typeDiags = typeResult.error
+                ? extractDiagnostics(expression, typeResult.error)
+                : [
+                    {
+                        message: "Type check failed",
+                        severity: "error",
+                        from: 0,
+                        to: expression.length,
+                    },
+                ];
+            return {
+                valid: false,
+                diagnostics: [...typeDiags, ...structuralDiags],
+            };
+        }
+        // Run type-aware rules (only on fully valid expressions)
+        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];
+        const hasRuleError = allRuleDiags.some((d) => d.severity === "error");
+        return {
+            valid: !hasRuleError,
+            type: typeResult.type,
+            diagnostics: allRuleDiags,
+        };
+    }
+    /**
+     * Get the inferred CEL type of the full expression.
+     * Returns undefined if the expression is invalid.
+     */
+    typeOf(expression) {
+        const result = this.check(expression);
+        return result.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 undefined;
+        }
+        let parsed;
+        try {
+            parsed = this.env.parse(expression);
+        }
+        catch {
+            return undefined;
+        }
+        const hit = findNodeWithParentAt(parsed.ast, offset);
+        if (!hit) {
+            const fullType = this.typeOf(expression);
+            return fullType
+                ? { type: fullType, from: 0, to: expression.length }
+                : undefined;
+        }
+        const { node } = hit;
+        // Identifier: variable or contract name
+        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,
+                };
+            }
+        }
+        // Find largest dot-access/call chain containing this offset
+        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 };
+            }
+        }
+        // Fall back to full expression type
+        const fullType = this.typeOf(expression);
+        return fullType
+            ? { type: fullType, from: 0, to: expression.length }
+            : 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, 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);
+            }
+        }
+        // Top-level completions
+        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,
+                });
+            }
+        }
+        const expected = this.expectedTypeAt(expression, offset);
+        return { kind: "top-level", expectedType: expected?.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);
+        // Phase A: Operator context
+        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" };
+            }
+        }
+        // Phase B: Function argument context
+        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,
+                };
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Resolve type and available members for a dot-access receiver expression.
+     */
+    dotCompletions(receiverExpression) {
+        // Check direct contract name
+        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,
+                })),
+            };
+        }
+        // Type-check the receiver expression
+        const receiverType = this.typeOf(receiverExpression);
+        if (receiverType) {
+            // Check if it resolves to a contract type
+            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,
+                    })),
+                };
+            }
+            // Check for receiver methods matching this type
+            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,
+            }));
+            // Include list macros
+            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 };
+            }
+            // Check for struct field completions
+            const structItems = this.structFieldsFor(receiverType);
+            if (structItems) {
+                return { kind: "dot-access", receiverType, items: structItems };
+            }
+            // Known type but no methods found
+            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) ?? undefined;
+            }
+            return undefined;
+        }
+        // function-arg
+        const rawType = this.resolveRawParamType(context.receiverName, context.functionName, context.paramIndex);
+        // Skip union types
+        if (rawType && !rawType.includes("|")) {
+            return rawType;
+        }
+        return undefined;
+    }
+    /**
+     * 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 = 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 undefined;
+        }
+        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] === "\t")) {
+            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();
+        // Multi-character operators first
+        for (const op of ["==", "!=", ">=", "<=", "&&", "||", "in"]) {
+            if (trimmed.endsWith(op)) {
+                const left = trimmed.slice(0, -op.length).trimEnd();
+                if (left) {
+                    return { leftExpr: left, operator: op };
+                }
+            }
+        }
+        // Single-character operators
+        for (const op of [">", "<", "+", "-", "*", "/", "%"]) {
+            if (trimmed.endsWith(op)) {
+                const before = trimmed.slice(0, -1);
+                // Guard against partial multi-char operators (>=, <=, ==, !=, &&, ||)
+                const lastChar = before.at(-1);
+                if (lastChar === ">" ||
+                    lastChar === "<" ||
+                    lastChar === "=" ||
+                    lastChar === "!" ||
+                    lastChar === "&" ||
+                    lastChar === "|") {
+                    continue;
+                }
+                const left = before.trimEnd();
+                if (left) {
+                    return { leftExpr: left, operator: op };
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * 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 undefined;
+        }
+        const beforeParen = expression.slice(0, parenPos);
+        const callMatch = /(?:(\w+)\.)?(\w+)\s*$/.exec(beforeParen);
+        if (!callMatch?.[2]) {
+            return undefined;
+        }
+        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) {
+            // Method call: receiver.method(...)
+            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) {
+                    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounds checked above
+                    return method.params[paramIndex].type;
+                }
+            }
+        }
+        else {
+            // Free function: func(...)
+            const fn = this.schema.functions.find((f) => f.name === functionName);
+            if (fn && paramIndex < fn.params.length) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounds checked above
+                return fn.params[paramIndex].type;
+            }
+        }
+        return undefined;
+    }
+}

package/dist/checker/diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { SELDiagnostic } from "./checker.js";
+/**
+ * Convert a cel-js error into position-aware SEL diagnostics.
+ *
+ * The error's `name` property distinguishes parse errors (`"ParseError"`)
+ * from type errors (`"TypeError"`).  Position information is extracted from
+ * the caret annotation embedded in the error message; when absent the
+ * diagnostic spans the entire expression.
+ */
+export declare const extractDiagnostics: (expression: string, error: unknown) => SELDiagnostic[];

package/dist/checker/diagnostics.js

@@ -0,0 +1,80 @@
+/**
+ * Extract position information from a cel-js error message.
+ *
+ * cel-js error messages embed a caret (`^`) on a separate line indicating
+ * the error column. The format is:
+ * ```
+ * Error description
+ *
+ * >    1 | expression text
+ *              ^
+ * ```
+ *
+ * We parse the caret offset relative to the code line prefix (`>    N | `)
+ * to derive the zero-based character offset within the expression.
+ */
+const extractPositionFromMessage = (message) => {
+    const lines = message.split("\n");
+    const caretLine = lines.find((line) => /^\s*\^+\s*$/.test(line));
+    if (!caretLine) {
+        return undefined;
+    }
+    const codeLine = lines.find((line) => line.startsWith(">"));
+    if (!codeLine) {
+        return undefined;
+    }
+    const pipeIndex = codeLine.indexOf("|");
+    if (pipeIndex === -1) {
+        return undefined;
+    }
+    // Prefix length includes the pipe and the space after it: ">    1 | "
+    const prefixLength = pipeIndex + 2;
+    const caretStart = caretLine.indexOf("^");
+    const caretEnd = caretLine.lastIndexOf("^");
+    const from = caretStart - prefixLength;
+    const to = caretEnd - prefixLength + 1;
+    if (from < 0) {
+        return undefined;
+    }
+    return { from, to };
+};
+/**
+ * Extract the plain error message without the caret/code-line decoration.
+ */
+const extractPlainMessage = (message) => {
+    const lines = message.split("\n");
+    const plainLines = lines.filter((line) => !line.startsWith(">") &&
+        !/^\s*\^+\s*$/.test(line) &&
+        line.trim().length > 0);
+    return plainLines.join(" ").trim() || message;
+};
+/**
+ * Convert a cel-js error into position-aware SEL diagnostics.
+ *
+ * The error's `name` property distinguishes parse errors (`"ParseError"`)
+ * from type errors (`"TypeError"`).  Position information is extracted from
+ * the caret annotation embedded in the error message; when absent the
+ * diagnostic spans the entire expression.
+ */
+export const extractDiagnostics = (expression, error) => {
+    if (!(error instanceof Error)) {
+        return [
+            {
+                message: String(error),
+                severity: "error",
+                from: 0,
+                to: expression.length,
+            },
+        ];
+    }
+    const position = extractPositionFromMessage(error.message);
+    const message = extractPlainMessage(error.message);
+    return [
+        {
+            message,
+            severity: "error",
+            from: position?.from ?? 0,
+            to: position?.to ?? expression.length,
+        },
+    ];
+};

package/dist/checker/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./checker.js";
+export { isTypeCompatible } from "./type-compatibility.js";

package/dist/checker/index.js

@@ -0,0 +1,2 @@
+export * from "./checker.js";
+export { isTypeCompatible } from "./type-compatibility.js";

package/dist/checker/type-compatibility.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Given the type of the left operand and the operator,
+ * returns the expected type for the right operand.
+ *
+ * Based on the registered operators in register-types.ts.
+ * Type compatibility is strictly same-type (no implicit coercion).
+ *
+ * Returns undefined when the type/operator combination is unknown,
+ * signaling that no narrowing should occur.
+ */
+export declare const expectedTypeForOperator: (leftType: string, operator: string) => string | undefined;
+/**
+ * Check if a candidate type is compatible with an expected type.
+ * "dyn" is a wildcard — compatible with anything in either direction.
+ */
+export declare const isTypeCompatible: (candidateType: string, expectedType: string) => boolean;