@rcrsr/rill 0.1.0 → 0.2.0

package/dist/check/rules/helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared Helper Functions
+ * Common utilities used across validation rules.
+ */
+import type { ExpressionNode } from '../../types.js';
+/**
+ * Extract source line at location for context display.
+ * Splits source by newlines, retrieves the specified line (1-indexed), and trims it.
+ */
+export declare function extractContextLine(line: number, source: string): string;
+/**
+ * Detect if expression is a bare $ (pipe variable) reference.
+ * Used by IMPLICIT_DOLLAR_* rules to detect replaceable patterns.
+ *
+ * Returns true only for single bare $, not $var or $.field or $[0].
+ * O(1) depth traversal (max 3 node levels): PipeChain -> ArithHead -> PostfixExpr -> Variable.
+ *
+ * Distinct from containsBareReference() in closures.ts:
+ * - isBareReference(): O(1) single-node check, answers "is this exact node a bare $?"
+ * - containsBareReference(): Recursive AST walker, answers "does this subtree contain any bare $?"
+ *
+ * @param expr - Expression node to check
+ * @returns true if expr is a bare $ reference, false otherwise
+ */
+export declare function isBareReference(expr: ExpressionNode | null | undefined): boolean;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/check/rules/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/check/rules/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GACtC,OAAO,CAkDT"}

package/dist/check/rules/helpers.js

@@ -0,0 +1,66 @@
+/**
+ * Shared Helper Functions
+ * Common utilities used across validation rules.
+ */
+/**
+ * Extract source line at location for context display.
+ * Splits source by newlines, retrieves the specified line (1-indexed), and trims it.
+ */
+export function extractContextLine(line, source) {
+    const lines = source.split('\n');
+    const sourceLine = lines[line - 1];
+    return sourceLine ? sourceLine.trim() : '';
+}
+/**
+ * Detect if expression is a bare $ (pipe variable) reference.
+ * Used by IMPLICIT_DOLLAR_* rules to detect replaceable patterns.
+ *
+ * Returns true only for single bare $, not $var or $.field or $[0].
+ * O(1) depth traversal (max 3 node levels): PipeChain -> ArithHead -> PostfixExpr -> Variable.
+ *
+ * Distinct from containsBareReference() in closures.ts:
+ * - isBareReference(): O(1) single-node check, answers "is this exact node a bare $?"
+ * - containsBareReference(): Recursive AST walker, answers "does this subtree contain any bare $?"
+ *
+ * @param expr - Expression node to check
+ * @returns true if expr is a bare $ reference, false otherwise
+ */
+export function isBareReference(expr) {
+    // Defensive: handle null/undefined input
+    if (!expr) {
+        return false;
+    }
+    // Expression is PipeChain
+    if (expr.type !== 'PipeChain') {
+        return false;
+    }
+    const pipeChain = expr;
+    // Must have no pipe targets (just the head)
+    if (pipeChain.pipes.length > 0 || pipeChain.terminator !== null) {
+        return false;
+    }
+    const head = pipeChain.head;
+    // ArithHead can be BinaryExpr, UnaryExpr, or PostfixExpr
+    // For bare $, we need PostfixExpr
+    if (head.type !== 'PostfixExpr') {
+        return false;
+    }
+    const postfix = head;
+    // Must have no method calls (just the primary)
+    if (postfix.methods.length > 0) {
+        return false;
+    }
+    const primary = postfix.primary;
+    // Primary must be a Variable
+    if (primary.type !== 'Variable') {
+        return false;
+    }
+    const variable = primary;
+    // Must be pipe variable ($) with no access chain, default value, or existence check
+    return (variable.isPipeVar &&
+        variable.name === null &&
+        variable.accessChain.length === 0 &&
+        variable.defaultValue === null &&
+        variable.existenceCheck === null);
+}
+//# sourceMappingURL=helpers.js.map

package/dist/check/rules/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/check/rules/helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,MAAc;IAC7D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IACnC,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAuC;IAEvC,yCAAyC;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,KAAK,CAAC;IACf,CAAC;IAED,0BAA0B;IAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,IAAqB,CAAC;IAExC,4CAA4C;IAC5C,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QAChE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC;IAE5B,yDAAyD;IACzD,kCAAkC;IAClC,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,IAAuB,CAAC;IAExC,+CAA+C;IAC/C,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhC,6BAA6B;IAC7B,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,OAAuB,CAAC;IAEzC,oFAAoF;IACpF,OAAO,CACL,QAAQ,CAAC,SAAS;QAClB,QAAQ,CAAC,IAAI,KAAK,IAAI;QACtB,QAAQ,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;QACjC,QAAQ,CAAC,YAAY,KAAK,IAAI;QAC9B,QAAQ,CAAC,cAAc,KAAK,IAAI,CACjC,CAAC;AACJ,CAAC"}

package/dist/check/rules/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Validation Rules Registry
+ * Barrel export for all validation rules.
+ */
+import type { ValidationRule } from '../types.js';
+export { NAMING_SNAKE_CASE } from './naming.js';
+export { CAPTURE_INLINE_CHAIN, CAPTURE_BEFORE_BRANCH } from './flow.js';
+export { BREAK_IN_PARALLEL, PREFER_MAP, FOLD_INTERMEDIATES, FILTER_NEGATION, METHOD_SHORTHAND, } from './collections.js';
+export { LOOP_ACCUMULATOR, PREFER_DO_WHILE, USE_EACH } from './loops.js';
+export { USE_DEFAULT_OPERATOR, CONDITION_TYPE } from './conditionals.js';
+export { CLOSURE_BARE_DOLLAR, CLOSURE_BRACES, CLOSURE_LATE_BINDING, } from './closures.js';
+export { UNNECESSARY_ASSERTION, VALIDATE_EXTERNAL } from './types.js';
+export { USE_EMPTY_METHOD } from './strings.js';
+export { AVOID_REASSIGNMENT, COMPLEX_CONDITION, LOOP_OUTER_CAPTURE, } from './anti-patterns.js';
+export { SPACING_OPERATOR, SPACING_BRACES, SPACING_BRACKETS, SPACING_CLOSURE, INDENT_CONTINUATION, IMPLICIT_DOLLAR_METHOD, IMPLICIT_DOLLAR_FUNCTION, IMPLICIT_DOLLAR_CLOSURE, THROWAWAY_CAPTURE, } from './formatting.js';
+/**
+ * All registered validation rules.
+ * Rules are applied during AST traversal via the validator.
+ */
+export declare const VALIDATION_RULES: ValidationRule[];
+//# sourceMappingURL=index.d.ts.map

package/dist/check/rules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/check/rules/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAwClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EACL,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AAMzB;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAAc,EAmD5C,CAAC"}

package/dist/check/rules/index.js

@@ -0,0 +1,78 @@
+/**
+ * Validation Rules Registry
+ * Barrel export for all validation rules.
+ */
+import { NAMING_SNAKE_CASE } from './naming.js';
+import { CAPTURE_INLINE_CHAIN, CAPTURE_BEFORE_BRANCH } from './flow.js';
+import { BREAK_IN_PARALLEL, PREFER_MAP, FOLD_INTERMEDIATES, FILTER_NEGATION, METHOD_SHORTHAND, } from './collections.js';
+import { LOOP_ACCUMULATOR, PREFER_DO_WHILE, USE_EACH } from './loops.js';
+import { USE_DEFAULT_OPERATOR, CONDITION_TYPE } from './conditionals.js';
+import { CLOSURE_BARE_DOLLAR, CLOSURE_BRACES, CLOSURE_LATE_BINDING, } from './closures.js';
+import { UNNECESSARY_ASSERTION, VALIDATE_EXTERNAL } from './types.js';
+import { USE_EMPTY_METHOD } from './strings.js';
+import { AVOID_REASSIGNMENT, COMPLEX_CONDITION, LOOP_OUTER_CAPTURE, } from './anti-patterns.js';
+import { SPACING_OPERATOR, SPACING_BRACES, SPACING_BRACKETS, SPACING_CLOSURE, INDENT_CONTINUATION, IMPLICIT_DOLLAR_METHOD, IMPLICIT_DOLLAR_FUNCTION, IMPLICIT_DOLLAR_CLOSURE, THROWAWAY_CAPTURE, } from './formatting.js';
+// ============================================================
+// RE-EXPORT INDIVIDUAL RULES
+// ============================================================
+export { NAMING_SNAKE_CASE } from './naming.js';
+export { CAPTURE_INLINE_CHAIN, CAPTURE_BEFORE_BRANCH } from './flow.js';
+export { BREAK_IN_PARALLEL, PREFER_MAP, FOLD_INTERMEDIATES, FILTER_NEGATION, METHOD_SHORTHAND, } from './collections.js';
+export { LOOP_ACCUMULATOR, PREFER_DO_WHILE, USE_EACH } from './loops.js';
+export { USE_DEFAULT_OPERATOR, CONDITION_TYPE } from './conditionals.js';
+export { CLOSURE_BARE_DOLLAR, CLOSURE_BRACES, CLOSURE_LATE_BINDING, } from './closures.js';
+export { UNNECESSARY_ASSERTION, VALIDATE_EXTERNAL } from './types.js';
+export { USE_EMPTY_METHOD } from './strings.js';
+export { AVOID_REASSIGNMENT, COMPLEX_CONDITION, LOOP_OUTER_CAPTURE, } from './anti-patterns.js';
+export { SPACING_OPERATOR, SPACING_BRACES, SPACING_BRACKETS, SPACING_CLOSURE, INDENT_CONTINUATION, IMPLICIT_DOLLAR_METHOD, IMPLICIT_DOLLAR_FUNCTION, IMPLICIT_DOLLAR_CLOSURE, THROWAWAY_CAPTURE, } from './formatting.js';
+// ============================================================
+// RULE REGISTRY
+// ============================================================
+/**
+ * All registered validation rules.
+ * Rules are applied during AST traversal via the validator.
+ */
+export const VALIDATION_RULES = [
+    // Naming conventions
+    NAMING_SNAKE_CASE,
+    // Flow and capture
+    CAPTURE_INLINE_CHAIN,
+    CAPTURE_BEFORE_BRANCH,
+    // Collection operators
+    BREAK_IN_PARALLEL,
+    PREFER_MAP,
+    FOLD_INTERMEDIATES,
+    FILTER_NEGATION,
+    METHOD_SHORTHAND,
+    // Loop conventions
+    LOOP_ACCUMULATOR,
+    PREFER_DO_WHILE,
+    USE_EACH,
+    // Conditional conventions
+    USE_DEFAULT_OPERATOR,
+    CONDITION_TYPE,
+    // Closure conventions
+    CLOSURE_BARE_DOLLAR,
+    CLOSURE_BRACES,
+    CLOSURE_LATE_BINDING,
+    // Type safety
+    UNNECESSARY_ASSERTION,
+    VALIDATE_EXTERNAL,
+    // String handling
+    USE_EMPTY_METHOD,
+    // Anti-patterns
+    AVOID_REASSIGNMENT,
+    COMPLEX_CONDITION,
+    LOOP_OUTER_CAPTURE,
+    // Formatting
+    SPACING_OPERATOR,
+    SPACING_BRACES,
+    SPACING_BRACKETS,
+    SPACING_CLOSURE,
+    INDENT_CONTINUATION,
+    IMPLICIT_DOLLAR_METHOD,
+    IMPLICIT_DOLLAR_FUNCTION,
+    IMPLICIT_DOLLAR_CLOSURE,
+    THROWAWAY_CAPTURE,
+];
+//# sourceMappingURL=index.js.map

package/dist/check/rules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/check/rules/index.ts"],"names":[],"mappings":"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"}

package/dist/check/rules/loops.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Loop Convention Rules
+ * Enforces conventions for while, do-while, and loop control flow.
+ */
+import type { ValidationRule } from '../types.js';
+/**
+ * Validates that $ is used as accumulator in while/do-while loops.
+ *
+ * In while and do-while loops, $ serves as the accumulator across iterations.
+ * Variables captured inside the loop body exist only within that iteration.
+ *
+ * Good pattern ($ accumulates):
+ *   0 -> ($ < 5) @ { $ + 1 }
+ *
+ * Avoid pattern (named variables don't persist):
+ *   0 -> ($ < 5) @ {
+ *     $ :> $x        # $x exists only in this iteration
+ *     $x + 1
+ *   }
+ *
+ * This is stylistic - both work, but $ is clearer for accumulation.
+ *
+ * References:
+ * - docs/16_conventions.md:151-171
+ */
+export declare const LOOP_ACCUMULATOR: ValidationRule;
+/**
+ * Suggests using do-while for retry patterns.
+ *
+ * Do-while is clearer for retry patterns where the body must run at least once:
+ *
+ * Good (do-while for retry):
+ *   @ {
+ *     attemptOperation()
+ *   } ? (.contains("RETRY"))
+ *
+ * Less clear (while with separate first attempt):
+ *   attemptOperation() :> $result
+ *   $result -> .contains("RETRY") @ {
+ *     attemptOperation()
+ *   }
+ *
+ * This is informational - helps guide users to the clearer pattern.
+ *
+ * References:
+ * - docs/16_conventions.md:173-186
+ */
+export declare const PREFER_DO_WHILE: ValidationRule;
+/**
+ * Suggests using each for collection iteration instead of while loops.
+ *
+ * When iterating over a collection, each is clearer and more idiomatic:
+ *
+ * Good (each for collection):
+ *   $items -> each { process($) }
+ *
+ * Less clear (while loop):
+ *   0 :> $i
+ *   ($i < $items.len) @ {
+ *     $items[$i] -> process()
+ *     $i + 1
+ *   }
+ *
+ * This is informational - while loops work, but each is clearer for collections.
+ *
+ * References:
+ * - docs/16_conventions.md:188-196
+ */
+export declare const USE_EACH: ValidationRule;
+//# sourceMappingURL=loops.d.ts.map

package/dist/check/rules/loops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loops.d.ts","sourceRoot":"","sources":["../../../src/check/rules/loops.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,aAAa,CAAC;AAmGrB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,EAAE,cA0B9B,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,eAAe,EAAE,cA2B7B,CAAC;AAMF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,QAAQ,EAAE,cAmCtB,CAAC"}

package/dist/check/rules/loops.js

@@ -0,0 +1,227 @@
+/**
+ * Loop Convention Rules
+ * Enforces conventions for while, do-while, and loop control flow.
+ */
+import { extractContextLine } from './helpers.js';
+// ============================================================
+// HELPER FUNCTIONS
+// ============================================================
+/**
+ * Check if a loop body contains variable captures.
+ * Returns true if any captures are found in the body.
+ */
+function containsCaptures(node) {
+    switch (node.type) {
+        case 'Capture':
+            return true;
+        case 'Block':
+            return node.statements.some((stmt) => containsCaptures(stmt));
+        case 'Statement':
+            return containsCaptures(node.expression);
+        case 'AnnotatedStatement':
+            return containsCaptures(node.statement);
+        case 'PipeChain':
+            if (node.pipes.some((pipe) => containsCaptures(pipe)))
+                return true;
+            if (node.terminator && node.terminator.type === 'Capture')
+                return true;
+            return false;
+        case 'PostfixExpr':
+            if (containsCaptures(node.primary))
+                return true;
+            return node.methods.some((method) => containsCaptures(method));
+        case 'BinaryExpr':
+            return containsCaptures(node.left) || containsCaptures(node.right);
+        case 'UnaryExpr':
+            return containsCaptures(node.operand);
+        case 'GroupedExpr':
+            return containsCaptures(node.expression);
+        case 'Conditional':
+            if (node.input && containsCaptures(node.input))
+                return true;
+            if (node.condition && containsCaptures(node.condition))
+                return true;
+            if (containsCaptures(node.thenBranch))
+                return true;
+            if (node.elseBranch && containsCaptures(node.elseBranch))
+                return true;
+            return false;
+        case 'WhileLoop':
+        case 'DoWhileLoop':
+            return containsCaptures(node.body);
+        default:
+            return false;
+    }
+}
+/**
+ * Check if a loop body appears to be calling a retry function.
+ * Simple heuristic: looks for function calls like attemptOperation() or retry().
+ */
+function callsRetryFunction(node) {
+    if (node.type === 'Block') {
+        return node.statements.some((stmt) => callsRetryFunction(stmt));
+    }
+    if (node.type === 'Statement') {
+        return callsRetryFunction(node.expression);
+    }
+    if (node.type === 'PipeChain') {
+        const chain = node;
+        const head = chain.head;
+        // Check if head is a function call
+        if (head.type === 'PostfixExpr') {
+            const primary = head.primary;
+            if (primary.type === 'HostCall' || primary.type === 'ClosureCall') {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+// ============================================================
+// LOOP_ACCUMULATOR RULE
+// ============================================================
+/**
+ * Validates that $ is used as accumulator in while/do-while loops.
+ *
+ * In while and do-while loops, $ serves as the accumulator across iterations.
+ * Variables captured inside the loop body exist only within that iteration.
+ *
+ * Good pattern ($ accumulates):
+ *   0 -> ($ < 5) @ { $ + 1 }
+ *
+ * Avoid pattern (named variables don't persist):
+ *   0 -> ($ < 5) @ {
+ *     $ :> $x        # $x exists only in this iteration
+ *     $x + 1
+ *   }
+ *
+ * This is stylistic - both work, but $ is clearer for accumulation.
+ *
+ * References:
+ * - docs/16_conventions.md:151-171
+ */
+export const LOOP_ACCUMULATOR = {
+    code: 'LOOP_ACCUMULATOR',
+    category: 'loops',
+    severity: 'info',
+    nodeTypes: ['WhileLoop', 'DoWhileLoop'],
+    validate(node, context) {
+        const loop = node;
+        // Check if loop body contains captures
+        if (containsCaptures(loop.body)) {
+            return [
+                {
+                    location: node.span.start,
+                    severity: 'info',
+                    code: 'LOOP_ACCUMULATOR',
+                    message: 'Use $ as accumulator in while/do-while. Variables captured inside loop body exist only within that iteration.',
+                    context: extractContextLine(node.span.start.line, context.source),
+                    fix: null, // Complex fix - requires refactoring loop body
+                },
+            ];
+        }
+        return [];
+    },
+};
+// ============================================================
+// PREFER_DO_WHILE RULE
+// ============================================================
+/**
+ * Suggests using do-while for retry patterns.
+ *
+ * Do-while is clearer for retry patterns where the body must run at least once:
+ *
+ * Good (do-while for retry):
+ *   @ {
+ *     attemptOperation()
+ *   } ? (.contains("RETRY"))
+ *
+ * Less clear (while with separate first attempt):
+ *   attemptOperation() :> $result
+ *   $result -> .contains("RETRY") @ {
+ *     attemptOperation()
+ *   }
+ *
+ * This is informational - helps guide users to the clearer pattern.
+ *
+ * References:
+ * - docs/16_conventions.md:173-186
+ */
+export const PREFER_DO_WHILE = {
+    code: 'PREFER_DO_WHILE',
+    category: 'loops',
+    severity: 'info',
+    nodeTypes: ['WhileLoop'],
+    validate(node, context) {
+        const loop = node;
+        // Heuristic: if loop body appears to be calling a retry/attempt function,
+        // suggest do-while
+        if (callsRetryFunction(loop.body)) {
+            return [
+                {
+                    location: node.span.start,
+                    severity: 'info',
+                    code: 'PREFER_DO_WHILE',
+                    message: 'Consider do-while for retry patterns where body runs at least once: @ { body } ? (condition)',
+                    context: extractContextLine(node.span.start.line, context.source),
+                    fix: null, // Complex fix - requires restructuring to do-while
+                },
+            ];
+        }
+        return [];
+    },
+};
+// ============================================================
+// USE_EACH RULE
+// ============================================================
+/**
+ * Suggests using each for collection iteration instead of while loops.
+ *
+ * When iterating over a collection, each is clearer and more idiomatic:
+ *
+ * Good (each for collection):
+ *   $items -> each { process($) }
+ *
+ * Less clear (while loop):
+ *   0 :> $i
+ *   ($i < $items.len) @ {
+ *     $items[$i] -> process()
+ *     $i + 1
+ *   }
+ *
+ * This is informational - while loops work, but each is clearer for collections.
+ *
+ * References:
+ * - docs/16_conventions.md:188-196
+ */
+export const USE_EACH = {
+    code: 'USE_EACH',
+    category: 'loops',
+    severity: 'info',
+    nodeTypes: ['WhileLoop'],
+    validate(node, context) {
+        const loop = node;
+        // Simple heuristic: if the condition or body appears to be doing array iteration
+        const conditionStr = JSON.stringify(loop.condition);
+        const bodyStr = JSON.stringify(loop.body);
+        // Look for patterns like:
+        // - field access to 'len' (array length checks)
+        // - bracket access patterns with BracketAccess nodes in body
+        const hasLenCheck = conditionStr.includes('"field":"len"');
+        const hasBracketAccess = bodyStr.includes('"accessKind":"bracket"');
+        if (hasLenCheck || hasBracketAccess) {
+            return [
+                {
+                    location: node.span.start,
+                    severity: 'info',
+                    code: 'USE_EACH',
+                    message: "Use 'each' for collection iteration instead of while loops: collection -> each { body }",
+                    context: extractContextLine(node.span.start.line, context.source),
+                    fix: null, // Complex fix - requires restructuring to each
+                },
+            ];
+        }
+        return [];
+    },
+};
+//# sourceMappingURL=loops.js.map

package/dist/check/rules/loops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loops.js","sourceRoot":"","sources":["../../../src/check/rules/loops.ts"],"names":[],"mappings":"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"}

package/dist/check/rules/naming.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Naming Convention Rules
+ * Enforces snake_case naming for variables, parameters, and dict keys.
+ */
+import type { ValidationRule } from '../types.js';
+/**
+ * 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/16_conventions.md:10-53
+ */
+export declare const NAMING_SNAKE_CASE: ValidationRule;
+//# sourceMappingURL=naming.d.ts.map

package/dist/check/rules/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../../src/check/rules/naming.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,aAAa,CAAC;AAsFrB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,EAAE,cA0H/B,CAAC"}