feat: report error when @utils.setVariables assigns to undefined variable (#59)

Author: awli

dialect/agentscript/src/lint/passes/index.ts

@@ -28,6 +28,7 @@ import { reasoningActionsAnalyzer } from './reasoning-actions.js';
 import { actionIoRule } from './action-io.js';
 import { actionTypeCheckRule } from './action-type-check.js';
 import { availableWhenTypeCheckRule } from './available-when-type-check.js';
+import { setVariablesIoRule } from './set-variables-io.js';
 
 export { typeMapAnalyzer, typeMapKey } from './type-map.js';
 export type {
@@ -46,10 +47,15 @@ export {
   reasoningActionsAnalyzer,
   reasoningActionsKey,
 } from './reasoning-actions.js';
-export type { ReasoningActionEntry } from './reasoning-actions.js';
+export type {
+  ReasoningActionEntry,
+  SetVariablesEntry,
+} from './reasoning-actions.js';
+export { setVariablesEntriesKey } from './reasoning-actions.js';
 export { actionIoRule } from './action-io.js';
 export { actionTypeCheckRule } from './action-type-check.js';
 export { availableWhenTypeCheckRule } from './available-when-type-check.js';
+export { setVariablesIoRule } from './set-variables-io.js';
 
 /** All AgentScript lint passes in engine execution order. */
 export function defaultRules(): LintPass[] {
@@ -77,5 +83,6 @@ export function defaultRules(): LintPass[] {
     actionIoRule(),
     actionTypeCheckRule(),
     availableWhenTypeCheckRule(),
+    setVariablesIoRule(),
   ];
 }

dialect/agentscript/src/lint/passes/reasoning-actions.ts

@@ -60,6 +60,20 @@ interface RawReasoningAction {
 export const reasoningActionsKey =
   storeKey<ReasoningActionEntry[]>('reasoning-actions');
 
+export interface SetVariablesEntry {
+  topicName: string;
+  /** The ReasoningActionBlock AST node. */
+  ra: Record<string, unknown>;
+  /** WithClause statements within the setVariables block. */
+  statements: Array<Record<string, unknown>> | undefined;
+  /** Range of the @utils.setVariables expression. */
+  actionRefRange: Range | undefined;
+}
+
+export const setVariablesEntriesKey = storeKey<SetVariablesEntry[]>(
+  'set-variables-entries'
+);
+
 class ReasoningActionsAnalyzer implements LintPass {
   readonly id = reasoningActionsKey;
   readonly description =
@@ -74,6 +88,7 @@ class ReasoningActionsAnalyzer implements LintPass {
     if (!ctx) return;
 
     const raw: RawReasoningAction[] = [];
+    const setVarEntries: SetVariablesEntry[] = [];
     const rootObj = root as AstNodeLike;
 
     // Support both 'subagent' (base dialect) and 'topic' (agentforce dialect)
@@ -155,6 +170,12 @@ class ReasoningActionsAnalyzer implements LintPass {
               statements,
               actionRefRange,
             });
+          } else if (
+            decomposed &&
+            decomposed.namespace === 'utils' &&
+            decomposed.property === 'setVariables'
+          ) {
+            setVarEntries.push({ topicName, ra, statements, actionRefRange });
           }
         }
       }
@@ -187,6 +208,7 @@ class ReasoningActionsAnalyzer implements LintPass {
     }
 
     store.set(reasoningActionsKey, entries);
+    store.set(setVariablesEntriesKey, setVarEntries);
   }
 }
 

dialect/agentscript/src/lint/passes/set-variables-io.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2026, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ * For full license text, see the LICENSE file in the repo root or https://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/**
+ * setVariables I/O validation — validates that `with` clause parameters in
+ * @utils.setVariables reasoning actions reference defined mutable variables.
+ *
+ * Diagnostics: set-variables-unknown-variable, set-variables-immutable-target
+ */
+
+import type { LintPass } from '@agentscript/language';
+import {
+  defineRule,
+  each,
+  attachDiagnostic,
+  findSuggestion,
+  lintDiagnostic,
+} from '@agentscript/language';
+import type { CstMeta, SyntaxNode } from '@agentscript/types';
+import { toRange, DiagnosticSeverity } from '@agentscript/types';
+import { setVariablesEntriesKey } from './reasoning-actions.js';
+import { typeMapKey } from './type-map.js';
+
+export function setVariablesIoRule(): LintPass {
+  return defineRule({
+    id: 'set-variables-io',
+    description:
+      'Validates with clause params in @utils.setVariables reference defined mutable variables',
+    deps: { entry: each(setVariablesEntriesKey), typeMap: typeMapKey },
+
+    run({ entry, typeMap }) {
+      const { statements } = entry;
+      if (!statements) return;
+
+      for (const stmt of statements) {
+        if (stmt.__kind !== 'WithClause') continue;
+        const param = stmt.param as string;
+        if (!param) continue;
+
+        const varInfo = typeMap.variables.get(param);
+        if (!varInfo) {
+          const cst = stmt.__cst as CstMeta | undefined;
+          if (!cst) continue;
+          const paramCstNode = (stmt as { __paramCstNode?: SyntaxNode })
+            .__paramCstNode;
+          const range = paramCstNode ? toRange(paramCstNode) : cst.range;
+
+          const suggestion = findSuggestion(param, [
+            ...typeMap.variables.keys(),
+          ]);
+          const msg = `'${param}' is not a defined variable. @utils.setVariables can only assign to declared variables.`;
+          attachDiagnostic(
+            stmt,
+            lintDiagnostic(
+              range,
+              msg,
+              DiagnosticSeverity.Error,
+              'set-variables-unknown-variable',
+              { suggestion }
+            )
+          );
+          continue;
+        }
+
+        if (varInfo.modifier !== 'mutable') {
+          const cst = stmt.__cst as CstMeta | undefined;
+          if (!cst) continue;
+          const paramCstNode = (stmt as { __paramCstNode?: SyntaxNode })
+            .__paramCstNode;
+          const range = paramCstNode ? toRange(paramCstNode) : cst.range;
+
+          const qualifier = varInfo.modifier ?? 'non-mutable';
+          const msg = `'${param}' is a ${qualifier} variable. @utils.setVariables can only assign to mutable variables.`;
+          attachDiagnostic(
+            stmt,
+            lintDiagnostic(
+              range,
+              msg,
+              DiagnosticSeverity.Error,
+              'set-variables-immutable-target'
+            )
+          );
+        }
+      }
+    },
+  });
+}