@seljs/checker 1.0.0 → 1.0.1

package/dist/rules/defaults/no-mixed-operators.mjs

@@ -0,0 +1,39 @@
+import { nodeSpan, walkAST } from "../../utils/ast-utils.mjs";
+//#region src/rules/defaults/no-mixed-operators.ts
+/**
+* Check whether a child expression has explicit parentheses in the source.
+* Scans backwards from the child's start position for a `(`.
+*/
+const hasExplicitParens = (src, child) => {
+	let i = nodeSpan(child).from - 1;
+	while (i >= 0 && (src[i] === " " || src[i] === "	")) i--;
+	return i >= 0 && src[i] === "(";
+};
+/**
+* Flags mixed `&&` and `||` without explicit parentheses.
+*
+* The cel-js parser discards parentheses from the AST, so this rule
+* inspects the original source text via `node.input` to determine
+* whether parentheses were explicitly written.
+*/
+const noMixedOperators = {
+	name: "no-mixed-operators",
+	description: "Require parentheses when mixing logical operators (&& and ||).",
+	defaultSeverity: "info",
+	tier: "structural",
+	run(context) {
+		const diagnostics = [];
+		walkAST(context.ast, (node) => {
+			if (node.op !== "&&" && node.op !== "||") return;
+			const opposite = node.op === "&&" ? "||" : "&&";
+			const [left, right] = node.args;
+			for (const child of [left, right]) if (child.op === opposite && !hasExplicitParens(node.input, child)) {
+				diagnostics.push(context.report(node, "Mixed logical operators without parentheses. Add explicit grouping to clarify precedence."));
+				break;
+			}
+		});
+		return diagnostics;
+	}
+};
+//#endregion
+export { noMixedOperators };

package/dist/rules/defaults/no-redundant-bool.cjs

@@ -0,0 +1,26 @@
+const require_ast_utils = require("../../utils/ast-utils.cjs");
+//#region src/rules/defaults/no-redundant-bool.ts
+/**
+* Flags redundant boolean comparisons: `x == true`, `x != false`, etc.
+*/
+const noRedundantBool = {
+	name: "no-redundant-bool",
+	description: "Disallow redundant comparisons to boolean literals (true/false).",
+	defaultSeverity: "warning",
+	tier: "structural",
+	run(context) {
+		const diagnostics = [];
+		require_ast_utils.walkAST(context.ast, (node) => {
+			if (node.op !== "==" && node.op !== "!=") return;
+			const [left, right] = node.args;
+			const leftIsBool = left.op === "value" && typeof left.args === "boolean";
+			const rightIsBool = right.op === "value" && typeof right.args === "boolean";
+			if (!leftIsBool && !rightIsBool) return;
+			const boolValue = leftIsBool ? left.args : right.args;
+			diagnostics.push(context.report(node, `Redundant comparison to \`${String(boolValue)}\`. Simplify the expression.`));
+		});
+		return diagnostics;
+	}
+};
+//#endregion
+exports.noRedundantBool = noRedundantBool;

package/dist/rules/defaults/no-redundant-bool.mjs

@@ -0,0 +1,26 @@
+import { walkAST } from "../../utils/ast-utils.mjs";
+//#region src/rules/defaults/no-redundant-bool.ts
+/**
+* Flags redundant boolean comparisons: `x == true`, `x != false`, etc.
+*/
+const noRedundantBool = {
+	name: "no-redundant-bool",
+	description: "Disallow redundant comparisons to boolean literals (true/false).",
+	defaultSeverity: "warning",
+	tier: "structural",
+	run(context) {
+		const diagnostics = [];
+		walkAST(context.ast, (node) => {
+			if (node.op !== "==" && node.op !== "!=") return;
+			const [left, right] = node.args;
+			const leftIsBool = left.op === "value" && typeof left.args === "boolean";
+			const rightIsBool = right.op === "value" && typeof right.args === "boolean";
+			if (!leftIsBool && !rightIsBool) return;
+			const boolValue = leftIsBool ? left.args : right.args;
+			diagnostics.push(context.report(node, `Redundant comparison to \`${String(boolValue)}\`. Simplify the expression.`));
+		});
+		return diagnostics;
+	}
+};
+//#endregion
+export { noRedundantBool };

package/dist/rules/defaults/no-self-comparison.cjs

@@ -0,0 +1,44 @@
+require("../../_virtual/_rolldown/runtime.cjs");
+const require_ast_utils = require("../../utils/ast-utils.cjs");
+let _marcbachmann_cel_js = require("@marcbachmann/cel-js");
+//#region src/rules/defaults/no-self-comparison.ts
+const COMPARISON_OPS = new Set([
+	"==",
+	"!=",
+	"<",
+	"<=",
+	">",
+	">="
+]);
+const ALWAYS_TRUE_OPS = new Set([
+	"==",
+	"<=",
+	">="
+]);
+/**
+* Flags comparisons where both sides are the same expression (tautology/contradiction).
+*
+* Uses `serialize()` for identity comparison (safe for this purpose —
+* normalization is acceptable when comparing subtree identity, unlike
+* span calculation where it would produce incorrect positions).
+*/
+const noSelfComparison = {
+	name: "no-self-comparison",
+	description: "Disallow comparing an expression to itself.",
+	defaultSeverity: "warning",
+	tier: "structural",
+	run(context) {
+		const diagnostics = [];
+		require_ast_utils.walkAST(context.ast, (node) => {
+			if (!COMPARISON_OPS.has(node.op)) return;
+			const [left, right] = node.args;
+			if ((0, _marcbachmann_cel_js.serialize)(left) === (0, _marcbachmann_cel_js.serialize)(right)) {
+				const alwaysResult = ALWAYS_TRUE_OPS.has(node.op) ? "true" : "false";
+				diagnostics.push(context.report(node, `Both sides of \`${node.op}\` are identical. This is always \`${alwaysResult}\`.`));
+			}
+		});
+		return diagnostics;
+	}
+};
+//#endregion
+exports.noSelfComparison = noSelfComparison;

package/dist/rules/defaults/no-self-comparison.mjs

@@ -0,0 +1,43 @@
+import { walkAST } from "../../utils/ast-utils.mjs";
+import { serialize } from "@marcbachmann/cel-js";
+//#region src/rules/defaults/no-self-comparison.ts
+const COMPARISON_OPS = new Set([
+	"==",
+	"!=",
+	"<",
+	"<=",
+	">",
+	">="
+]);
+const ALWAYS_TRUE_OPS = new Set([
+	"==",
+	"<=",
+	">="
+]);
+/**
+* Flags comparisons where both sides are the same expression (tautology/contradiction).
+*
+* Uses `serialize()` for identity comparison (safe for this purpose —
+* normalization is acceptable when comparing subtree identity, unlike
+* span calculation where it would produce incorrect positions).
+*/
+const noSelfComparison = {
+	name: "no-self-comparison",
+	description: "Disallow comparing an expression to itself.",
+	defaultSeverity: "warning",
+	tier: "structural",
+	run(context) {
+		const diagnostics = [];
+		walkAST(context.ast, (node) => {
+			if (!COMPARISON_OPS.has(node.op)) return;
+			const [left, right] = node.args;
+			if (serialize(left) === serialize(right)) {
+				const alwaysResult = ALWAYS_TRUE_OPS.has(node.op) ? "true" : "false";
+				diagnostics.push(context.report(node, `Both sides of \`${node.op}\` are identical. This is always \`${alwaysResult}\`.`));
+			}
+		});
+		return diagnostics;
+	}
+};
+//#endregion
+export { noSelfComparison };

package/dist/rules/defaults/require-type.cjs

@@ -0,0 +1,18 @@
+//#region src/rules/defaults/require-type.ts
+/**
+* Rule factory that enforces an expression evaluates to the expected CEL type.
+*
+* @param expected - The CEL type name the expression must resolve to (e.g. "bool", "uint256")
+*/
+const requireType = (expected) => ({
+	name: `require-type-${expected}`,
+	description: `Expression must evaluate to ${expected}.`,
+	defaultSeverity: "error",
+	tier: "type-aware",
+	run(context) {
+		if (context.resolvedType === expected) return [];
+		return [context.reportAt(0, context.expression.length, `Expected expression to evaluate to "${expected}", but got "${String(context.resolvedType)}".`)];
+	}
+});
+//#endregion
+exports.requireType = requireType;

package/dist/rules/defaults/require-type.mjs

@@ -0,0 +1,18 @@
+//#region src/rules/defaults/require-type.ts
+/**
+* Rule factory that enforces an expression evaluates to the expected CEL type.
+*
+* @param expected - The CEL type name the expression must resolve to (e.g. "bool", "uint256")
+*/
+const requireType = (expected) => ({
+	name: `require-type-${expected}`,
+	description: `Expression must evaluate to ${expected}.`,
+	defaultSeverity: "error",
+	tier: "type-aware",
+	run(context) {
+		if (context.resolvedType === expected) return [];
+		return [context.reportAt(0, context.expression.length, `Expected expression to evaluate to "${expected}", but got "${String(context.resolvedType)}".`)];
+	}
+});
+//#endregion
+export { requireType };

package/dist/rules/facade.cjs

@@ -0,0 +1,31 @@
+const require_deferred_call = require("./defaults/deferred-call.cjs");
+const require_no_constant_condition = require("./defaults/no-constant-condition.cjs");
+const require_no_mixed_operators = require("./defaults/no-mixed-operators.cjs");
+const require_no_redundant_bool = require("./defaults/no-redundant-bool.cjs");
+const require_no_self_comparison = require("./defaults/no-self-comparison.cjs");
+const require_require_type = require("./defaults/require-type.cjs");
+require("./defaults/index.cjs");
+//#region src/rules/facade.ts
+/**
+* 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.
+*/
+const rules = {
+	builtIn: [
+		require_no_redundant_bool.noRedundantBool,
+		require_no_constant_condition.noConstantCondition,
+		require_no_mixed_operators.noMixedOperators,
+		require_no_self_comparison.noSelfComparison,
+		require_deferred_call.deferredCall
+	],
+	noRedundantBool: require_no_redundant_bool.noRedundantBool,
+	noConstantCondition: require_no_constant_condition.noConstantCondition,
+	noMixedOperators: require_no_mixed_operators.noMixedOperators,
+	noSelfComparison: require_no_self_comparison.noSelfComparison,
+	deferredCall: require_deferred_call.deferredCall,
+	requireType: require_require_type.requireType
+};
+//#endregion
+exports.rules = rules;

package/dist/rules/facade.d.cts

@@ -0,0 +1,20 @@
+import { SELRule } from "./types.cjs";
+
+//#region src/rules/facade.d.ts
+/**
+ * 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.
+ */
+declare const rules: {
+  /** All built-in lint rules. */readonly builtIn: readonly [SELRule, SELRule, SELRule, SELRule, SELRule]; /** Flags redundant comparisons to boolean literals (true/false). */
+  readonly noRedundantBool: SELRule; /** Flags constant conditions (e.g. `true && x`, `1 == 1`). */
+  readonly noConstantCondition: SELRule; /** Requires parentheses when mixing `&&` and `||`. */
+  readonly noMixedOperators: SELRule; /** Flags self-comparisons (e.g. `x == x`). */
+  readonly noSelfComparison: SELRule; /** Flags contract calls with dynamic arguments that will execute as live RPC calls. */
+  readonly deferredCall: SELRule; /** Rule factory that enforces an expression evaluates to the expected CEL type. */
+  readonly requireType: (expected: string) => SELRule;
+};
+//#endregion
+export { rules };

package/dist/rules/facade.d.mts

@@ -0,0 +1,20 @@
+import { SELRule } from "./types.mjs";
+
+//#region src/rules/facade.d.ts
+/**
+ * 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.
+ */
+declare const rules: {
+  /** All built-in lint rules. */readonly builtIn: readonly [SELRule, SELRule, SELRule, SELRule, SELRule]; /** Flags redundant comparisons to boolean literals (true/false). */
+  readonly noRedundantBool: SELRule; /** Flags constant conditions (e.g. `true && x`, `1 == 1`). */
+  readonly noConstantCondition: SELRule; /** Requires parentheses when mixing `&&` and `||`. */
+  readonly noMixedOperators: SELRule; /** Flags self-comparisons (e.g. `x == x`). */
+  readonly noSelfComparison: SELRule; /** Flags contract calls with dynamic arguments that will execute as live RPC calls. */
+  readonly deferredCall: SELRule; /** Rule factory that enforces an expression evaluates to the expected CEL type. */
+  readonly requireType: (expected: string) => SELRule;
+};
+//#endregion
+export { rules };

package/dist/rules/facade.mjs

@@ -0,0 +1,31 @@
+import { deferredCall } from "./defaults/deferred-call.mjs";
+import { noConstantCondition } from "./defaults/no-constant-condition.mjs";
+import { noMixedOperators } from "./defaults/no-mixed-operators.mjs";
+import { noRedundantBool } from "./defaults/no-redundant-bool.mjs";
+import { noSelfComparison } from "./defaults/no-self-comparison.mjs";
+import { requireType } from "./defaults/require-type.mjs";
+import "./defaults/index.mjs";
+//#region src/rules/facade.ts
+/**
+* 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.
+*/
+const rules = {
+	builtIn: [
+		noRedundantBool,
+		noConstantCondition,
+		noMixedOperators,
+		noSelfComparison,
+		deferredCall
+	],
+	noRedundantBool,
+	noConstantCondition,
+	noMixedOperators,
+	noSelfComparison,
+	deferredCall,
+	requireType
+};
+//#endregion
+export { rules };

package/dist/rules/index.cjs

@@ -0,0 +1,2 @@
+require("./facade.cjs");
+require("./runner.cjs");

package/dist/rules/index.d.mts

@@ -0,0 +1,3 @@
+import { RuleContext, RuleSeverity, RuleTier, SELRule } from "./types.mjs";
+import { rules } from "./facade.mjs";
+import { RunRulesOptions, runRules } from "./runner.mjs";

package/dist/rules/index.mjs

@@ -0,0 +1,3 @@
+import "./facade.mjs";
+import "./runner.mjs";
+export {};

package/dist/rules/runner.cjs

@@ -0,0 +1,40 @@
+const require_ast_utils = require("../utils/ast-utils.cjs");
+//#region src/rules/runner.ts
+/**
+* Run enabled rules of the specified tier against a parsed AST.
+*/
+const runRules = ({ expression, ast, schema, rules, tier, resolvedType }) => {
+	const diagnostics = [];
+	for (const rule of rules) {
+		if ((rule.tier ?? "structural") !== tier) continue;
+		const severity = rule.defaultSeverity;
+		const context = {
+			expression,
+			ast,
+			schema,
+			severity,
+			resolvedType,
+			report(node, message) {
+				const span = require_ast_utils.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;
+};
+//#endregion
+exports.runRules = runRules;

package/dist/rules/runner.d.cts

@@ -0,0 +1,27 @@
+import { RuleTier, SELRule } from "./types.cjs";
+import { SELDiagnostic } from "../checker/checker.cjs";
+import { ASTNode } from "@marcbachmann/cel-js";
+import { SELSchema } from "@seljs/schema";
+
+//#region src/rules/runner.d.ts
+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.
+ */
+declare const runRules: ({
+  expression,
+  ast,
+  schema,
+  rules,
+  tier,
+  resolvedType
+}: RunRulesOptions) => SELDiagnostic[];
+//#endregion
+export { RunRulesOptions, runRules };

package/dist/rules/runner.d.mts

@@ -0,0 +1,27 @@
+import { RuleTier, SELRule } from "./types.mjs";
+import { SELDiagnostic } from "../checker/checker.mjs";
+import { ASTNode } from "@marcbachmann/cel-js";
+import { SELSchema } from "@seljs/schema";
+
+//#region src/rules/runner.d.ts
+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.
+ */
+declare const runRules: ({
+  expression,
+  ast,
+  schema,
+  rules,
+  tier,
+  resolvedType
+}: RunRulesOptions) => SELDiagnostic[];
+//#endregion
+export { RunRulesOptions, runRules };

package/dist/rules/runner.mjs

@@ -0,0 +1,40 @@
+import { nodeSpan } from "../utils/ast-utils.mjs";
+//#region src/rules/runner.ts
+/**
+* Run enabled rules of the specified tier against a parsed AST.
+*/
+const runRules = ({ expression, ast, schema, rules, tier, resolvedType }) => {
+	const diagnostics = [];
+	for (const rule of rules) {
+		if ((rule.tier ?? "structural") !== 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;
+};
+//#endregion
+export { runRules };

package/dist/rules/types.d.cts

@@ -0,0 +1,77 @@
+import { SELDiagnostic } from "../checker/checker.cjs";
+import { ASTNode } from "@marcbachmann/cel-js";
+import { SELSchema } from "@seljs/schema";
+
+//#region src/rules/types.d.ts
+/**
+ * Severity levels for rules.
+ */
+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
+ */
+type RuleTier = "structural" | "type-aware";
+/**
+ * Context passed to each rule's run function.
+ */
+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.
+ */
+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[];
+}
+//#endregion
+export { RuleContext, RuleSeverity, RuleTier, SELRule };

package/dist/rules/types.d.mts

@@ -0,0 +1,77 @@
+import { SELDiagnostic } from "../checker/checker.mjs";
+import { ASTNode } from "@marcbachmann/cel-js";
+import { SELSchema } from "@seljs/schema";
+
+//#region src/rules/types.d.ts
+/**
+ * Severity levels for rules.
+ */
+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
+ */
+type RuleTier = "structural" | "type-aware";
+/**
+ * Context passed to each rule's run function.
+ */
+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.
+ */
+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[];
+}
+//#endregion
+export { RuleContext, RuleSeverity, RuleTier, SELRule };