@seljs/checker 1.0.0

package/dist/rules/facade.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Unified export for rules.
+ *
+ * Provides access to individual built-in rules, a convenience array of all
+ * built-in rules, and rule factories for custom enforcement.
+ */
+export declare const rules: {
+    /** All built-in lint rules. */
+    readonly builtIn: readonly [import("./types.js").SELRule, import("./types.js").SELRule, import("./types.js").SELRule, import("./types.js").SELRule, import("./types.js").SELRule];
+    /** Flags redundant comparisons to boolean literals (true/false). */
+    readonly noRedundantBool: import("./types.js").SELRule;
+    /** Flags constant conditions (e.g. `true && x`, `1 == 1`). */
+    readonly noConstantCondition: import("./types.js").SELRule;
+    /** Requires parentheses when mixing `&&` and `||`. */
+    readonly noMixedOperators: import("./types.js").SELRule;
+    /** Flags self-comparisons (e.g. `x == x`). */
+    readonly noSelfComparison: import("./types.js").SELRule;
+    /** Flags contract calls with dynamic arguments that will execute as live RPC calls. */
+    readonly deferredCall: import("./types.js").SELRule;
+    /** Rule factory that enforces an expression evaluates to the expected CEL type. */
+    readonly requireType: (expected: string) => import("./types.js").SELRule;
+};

package/dist/rules/facade.js

@@ -0,0 +1,29 @@
+import { deferredCall, noConstantCondition, noMixedOperators, noRedundantBool, noSelfComparison, requireType, } from "./defaults/index.js";
+/**
+ * Unified export for rules.
+ *
+ * Provides access to individual built-in rules, a convenience array of all
+ * built-in rules, and rule factories for custom enforcement.
+ */
+export const rules = {
+    /** All built-in lint rules. */
+    builtIn: [
+        noRedundantBool,
+        noConstantCondition,
+        noMixedOperators,
+        noSelfComparison,
+        deferredCall,
+    ],
+    /** Flags redundant comparisons to boolean literals (true/false). */
+    noRedundantBool,
+    /** Flags constant conditions (e.g. `true && x`, `1 == 1`). */
+    noConstantCondition,
+    /** Requires parentheses when mixing `&&` and `||`. */
+    noMixedOperators,
+    /** Flags self-comparisons (e.g. `x == x`). */
+    noSelfComparison,
+    /** Flags contract calls with dynamic arguments that will execute as live RPC calls. */
+    deferredCall,
+    /** Rule factory that enforces an expression evaluates to the expected CEL type. */
+    requireType,
+};

package/dist/rules/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./facade.js";
+export * from "./runner.js";
+export * from "./types.js";

package/dist/rules/index.js

@@ -0,0 +1,3 @@
+export * from "./facade.js";
+export * from "./runner.js";
+export * from "./types.js";

package/dist/rules/runner.d.ts

@@ -0,0 +1,16 @@
+import type { RuleTier, SELRule } from "./types.js";
+import type { SELDiagnostic } from "../checker/checker.js";
+import type { ASTNode } from "@marcbachmann/cel-js";
+import type { SELSchema } from "@seljs/schema";
+export interface RunRulesOptions {
+    expression: string;
+    ast: ASTNode;
+    schema: SELSchema;
+    rules: readonly SELRule[];
+    tier: RuleTier;
+    resolvedType?: string;
+}
+/**
+ * Run enabled rules of the specified tier against a parsed AST.
+ */
+export declare const runRules: ({ expression, ast, schema, rules, tier, resolvedType, }: RunRulesOptions) => SELDiagnostic[];

package/dist/rules/runner.js

@@ -0,0 +1,30 @@
+import { nodeSpan } from "../utils/index.js";
+/**
+ * Run enabled rules of the specified tier against a parsed AST.
+ */
+export const runRules = ({ expression, ast, schema, rules, tier, resolvedType, }) => {
+    const diagnostics = [];
+    for (const rule of rules) {
+        const ruleTier = rule.tier ?? "structural";
+        if (ruleTier !== tier) {
+            continue;
+        }
+        const severity = rule.defaultSeverity;
+        const context = {
+            expression,
+            ast,
+            schema,
+            severity,
+            resolvedType,
+            report(node, message) {
+                const span = nodeSpan(node);
+                return { message, severity, from: span.from, to: span.to };
+            },
+            reportAt(from, to, message) {
+                return { message, severity, from, to };
+            },
+        };
+        diagnostics.push(...rule.run(context));
+    }
+    return diagnostics;
+};

package/dist/rules/types.d.ts

@@ -0,0 +1,73 @@
+import type { SELDiagnostic } from "../checker/checker.js";
+import type { ASTNode } from "@marcbachmann/cel-js";
+import type { SELSchema } from "@seljs/schema";
+/**
+ * Severity levels for rules.
+ */
+export type RuleSeverity = "error" | "warning" | "info";
+/**
+ * Tier determines when a rule runs:
+ * - "structural": runs on any successfully-parsed expression, even if type-check fails
+ * - "type-aware": runs only when both parse and type-check succeed
+ */
+export type RuleTier = "structural" | "type-aware";
+/**
+ * Context passed to each rule's run function.
+ */
+export interface RuleContext {
+    /**
+     * The raw expression string.
+     */
+    expression: string;
+    /**
+     * The parsed AST root node.
+     */
+    ast: ASTNode;
+    /**
+     * The active schema (contracts, variables, types, functions).
+     */
+    schema: SELSchema;
+    /**
+     * The resolved severity for this rule invocation.
+     */
+    severity: RuleSeverity;
+    /**
+     * Resolved CEL type of the full expression. Only set for type-aware rules.
+     */
+    resolvedType?: string;
+    /**
+     * Create a diagnostic spanning an AST node's source range.
+     */
+    report: (node: ASTNode, message: string) => SELDiagnostic;
+    /**
+     * Create a diagnostic at an explicit position range.
+     */
+    reportAt: (from: number, to: number, message: string) => SELDiagnostic;
+}
+/**
+ * A lint rule that analyzes a parsed expression and reports diagnostics.
+ */
+export interface SELRule {
+    /**
+     * Unique rule identifier (kebab-case, e.g. "no-redundant-bool").
+     */
+    name: string;
+    /**
+     * Human-readable description.
+     */
+    description: string;
+    /**
+     * Severity level for diagnostics reported by this rule.
+     */
+    defaultSeverity: RuleSeverity;
+    /**
+     * Execution tier. Defaults to "structural" if omitted.
+     * - "structural": rule receives AST even when type-check failed
+     * - "type-aware": rule only runs after successful type-check
+     */
+    tier?: RuleTier;
+    /**
+     * Analyze the expression and return diagnostics.
+     */
+    run: (context: RuleContext) => SELDiagnostic[];
+}

package/dist/rules/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/ast-utils.d.ts

@@ -0,0 +1,55 @@
+import type { ASTNode } from "@marcbachmann/cel-js";
+interface NodeSpan {
+    from: number;
+    to: number;
+}
+type ASTVisitor = (node: ASTNode, parent: ASTNode | null) => void;
+/**
+ * Compute the source span {from, to} of an AST node.
+ *
+ * Uses the AST structure and `node.input` (original source) to calculate
+ * positions. Does NOT use `serialize()` which normalizes whitespace,
+ * quotes, and parentheses.
+ *
+ * Note: for binary operators, `node.pos` points to the operator token,
+ * not the start of the expression. We compute `from` by finding the
+ * leftmost descendant leaf position instead.
+ */
+declare const nodeSpan: (node: ASTNode) => NodeSpan;
+/**
+ * Depth-first walk of the AST, calling visitor on every node.
+ */
+declare const walkAST: (node: ASTNode, visitor: ASTVisitor, parent?: ASTNode | null) => void;
+/**
+ * Collect all ASTNode children of a node, regardless of op shape.
+ */
+declare const collectChildren: (node: ASTNode) => ASTNode[];
+/**
+ * Find the deepest AST node whose span contains the given offset.
+ *
+ * Walks the tree depth-first. At each level, if a child's span contains
+ * the offset, recurse into that child. Returns the deepest matching node,
+ * or undefined if the offset is outside the root span.
+ */
+declare const findNodeAt: (root: ASTNode, offset: number) => ASTNode | undefined;
+interface NodeWithParent {
+    node: ASTNode;
+    parent: ASTNode | null;
+}
+declare const findNodeWithParentAt: (root: ASTNode, offset: number, parent?: ASTNode | null) => NodeWithParent | undefined;
+interface EnclosingCallInfo {
+    functionName: string;
+    receiverName?: string;
+    paramIndex: number;
+}
+/**
+ * Find the enclosing call/rcall node for a cursor offset and determine
+ * which argument index the cursor falls within.
+ *
+ * Walks the AST to find call/rcall nodes whose span contains the offset,
+ * then determines the argument index by checking which arg node's span
+ * the offset falls within.
+ */
+declare const findEnclosingCallInfo: (root: ASTNode, offset: number) => EnclosingCallInfo | undefined;
+export { collectChildren, findEnclosingCallInfo, findNodeAt, findNodeWithParentAt, nodeSpan, walkAST, };
+export type { ASTVisitor, EnclosingCallInfo, NodeSpan, NodeWithParent };

package/dist/utils/ast-utils.js

@@ -0,0 +1,255 @@
+const BINARY_OPS = new Set([
+    "==",
+    "!=",
+    "<",
+    "<=",
+    ">",
+    ">=",
+    "+",
+    "-",
+    "*",
+    "/",
+    "%",
+    "in",
+    "||",
+    "&&",
+    "[]",
+    "[?]",
+]);
+/**
+ * Compute the source span {from, to} of an AST node.
+ *
+ * Uses the AST structure and `node.input` (original source) to calculate
+ * positions. Does NOT use `serialize()` which normalizes whitespace,
+ * quotes, and parentheses.
+ *
+ * Note: for binary operators, `node.pos` points to the operator token,
+ * not the start of the expression. We compute `from` by finding the
+ * leftmost descendant leaf position instead.
+ */
+const nodeSpan = (node) => {
+    const src = node.input;
+    if (node.op === "id") {
+        return { from: node.pos, to: node.pos + node.args.length };
+    }
+    if (node.op === "value") {
+        return valueSpan(src, node.pos);
+    }
+    // Composite: compute from as leftmost child start, to as rightmost child end
+    const children = collectChildren(node);
+    let minFrom = node.pos;
+    let maxTo = node.pos;
+    for (const child of children) {
+        const s = nodeSpan(child);
+        if (s.from < minFrom) {
+            minFrom = s.from;
+        }
+        if (s.to > maxTo) {
+            maxTo = s.to;
+        }
+    }
+    // For unary operators, node.pos IS the start (e.g. `!` in `!x`)
+    if (node.op === "!_" || node.op === "-_") {
+        minFrom = node.pos;
+    }
+    // Handle trailing syntax for delimited constructs
+    if (node.op === "." || node.op === ".?") {
+        const fieldName = node.args[1];
+        let i = maxTo;
+        while (i < src.length && src[i] !== ".") {
+            i++;
+        }
+        // skip dot
+        i++;
+        if (node.op === ".?" && i < src.length && src[i] === "?") {
+            i++;
+        }
+        i += fieldName.length;
+        return { from: minFrom, to: Math.min(i, src.length) };
+    }
+    if (node.op === "call" || node.op === "rcall") {
+        return { from: minFrom, to: scanTo(src, maxTo, ")") };
+    }
+    if (node.op === "list" || node.op === "[]" || node.op === "[?]") {
+        return { from: minFrom, to: scanTo(src, maxTo, "]") };
+    }
+    if (node.op === "map") {
+        return { from: minFrom, to: scanTo(src, maxTo, "}") };
+    }
+    return { from: minFrom, to: maxTo };
+};
+/**
+ * Depth-first walk of the AST, calling visitor on every node.
+ */
+const walkAST = (node, visitor, parent = null) => {
+    visitor(node, parent);
+    for (const child of collectChildren(node)) {
+        walkAST(child, visitor, node);
+    }
+};
+/**
+ * Collect all ASTNode children of a node, regardless of op shape.
+ */
+const collectChildren = (node) => {
+    if (node.op === "value" || node.op === "id") {
+        return [];
+    }
+    if (node.op === "!_" || node.op === "-_") {
+        return [node.args];
+    }
+    if (BINARY_OPS.has(node.op)) {
+        const [left, right] = node.args;
+        return [left, right];
+    }
+    switch (node.op) {
+        case ".":
+        case ".?": {
+            const [receiver] = node.args;
+            return [receiver];
+        }
+        case "call": {
+            const [, callArgs] = node.args;
+            return callArgs;
+        }
+        case "rcall": {
+            const [, receiver, callArgs] = node.args;
+            return [receiver, ...callArgs];
+        }
+        case "list":
+            return node.args;
+        case "map": {
+            const entries = node.args;
+            return entries.flat();
+        }
+        case "?:": {
+            const [cond, then, els] = node.args;
+            return [cond, then, els];
+        }
+        default:
+            return [];
+    }
+};
+const valueSpan = (src, from) => {
+    const ch = src[from];
+    if (ch === '"' || ch === "'") {
+        let i = from + 1;
+        while (i < src.length && src[i] !== ch) {
+            if (src[i] === "\\") {
+                i++;
+            }
+            i++;
+        }
+        return { from, to: i < src.length ? i + 1 : i };
+    }
+    // Boolean, null, number: scan past word characters and dots (floats)
+    let i = from;
+    while (i < src.length && /[\w.]/.test(src[i] ?? "")) {
+        i++;
+    }
+    return { from, to: i };
+};
+const scanTo = (src, from, ch) => {
+    let i = from;
+    while (i < src.length && src[i] !== ch) {
+        i++;
+    }
+    return i < src.length ? i + 1 : from;
+};
+/**
+ * Find the deepest AST node whose span contains the given offset.
+ *
+ * Walks the tree depth-first. At each level, if a child's span contains
+ * the offset, recurse into that child. Returns the deepest matching node,
+ * or undefined if the offset is outside the root span.
+ */
+const findNodeAt = (root, offset) => {
+    const rootSpan = nodeSpan(root);
+    if (offset < rootSpan.from || offset >= rootSpan.to) {
+        return undefined;
+    }
+    const children = collectChildren(root);
+    for (const child of children) {
+        const childSpan = nodeSpan(child);
+        if (offset >= childSpan.from && offset < childSpan.to) {
+            return findNodeAt(child, offset) ?? child;
+        }
+    }
+    return root;
+};
+const findNodeWithParentAt = (root, offset, parent = null) => {
+    const rootSpan = nodeSpan(root);
+    if (offset < rootSpan.from || offset >= rootSpan.to) {
+        return undefined;
+    }
+    const children = collectChildren(root);
+    for (const child of children) {
+        const childSpan = nodeSpan(child);
+        if (offset >= childSpan.from && offset < childSpan.to) {
+            return (findNodeWithParentAt(child, offset, root) ?? {
+                node: child,
+                parent: root,
+            });
+        }
+    }
+    return { node: root, parent };
+};
+/**
+ * Find the enclosing call/rcall node for a cursor offset and determine
+ * which argument index the cursor falls within.
+ *
+ * Walks the AST to find call/rcall nodes whose span contains the offset,
+ * then determines the argument index by checking which arg node's span
+ * the offset falls within.
+ */
+const findEnclosingCallInfo = (root, offset) => {
+    let result;
+    walkAST(root, (node) => {
+        if (node.op !== "call" && node.op !== "rcall") {
+            return;
+        }
+        const span = nodeSpan(node);
+        if (offset < span.from || offset >= span.to) {
+            return;
+        }
+        if (node.op === "call") {
+            const [name, args] = node.args;
+            const paramIndex = findArgIndex(args, offset);
+            if (paramIndex >= 0) {
+                result = { functionName: name, paramIndex };
+            }
+        }
+        if (node.op === "rcall") {
+            const [name, receiver, args] = node.args;
+            const paramIndex = findArgIndex(args, offset);
+            if (paramIndex >= 0) {
+                const receiverName = receiver.op === "id" ? receiver.args : undefined;
+                result = { functionName: name, receiverName, paramIndex };
+            }
+        }
+    });
+    return result;
+};
+/** Determine which argument index a cursor offset falls within. */
+const findArgIndex = (args, offset) => {
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg) {
+            continue;
+        }
+        const argSpan = nodeSpan(arg);
+        if (offset >= argSpan.from && offset < argSpan.to) {
+            return i;
+        }
+    }
+    if (args.length > 0) {
+        const lastArg = args[args.length - 1];
+        if (lastArg) {
+            const lastSpan = nodeSpan(lastArg);
+            if (offset >= lastSpan.to) {
+                return args.length;
+            }
+        }
+    }
+    return args.length === 0 ? 0 : -1;
+};
+export { collectChildren, findEnclosingCallInfo, findNodeAt, findNodeWithParentAt, nodeSpan, walkAST, };

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./ast-utils.js";

package/dist/utils/index.js

@@ -0,0 +1 @@
+export * from "./ast-utils.js";

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@seljs/checker",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": {
+    "name": "abi group GmbH",
+    "email": "info@abigroup.io",
+    "url": "https://abigroup.io/"
+  },
+  "repository": {
+    "url": "https://github.com/abinnovision/seljs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "format:check": "prettier --check '{{src,test}/**/*,*}.{{t,j}s{,x},json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write '{{src,test}/**/*,*}.{{t,j}s{,x},json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint '{{src,test}/**/*,*}.{t,j}s{,x}'",
+    "lint:fix": "eslint '{{src,test}/**/*,*}.{t,j}s{,x}' --fix",
+    "test-integration": "vitest run --config test/integration/vitest.config.ts",
+    "test-unit": "vitest run",
+    "test-unit:watch": "vitest watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "lint-staged": {
+    "{{src,test}/**/*,*}.{{t,j}s{,x},json{,5},md,y{,a}ml}": [
+      "prettier --write"
+    ],
+    "{{src,test}/**/*,*}.{t,j}s{,x}": [
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "@marcbachmann/cel-js": "^7.5.2",
+    "@seljs/common": "1.0.0",
+    "@seljs/schema": "1.0.0",
+    "@seljs/types": "1.0.0",
+    "debug": "^4.4.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@abinnovision/eslint-config-base": "^3.2.0",
+    "@abinnovision/prettier-config": "^2.1.5",
+    "@seljs-internal/tsconfig": "^0.0.0",
+    "@types/debug": "^4.1.12",
+    "eslint": "^9.39.4",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "npm": true,
+    "npmAccess": "public"
+  }
+}