@rcrsr/rill-cli 0.6.0

package/src/check/rules/naming.ts

@@ -0,0 +1,242 @@
+/**
+ * Naming Convention Rules
+ * Enforces snake_case naming for variables, parameters, and dict keys.
+ */
+
+import type {
+  ValidationRule,
+  Diagnostic,
+  Fix,
+  ValidationContext,
+  FixContext,
+} from '../types.js';
+import type {
+  ASTNode,
+  ClosureParamNode,
+  DictEntryNode,
+  CaptureNode,
+  SourceLocation,
+} from '@rcrsr/rill';
+import { extractContextLine } from './helpers.js';
+
+// ============================================================
+// NAMING VALIDATION
+// ============================================================
+
+/**
+ * Check if a name follows snake_case convention.
+ * Valid: user_name, item_list, is_valid, x, count
+ * Invalid: userName, ItemList, user-name, user.name
+ */
+function isSnakeCase(name: string): boolean {
+  // Empty string is invalid
+  if (!name) return false;
+
+  // Must match: lowercase letters, numbers, underscores only
+  // Must start with letter or underscore
+  // No consecutive underscores, no trailing underscore
+  const snakeCasePattern = /^[a-z_][a-z0-9_]*$/;
+  if (!snakeCasePattern.test(name)) return false;
+
+  // Reject consecutive underscores
+  if (name.includes('__')) return false;
+
+  // Reject trailing underscore (unless single underscore)
+  if (name.length > 1 && name.endsWith('_')) return false;
+
+  return true;
+}
+
+/**
+ * Convert a name to snake_case.
+ * Handles camelCase, PascalCase, kebab-case, and mixed formats.
+ */
+function toSnakeCase(name: string): string {
+  return (
+    name
+      // Handle consecutive uppercase (XMLParser -> xml_parser)
+      .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+      // Insert underscore before uppercase letters (camelCase -> camel_case)
+      .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+      // Replace hyphens and dots with underscores
+      .replace(/[-.\s]+/g, '_')
+      // Convert to lowercase
+      .toLowerCase()
+      // Remove consecutive underscores
+      .replace(/_+/g, '_')
+      // Remove leading/trailing underscores
+      .replace(/^_+|_+$/g, '')
+  );
+}
+
+/**
+ * Create a diagnostic for snake_case violation.
+ */
+function createNamingDiagnostic(
+  location: SourceLocation,
+  name: string,
+  kind: string,
+  context: ValidationContext,
+  fix: Fix | null
+): Diagnostic {
+  const message = `${kind} '${name}' should use snake_case (e.g., '${toSnakeCase(name)}')`;
+
+  return {
+    location,
+    severity: 'error',
+    code: 'NAMING_SNAKE_CASE',
+    message,
+    context: extractContextLine(location.line, context.source),
+    fix,
+  };
+}
+
+// ============================================================
+// NAMING_SNAKE_CASE RULE
+// ============================================================
+
+/**
+ * Validates that variable definitions, parameters, and dict keys use snake_case.
+ *
+ * Checks definition sites only (not variable usage):
+ * - Captures: => $user_name, => $item_list, => $is_valid
+ * - Closure params: |user_name, count| { }
+ * - Dict keys: [user_name: "Alice", is_active: true]
+ *
+ * Exceptions:
+ * - Single-letter names are valid (common for loop variables)
+ *
+ * References:
+ * - docs/guide-conventions.md:10-53
+ */
+export const NAMING_SNAKE_CASE: ValidationRule = {
+  code: 'NAMING_SNAKE_CASE',
+  category: 'naming',
+  severity: 'error',
+  nodeTypes: ['ClosureParam', 'DictEntry', 'Capture'],
+
+  validate(node: ASTNode, context: ValidationContext): Diagnostic[] {
+    switch (node.type) {
+      case 'ClosureParam': {
+        const paramNode = node as ClosureParamNode;
+        const name = paramNode.name;
+
+        if (!isSnakeCase(name)) {
+          const fix = this.fix?.(node, context) ?? null;
+          return [
+            createNamingDiagnostic(
+              paramNode.span.start,
+              name,
+              'Parameter',
+              context,
+              fix
+            ),
+          ];
+        }
+        return [];
+      }
+
+      case 'DictEntry': {
+        const entryNode = node as DictEntryNode;
+        const key = entryNode.key;
+
+        // Skip multi-key entries (tuple keys) - only validate string keys
+        if (typeof key !== 'string') {
+          return [];
+        }
+
+        if (!isSnakeCase(key)) {
+          const fix = this.fix?.(node, context) ?? null;
+          return [
+            createNamingDiagnostic(
+              entryNode.span.start,
+              key,
+              'Dict key',
+              context,
+              fix
+            ),
+          ];
+        }
+        return [];
+      }
+
+      case 'Capture': {
+        const captureNode = node as CaptureNode;
+        const name = captureNode.name;
+
+        if (!isSnakeCase(name)) {
+          const fix = this.fix?.(node, context) ?? null;
+          return [
+            createNamingDiagnostic(
+              captureNode.span.start,
+              name,
+              'Captured variable',
+              context,
+              fix
+            ),
+          ];
+        }
+        return [];
+      }
+
+      default:
+        return [];
+    }
+  },
+
+  fix(node: ASTNode, context: FixContext): Fix | null {
+    let name: string | null = null;
+    let range = node.span;
+
+    // Extract name and determine replacement range
+    switch (node.type) {
+      case 'ClosureParam': {
+        const paramNode = node as ClosureParamNode;
+        name = paramNode.name;
+        break;
+      }
+
+      case 'DictEntry': {
+        const entryNode = node as DictEntryNode;
+        // Skip multi-key entries (tuple keys) - only fix string keys
+        if (typeof entryNode.key === 'string') {
+          name = entryNode.key;
+          // For dict entries, replace only the key portion before the colon
+        }
+        break;
+      }
+
+      case 'Capture': {
+        const captureNode = node as CaptureNode;
+        name = captureNode.name;
+        break;
+      }
+
+      default:
+        return null;
+    }
+
+    if (!name || isSnakeCase(name)) {
+      return null;
+    }
+
+    const snakeCaseName = toSnakeCase(name);
+
+    // Get original source text for this node
+    const sourceText = context.source.substring(
+      range.start.offset,
+      range.end.offset
+    );
+
+    // Replace the original name with snake_case version
+    // This preserves $ prefix for variables and : for dict entries
+    const replacement = sourceText.replace(name, snakeCaseName);
+
+    return {
+      description: `Rename '${name}' to '${snakeCaseName}'`,
+      applicable: true,
+      range,
+      replacement,
+    };
+  },
+};

package/src/check/rules/strings.ts

@@ -0,0 +1,104 @@
+/**
+ * String Handling Convention Rules
+ * Enforces string handling best practices from docs/guide-conventions.md:318-352.
+ */
+
+import type {
+  ValidationRule,
+  Diagnostic,
+  ValidationContext,
+} from '../types.js';
+import type { ASTNode, StringLiteralNode, BinaryExprNode } from '@rcrsr/rill';
+import { extractContextLine } from './helpers.js';
+
+// ============================================================
+// USE_EMPTY_METHOD RULE
+// ============================================================
+
+/**
+ * Enforces .empty method for emptiness checks.
+ * Direct string comparison with "" is not idiomatic and may not work
+ * correctly in all contexts. Use .empty method instead.
+ *
+ * Detection:
+ * - BinaryExpr with == or != operator
+ * - One side is empty string literal ""
+ * - Suggests using .empty method
+ *
+ * Valid patterns:
+ * - $str -> .empty (check if empty)
+ * - $str -> .empty ? "yes" ! "no" (conditional)
+ *
+ * Discouraged:
+ * - $str == "" (direct comparison)
+ * - $str != "" (direct comparison)
+ *
+ * References:
+ * - docs/guide-conventions.md:333-345
+ */
+export const USE_EMPTY_METHOD: ValidationRule = {
+  code: 'USE_EMPTY_METHOD',
+  category: 'strings',
+  severity: 'warning',
+  nodeTypes: ['BinaryExpr'],
+
+  validate(node: ASTNode, context: ValidationContext): Diagnostic[] {
+    const binaryNode = node as BinaryExprNode;
+
+    // Only check equality operators
+    if (binaryNode.op !== '==' && binaryNode.op !== '!=') {
+      return [];
+    }
+
+    // left and right are PostfixExpr - check their primaries
+    const { left, right } = binaryNode;
+
+    const leftIsEmpty =
+      left.type === 'PostfixExpr' && isEmptyStringLiteral(left.primary);
+    const rightIsEmpty =
+      right.type === 'PostfixExpr' && isEmptyStringLiteral(right.primary);
+
+    if (leftIsEmpty || rightIsEmpty) {
+      const suggestedMethod = binaryNode.op === '==' ? '.empty' : '.empty -> !';
+
+      return [
+        {
+          location: binaryNode.span.start,
+          severity: 'warning',
+          code: 'USE_EMPTY_METHOD',
+          message: `Use ${suggestedMethod} for emptiness checks instead of comparing with ""`,
+          context: extractContextLine(
+            binaryNode.span.start.line,
+            context.source
+          ),
+          fix: null, // Auto-fix would require expression reconstruction
+        },
+      ];
+    }
+
+    return [];
+  },
+};
+
+/**
+ * Check if a node is an empty string literal.
+ */
+function isEmptyStringLiteral(node: ASTNode): boolean {
+  if (node.type !== 'StringLiteral') {
+    return false;
+  }
+
+  const stringNode = node as StringLiteralNode;
+
+  // Check if all parts are empty strings (no interpolations)
+  if (stringNode.parts.length === 0) {
+    return true;
+  }
+
+  if (stringNode.parts.length === 1) {
+    const part = stringNode.parts[0];
+    return typeof part === 'string' && part === '';
+  }
+
+  return false;
+}

package/src/check/rules/types.ts

@@ -0,0 +1,214 @@
+/**
+ * Type Safety Convention Rules
+ * Enforces type annotation best practices from docs/guide-conventions.md:288-316.
+ */
+
+import type {
+  ValidationRule,
+  Diagnostic,
+  Fix,
+  ValidationContext,
+  FixContext,
+} from '../types.js';
+import type { ASTNode, HostCallNode, TypeAssertionNode } from '@rcrsr/rill';
+import { extractContextLine } from './helpers.js';
+
+// ============================================================
+// UNNECESSARY_ASSERTION RULE
+// ============================================================
+
+/**
+ * Detects redundant type assertions on literal values.
+ * Type assertions are for validation, not conversion. Asserting a literal's
+ * type is unnecessary because the type is already known at parse time.
+ *
+ * Redundant patterns:
+ * - 5:number (number literal with number assertion)
+ * - "hello":string (string literal with string assertion)
+ * - true:bool (bool literal with bool assertion)
+ *
+ * Valid patterns:
+ * - parseJson($input):dict (external input validation)
+ * - $userInput:string (runtime validation)
+ *
+ * References:
+ * - docs/guide-conventions.md:305-315
+ */
+export const UNNECESSARY_ASSERTION: ValidationRule = {
+  code: 'UNNECESSARY_ASSERTION',
+  category: 'types',
+  severity: 'info',
+  nodeTypes: ['TypeAssertion'],
+
+  validate(node: ASTNode, context: ValidationContext): Diagnostic[] {
+    const assertionNode = node as TypeAssertionNode;
+    const operand = assertionNode.operand;
+
+    // Bare assertions (:type) are valid - they check pipe value
+    if (!operand) {
+      return [];
+    }
+
+    // operand is PostfixExprNode - check the primary
+    const primary = operand.primary;
+
+    // Check if primary is a literal
+    const isLiteral =
+      primary.type === 'NumberLiteral' ||
+      primary.type === 'StringLiteral' ||
+      primary.type === 'BoolLiteral';
+
+    if (!isLiteral) {
+      return [];
+    }
+
+    // Check if the assertion matches the literal type
+    const literalType = getLiteralType(primary);
+    const assertedType = assertionNode.typeName;
+
+    if (literalType === assertedType) {
+      const fix = this.fix?.(node, context) ?? null;
+
+      return [
+        {
+          location: assertionNode.span.start,
+          severity: 'info',
+          code: 'UNNECESSARY_ASSERTION',
+          message: `Type assertion on ${literalType} literal is unnecessary`,
+          context: extractContextLine(
+            assertionNode.span.start.line,
+            context.source
+          ),
+          fix,
+        },
+      ];
+    }
+
+    return [];
+  },
+
+  fix(node: ASTNode, context: FixContext): Fix | null {
+    const assertionNode = node as TypeAssertionNode;
+    const operand = assertionNode.operand;
+
+    if (!operand) {
+      return null;
+    }
+
+    // Find the end of the type assertion (:type part)
+    const assertionSource = context.source.substring(
+      assertionNode.span.start.offset,
+      assertionNode.span.end.offset
+    );
+
+    // The type assertion is "literal:type" - we want to keep only "literal"
+    // Find the : character position
+    const colonIndex = assertionSource.indexOf(':');
+    if (colonIndex === -1) {
+      return null;
+    }
+
+    // Calculate the actual end of ":type" part
+    const typeStart = assertionNode.span.start.offset + colonIndex;
+    const typeEnd = typeStart + 1 + assertionNode.typeName.length;
+
+    return {
+      description: 'Remove unnecessary type assertion',
+      applicable: true,
+      range: {
+        start: { ...assertionNode.span.start, offset: typeStart },
+        end: { ...assertionNode.span.start, offset: typeEnd },
+      },
+      replacement: '',
+    };
+  },
+};
+
+/**
+ * Get the type name of a literal node.
+ */
+function getLiteralType(
+  node: ASTNode
+): 'string' | 'number' | 'bool' | 'list' | 'dict' | null {
+  switch (node.type) {
+    case 'NumberLiteral':
+      return 'number';
+    case 'StringLiteral':
+      return 'string';
+    case 'BoolLiteral':
+      return 'bool';
+    case 'Tuple':
+      return 'list';
+    case 'Dict':
+      return 'dict';
+    default:
+      return null;
+  }
+}
+
+// ============================================================
+// VALIDATE_EXTERNAL RULE
+// ============================================================
+
+/**
+ * Recommends type assertions for external input validation.
+ * External inputs (from host functions, user input, parsed data) should be
+ * validated with type assertions to ensure type safety.
+ *
+ * Detection heuristics:
+ * - Host function calls (HostCall nodes)
+ * - Parsing functions (parse_json, parse_xml, etc.)
+ * - Variables from external sources ($ARGS, $ENV)
+ *
+ * This is an informational rule - not all external data needs assertions,
+ * but it's a good practice for critical paths.
+ *
+ * References:
+ * - docs/guide-conventions.md:307-311
+ */
+export const VALIDATE_EXTERNAL: ValidationRule = {
+  code: 'VALIDATE_EXTERNAL',
+  category: 'types',
+  severity: 'info',
+  nodeTypes: ['HostCall'],
+
+  validate(node: ASTNode, context: ValidationContext): Diagnostic[] {
+    const hostCallNode = node as HostCallNode;
+    const functionName = hostCallNode.name;
+
+    // Skip namespaced functions (ns::func) - these are trusted host APIs
+    if (functionName.includes('::')) {
+      return [];
+    }
+
+    // Check if this is a parsing or external data function
+    const isExternalDataFunction =
+      functionName.startsWith('parse_') ||
+      functionName.includes('fetch') ||
+      functionName.includes('read') ||
+      functionName.includes('load');
+
+    if (!isExternalDataFunction) {
+      return [];
+    }
+
+    // Skip if this HostCall is already wrapped in a TypeAssertion
+    if (context.assertedHostCalls.has(node)) {
+      return [];
+    }
+
+    return [
+      {
+        location: hostCallNode.span.start,
+        severity: 'info',
+        code: 'VALIDATE_EXTERNAL',
+        message: `Consider validating external input with type assertion: ${functionName}():type`,
+        context: extractContextLine(
+          hostCallNode.span.start.line,
+          context.source
+        ),
+        fix: null, // Cannot auto-fix - requires developer judgment
+      },
+    ];
+  },
+};