@rcrsr/rill-cli 0.6.0

package/src/check/types.ts

@@ -0,0 +1,163 @@
+/**
+ * Check Types
+ * Type definitions for the rill-check static analysis tool.
+ */
+
+import type {
+  SourceLocation,
+  SourceSpan,
+  ScriptNode,
+  NodeType,
+  ASTNode,
+} from '@rcrsr/rill';
+
+// ============================================================
+// SEVERITY AND RULE STATE
+// ============================================================
+
+/** Diagnostic severity levels */
+export type Severity = 'error' | 'warning' | 'info';
+
+/** Rule state configuration */
+export type RuleState = 'on' | 'off' | 'warn';
+
+// ============================================================
+// DIAGNOSTIC DATA
+// ============================================================
+
+/**
+ * Fix suggestion for a diagnostic.
+ * Provides automated fix information that can be applied to source code.
+ */
+export interface Fix {
+  /** Human-readable description of what the fix does */
+  readonly description: string;
+  /** Whether the fix can be safely applied automatically */
+  readonly applicable: boolean;
+  /** Source range to replace */
+  readonly range: SourceSpan;
+  /** Replacement text */
+  readonly replacement: string;
+}
+
+/**
+ * A single diagnostic issue found during validation.
+ * Represents errors, warnings, or informational messages from static analysis.
+ */
+export interface Diagnostic {
+  /** Location of the issue in source */
+  readonly location: SourceLocation;
+  /** Severity level */
+  readonly severity: Severity;
+  /** Rule code (e.g., NAMING_SNAKE_CASE) */
+  readonly code: string;
+  /** Human-readable description */
+  readonly message: string;
+  /** Source line containing the issue */
+  readonly context: string;
+  /** Optional automatic fix */
+  readonly fix: Fix | null;
+}
+
+// ============================================================
+// CHECK CONFIGURATION
+// ============================================================
+
+/**
+ * Configuration for check rules and severity overrides.
+ * Controls which rules are active and at what severity level.
+ */
+export interface CheckConfig {
+  /** Per-rule enable/disable/warn state */
+  readonly rules: Record<string, RuleState>;
+  /** Severity overrides by rule code */
+  readonly severity: Record<string, Severity>;
+}
+
+// ============================================================
+// VALIDATION CONTEXT
+// ============================================================
+
+/**
+ * Context for validation passes.
+ * Tracks source, AST, configuration, and accumulated diagnostics.
+ */
+export interface ValidationContext {
+  /** Original source text */
+  readonly source: string;
+  /** Parsed AST */
+  readonly ast: ScriptNode;
+  /** Active configuration */
+  readonly config: CheckConfig;
+  /** Accumulated diagnostics */
+  readonly diagnostics: Diagnostic[];
+  /** Variable definitions for collision detection */
+  readonly variables: Map<string, SourceLocation>;
+  /** HostCall nodes that are wrapped in type assertions */
+  readonly assertedHostCalls: Set<ASTNode>;
+  /** Closure scope IDs for variables (maps variable name to closure AST node) */
+  readonly variableScopes: Map<string, ASTNode | null>;
+  /** Current closure scope stack during traversal */
+  readonly scopeStack: ASTNode[];
+}
+
+/**
+ * Context for fix generation.
+ * Provides access to source and AST for computing fix replacements.
+ */
+export interface FixContext {
+  /** Original source text */
+  readonly source: string;
+  /** Parsed AST */
+  readonly ast: ScriptNode;
+}
+
+// ============================================================
+// VALIDATION RULES
+// ============================================================
+
+/** Rule category for grouping and organization */
+export type RuleCategory =
+  | 'naming'
+  | 'flow'
+  | 'collections'
+  | 'loops'
+  | 'conditionals'
+  | 'closures'
+  | 'types'
+  | 'strings'
+  | 'errors'
+  | 'formatting'
+  | 'anti-patterns';
+
+/**
+ * Validation rule interface.
+ * Rules are stateless - all context passed via ValidationContext.
+ * Rules return diagnostics, never throw.
+ * fix() must preserve semantics (no behavior changes).
+ */
+export interface ValidationRule {
+  /** Unique rule code (e.g., NAMING_SNAKE_CASE) */
+  readonly code: string;
+
+  /** Rule category for grouping */
+  readonly category: RuleCategory;
+
+  /** Default severity level */
+  readonly severity: Severity;
+
+  /** Node types this rule applies to */
+  readonly nodeTypes: NodeType[];
+
+  /**
+   * Validate a node, returning diagnostics for violations.
+   * Called for each node matching nodeTypes.
+   */
+  validate(node: ASTNode, context: ValidationContext): Diagnostic[];
+
+  /**
+   * Optionally generate a fix for a diagnostic.
+   * Returns null if fix not applicable.
+   */
+  fix?(node: ASTNode, context: FixContext): Fix | null;
+}

package/src/check/validator.ts

@@ -0,0 +1,136 @@
+/**
+ * Script Validator
+ * Orchestrates validation by traversing AST and invoking enabled rules.
+ */
+
+import type {
+  ScriptNode,
+  ASTNode,
+  CaptureNode,
+  TypeAssertionNode,
+} from '@rcrsr/rill';
+import type { CheckConfig, Diagnostic, ValidationContext } from './types.js';
+import { visitNode, type RuleVisitor } from './visitor.js';
+import { VALIDATION_RULES } from './rules/index.js';
+
+// ============================================================
+// VALIDATION ORCHESTRATOR
+// ============================================================
+
+/**
+ * Validate script AST against all enabled rules.
+ * Traverses AST using visitor pattern, invoking enabled rules for matching nodes.
+ * Returns diagnostics sorted by line number, then column.
+ *
+ * @param ast - Parsed script AST to validate
+ * @param source - Original source text for context extraction
+ * @param config - Configuration determining which rules are active
+ * @returns Array of diagnostics sorted by location
+ */
+export function validateScript(
+  ast: ScriptNode,
+  source: string,
+  config: CheckConfig
+): Diagnostic[] {
+  // Create validation context
+  const context: ValidationContext = {
+    source,
+    ast,
+    config,
+    diagnostics: [],
+    variables: new Map(),
+    assertedHostCalls: new Set(),
+    variableScopes: new Map(),
+    scopeStack: [],
+  };
+
+  // Create visitor that invokes enabled rules
+  const visitor: RuleVisitor = {
+    enter(node: ASTNode, ctx: ValidationContext): void {
+      // Track closure scope entry
+      if (node.type === 'Closure') {
+        ctx.scopeStack.push(node);
+      }
+
+      // Track HostCall nodes wrapped in TypeAssertion BEFORE rules check
+      if (node.type === 'TypeAssertion') {
+        const operand = (node as TypeAssertionNode).operand;
+        if (operand?.primary.type === 'HostCall') {
+          ctx.assertedHostCalls.add(operand.primary);
+        }
+      }
+
+      // For each enabled rule that applies to this node type
+      for (const rule of VALIDATION_RULES) {
+        // Skip if rule not enabled
+        if (!isRuleEnabled(rule.code, ctx.config)) {
+          continue;
+        }
+
+        // Skip if rule doesn't apply to this node type
+        if (!rule.nodeTypes.includes(node.type)) {
+          continue;
+        }
+
+        // Invoke rule validation and accumulate diagnostics
+        const ruleDiagnostics = rule.validate(node, ctx);
+        ctx.diagnostics.push(...ruleDiagnostics);
+      }
+
+      // Track variable captures AFTER rules check (for reassignment detection)
+      if (node.type === 'Capture') {
+        const captureNode = node as CaptureNode;
+        if (!ctx.variables.has(captureNode.name)) {
+          ctx.variables.set(captureNode.name, node.span.start);
+          // Track which closure scope this variable belongs to
+          const currentScope =
+            ctx.scopeStack.length > 0
+              ? ctx.scopeStack[ctx.scopeStack.length - 1]
+              : null;
+          ctx.variableScopes.set(captureNode.name, currentScope ?? null);
+        }
+      }
+    },
+
+    exit(node: ASTNode, ctx: ValidationContext): void {
+      // Track closure scope exit
+      if (node.type === 'Closure') {
+        ctx.scopeStack.pop();
+      }
+    },
+  };
+
+  // Traverse AST with visitor
+  visitNode(ast, context, visitor);
+
+  // Sort diagnostics by location (line first, then column)
+  return sortDiagnostics(context.diagnostics);
+}
+
+// ============================================================
+// HELPERS
+// ============================================================
+
+/**
+ * Check if a rule is enabled based on configuration.
+ * Rules are enabled if state is 'on' or 'warn'.
+ */
+function isRuleEnabled(ruleCode: string, config: CheckConfig): boolean {
+  const state = config.rules[ruleCode];
+  return state === 'on' || state === 'warn';
+}
+
+/**
+ * Sort diagnostics by line number first, then column number.
+ * Stable sort preserves original order for diagnostics at same location.
+ */
+function sortDiagnostics(diagnostics: Diagnostic[]): Diagnostic[] {
+  return [...diagnostics].sort((a, b) => {
+    // Sort by line first
+    if (a.location.line !== b.location.line) {
+      return a.location.line - b.location.line;
+    }
+    // Then by column
+    return a.location.column - b.location.column;
+  });
+}

package/src/check/visitor.ts

@@ -0,0 +1,338 @@
+/**
+ * AST Visitor
+ * Recursive traversal with enter/exit callbacks for validation rules.
+ */
+
+import type { ASTNode } from '@rcrsr/rill';
+import type { ValidationContext } from './types.js';
+
+// ============================================================
+// VISITOR INTERFACE
+// ============================================================
+
+/**
+ * Visitor pattern interface for AST traversal.
+ * Provides enter/exit callbacks invoked before and after visiting children.
+ */
+export interface RuleVisitor {
+  /**
+   * Called before visiting node's children.
+   * Use for pre-order traversal validation.
+   */
+  enter(node: ASTNode, context: ValidationContext): void;
+
+  /**
+   * Called after visiting node's children.
+   * Use for post-order traversal validation.
+   */
+  exit(node: ASTNode, context: ValidationContext): void;
+}
+
+// ============================================================
+// VISITOR FUNCTION
+// ============================================================
+
+/**
+ * Recursively visit AST nodes with enter/exit callbacks.
+ * Handles all 46 node types from ASTNode union.
+ *
+ * Traversal order:
+ * 1. visitor.enter(node)
+ * 2. Recurse into children
+ * 3. visitor.exit(node)
+ */
+export function visitNode(
+  node: ASTNode,
+  context: ValidationContext,
+  visitor: RuleVisitor
+): void {
+  // Enter callback before children
+  visitor.enter(node, context);
+
+  // Recurse based on node type
+  switch (node.type) {
+    case 'Script':
+      if (node.frontmatter) {
+        visitNode(node.frontmatter, context, visitor);
+      }
+      for (const stmt of node.statements) {
+        visitNode(stmt, context, visitor);
+      }
+      break;
+
+    case 'Frontmatter':
+      // Leaf node - no children
+      break;
+
+    case 'Statement':
+      visitNode(node.expression, context, visitor);
+      break;
+
+    case 'AnnotatedStatement':
+      for (const arg of node.annotations) {
+        visitNode(arg, context, visitor);
+      }
+      visitNode(node.statement, context, visitor);
+      break;
+
+    case 'NamedArg':
+      visitNode(node.value, context, visitor);
+      break;
+
+    case 'SpreadArg':
+      visitNode(node.expression, context, visitor);
+      break;
+
+    case 'PipeChain':
+      visitNode(node.head, context, visitor);
+      for (const pipe of node.pipes) {
+        visitNode(pipe, context, visitor);
+      }
+      if (node.terminator) {
+        visitNode(node.terminator, context, visitor);
+      }
+      break;
+
+    case 'PostfixExpr':
+      visitNode(node.primary, context, visitor);
+      for (const method of node.methods) {
+        visitNode(method, context, visitor);
+      }
+      break;
+
+    case 'BinaryExpr':
+      visitNode(node.left, context, visitor);
+      visitNode(node.right, context, visitor);
+      break;
+
+    case 'UnaryExpr':
+      visitNode(node.operand, context, visitor);
+      break;
+
+    case 'GroupedExpr':
+      visitNode(node.expression, context, visitor);
+      break;
+
+    case 'StringLiteral':
+      for (const part of node.parts) {
+        if (typeof part !== 'string') {
+          visitNode(part, context, visitor);
+        }
+      }
+      break;
+
+    case 'Interpolation':
+      visitNode(node.expression, context, visitor);
+      break;
+
+    case 'NumberLiteral':
+    case 'BoolLiteral':
+      // Leaf nodes - no children
+      break;
+
+    case 'Tuple':
+      for (const element of node.elements) {
+        visitNode(element, context, visitor);
+      }
+      break;
+
+    case 'ListSpread':
+      visitNode(node.expression, context, visitor);
+      break;
+
+    case 'Dict':
+      for (const entry of node.entries) {
+        visitNode(entry, context, visitor);
+      }
+      break;
+
+    case 'DictEntry':
+      visitNode(node.value, context, visitor);
+      break;
+
+    case 'Closure':
+      for (const param of node.params) {
+        visitNode(param, context, visitor);
+      }
+      visitNode(node.body, context, visitor);
+      break;
+
+    case 'ClosureParam':
+      if (node.defaultValue) {
+        visitNode(node.defaultValue, context, visitor);
+      }
+      break;
+
+    case 'Variable':
+      if (node.defaultValue) {
+        visitNode(node.defaultValue, context, visitor);
+      }
+      break;
+
+    case 'HostCall':
+      for (const arg of node.args) {
+        visitNode(arg, context, visitor);
+      }
+      break;
+
+    case 'ClosureCall':
+      for (const arg of node.args) {
+        visitNode(arg, context, visitor);
+      }
+      break;
+
+    case 'MethodCall':
+      for (const arg of node.args) {
+        visitNode(arg, context, visitor);
+      }
+      break;
+
+    case 'Invoke':
+      for (const arg of node.args) {
+        visitNode(arg, context, visitor);
+      }
+      break;
+
+    case 'PipeInvoke':
+      for (const arg of node.args) {
+        visitNode(arg, context, visitor);
+      }
+      break;
+
+    case 'Conditional':
+      if (node.input) {
+        visitNode(node.input, context, visitor);
+      }
+      if (node.condition) {
+        visitNode(node.condition, context, visitor);
+      }
+      visitNode(node.thenBranch, context, visitor);
+      if (node.elseBranch) {
+        visitNode(node.elseBranch, context, visitor);
+      }
+      break;
+
+    case 'WhileLoop':
+      visitNode(node.condition, context, visitor);
+      visitNode(node.body, context, visitor);
+      break;
+
+    case 'DoWhileLoop':
+      if (node.input) {
+        visitNode(node.input, context, visitor);
+      }
+      visitNode(node.body, context, visitor);
+      visitNode(node.condition, context, visitor);
+      break;
+
+    case 'Block':
+      for (const stmt of node.statements) {
+        visitNode(stmt, context, visitor);
+      }
+      break;
+
+    case 'EachExpr':
+      visitNode(node.body, context, visitor);
+      if (node.accumulator) {
+        visitNode(node.accumulator, context, visitor);
+      }
+      break;
+
+    case 'MapExpr':
+      visitNode(node.body, context, visitor);
+      break;
+
+    case 'FoldExpr':
+      visitNode(node.body, context, visitor);
+      if (node.accumulator) {
+        visitNode(node.accumulator, context, visitor);
+      }
+      break;
+
+    case 'FilterExpr':
+      visitNode(node.body, context, visitor);
+      break;
+
+    case 'ClosureChain':
+      visitNode(node.target, context, visitor);
+      break;
+
+    case 'Destructure':
+      for (const element of node.elements) {
+        visitNode(element, context, visitor);
+      }
+      break;
+
+    case 'DestructPattern':
+      if (node.nested) {
+        visitNode(node.nested, context, visitor);
+      }
+      break;
+
+    case 'Slice':
+      if (node.start) {
+        visitNode(node.start, context, visitor);
+      }
+      if (node.stop) {
+        visitNode(node.stop, context, visitor);
+      }
+      if (node.step) {
+        visitNode(node.step, context, visitor);
+      }
+      break;
+
+    case 'Spread':
+      if (node.operand) {
+        visitNode(node.operand, context, visitor);
+      }
+      break;
+
+    case 'TypeAssertion':
+      if (node.operand) {
+        visitNode(node.operand, context, visitor);
+      }
+      break;
+
+    case 'TypeCheck':
+      if (node.operand) {
+        visitNode(node.operand, context, visitor);
+      }
+      break;
+
+    case 'Assert':
+      visitNode(node.condition, context, visitor);
+      if (node.message) {
+        visitNode(node.message, context, visitor);
+      }
+      break;
+
+    case 'Capture':
+    case 'Break':
+    case 'Return':
+    case 'Pass':
+      // Leaf nodes - no children
+      break;
+
+    case 'RecoveryError':
+      // Recovery error node - no children to visit
+      break;
+
+    case 'Error':
+      // Error statement node - visit message if present
+      if (node.message) {
+        visitNode(node.message, context, visitor);
+      }
+      break;
+
+    default: {
+      // Exhaustive check: if we reach here, a node type is missing
+      const _exhaustive: never = node;
+      throw new Error(
+        `Unhandled node type in visitor: ${(_exhaustive as ASTNode).type}`
+      );
+    }
+  }
+
+  // Exit callback after children
+  visitor.exit(node, context);
+}