@rcrsr/rill 0.1.0 → 0.2.0

package/dist/check/rules/naming.js

@@ -0,0 +1,167 @@
+/**
+ * Naming Convention Rules
+ * Enforces snake_case naming for variables, parameters, and dict keys.
+ */
+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) {
+    // 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) {
+    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, name, kind, context, fix) {
+    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/16_conventions.md:10-53
+ */
+export const NAMING_SNAKE_CASE = {
+    code: 'NAMING_SNAKE_CASE',
+    category: 'naming',
+    severity: 'error',
+    nodeTypes: ['ClosureParam', 'DictEntry', 'Capture'],
+    validate(node, context) {
+        switch (node.type) {
+            case 'ClosureParam': {
+                const paramNode = node;
+                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;
+                const key = entryNode.key;
+                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;
+                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, context) {
+        let name = null;
+        let range = node.span;
+        // Extract name and determine replacement range
+        switch (node.type) {
+            case 'ClosureParam': {
+                const paramNode = node;
+                name = paramNode.name;
+                break;
+            }
+            case 'DictEntry': {
+                const entryNode = node;
+                name = entryNode.key;
+                // For dict entries, replace only the key portion before the colon
+                break;
+            }
+            case 'Capture': {
+                const captureNode = node;
+                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,
+        };
+    },
+};
+//# sourceMappingURL=naming.js.map

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

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

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

@@ -0,0 +1,28 @@
+/**
+ * String Handling Convention Rules
+ * Enforces string handling best practices from docs/16_conventions.md:318-352.
+ */
+import type { ValidationRule } from '../types.js';
+/**
+ * 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/16_conventions.md:333-345
+ */
+export declare const USE_EMPTY_METHOD: ValidationRule;
+//# sourceMappingURL=strings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../../src/check/rules/strings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,aAAa,CAAC;AAYrB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,EAAE,cA2C9B,CAAC"}

package/dist/check/rules/strings.js

@@ -0,0 +1,80 @@
+/**
+ * String Handling Convention Rules
+ * Enforces string handling best practices from docs/16_conventions.md:318-352.
+ */
+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/16_conventions.md:333-345
+ */
+export const USE_EMPTY_METHOD = {
+    code: 'USE_EMPTY_METHOD',
+    category: 'strings',
+    severity: 'warning',
+    nodeTypes: ['BinaryExpr'],
+    validate(node, context) {
+        const binaryNode = node;
+        // Only check equality operators
+        if (binaryNode.op !== '==' && binaryNode.op !== '!=') {
+            return [];
+        }
+        // left and right are PostfixExpr - check their primaries
+        const left = binaryNode.left;
+        const right = binaryNode.right;
+        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) {
+    if (node.type !== 'StringLiteral') {
+        return false;
+    }
+    const stringNode = node;
+    // 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;
+}
+//# sourceMappingURL=strings.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strings.js","sourceRoot":"","sources":["../../../src/check/rules/strings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,+DAA+D;AAC/D,wBAAwB;AACxB,+DAA+D;AAE/D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,IAAI,EAAE,kBAAkB;IACxB,QAAQ,EAAE,SAAS;IACnB,QAAQ,EAAE,SAAS;IACnB,SAAS,EAAE,CAAC,YAAY,CAAC;IAEzB,QAAQ,CAAC,IAAa,EAAE,OAA0B;QAChD,MAAM,UAAU,GAAG,IAAsB,CAAC;QAE1C,gCAAgC;QAChC,IAAI,UAAU,CAAC,EAAE,KAAK,IAAI,IAAI,UAAU,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;YACrD,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,yDAAyD;QACzD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAW,CAAC;QACpC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAY,CAAC;QAEtC,MAAM,WAAW,GACf,IAAI,CAAC,IAAI,KAAK,aAAa,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpE,MAAM,YAAY,GAChB,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEtE,IAAI,WAAW,IAAI,YAAY,EAAE,CAAC;YAChC,MAAM,eAAe,GAAG,UAAU,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC;YAE1E,OAAO;gBACL;oBACE,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,KAAK;oBAC/B,QAAQ,EAAE,SAAS;oBACnB,IAAI,EAAE,kBAAkB;oBACxB,OAAO,EAAE,OAAO,eAAe,oDAAoD;oBACnF,OAAO,EAAE,kBAAkB,CACzB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAC1B,OAAO,CAAC,MAAM,CACf;oBACD,GAAG,EAAE,IAAI,EAAE,mDAAmD;iBAC/D;aACF,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;CACF,CAAC;AAEF;;GAEG;AACH,SAAS,oBAAoB,CAAC,IAAa;IACzC,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,UAAU,GAAG,IAAyB,CAAC;IAE7C,2DAA2D;IAC3D,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACjC,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,CAAC;IACjD,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * Type Safety Convention Rules
+ * Enforces type annotation best practices from docs/16_conventions.md:288-316.
+ */
+import type { ValidationRule } from '../types.js';
+/**
+ * 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/16_conventions.md:305-315
+ */
+export declare const UNNECESSARY_ASSERTION: ValidationRule;
+/**
+ * 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/16_conventions.md:307-311
+ */
+export declare const VALIDATE_EXTERNAL: ValidationRule;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/check/rules/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,cAAc,EAKf,MAAM,aAAa,CAAC;AAQrB;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAwFnC,CAAC;AA4BF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAuC/B,CAAC"}

package/dist/check/rules/types.js

@@ -0,0 +1,162 @@
+/**
+ * Type Safety Convention Rules
+ * Enforces type annotation best practices from docs/16_conventions.md:288-316.
+ */
+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/16_conventions.md:305-315
+ */
+export const UNNECESSARY_ASSERTION = {
+    code: 'UNNECESSARY_ASSERTION',
+    category: 'types',
+    severity: 'info',
+    nodeTypes: ['TypeAssertion'],
+    validate(node, context) {
+        const assertionNode = node;
+        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, context) {
+        const assertionNode = node;
+        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) {
+    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/16_conventions.md:307-311
+ */
+export const VALIDATE_EXTERNAL = {
+    code: 'VALIDATE_EXTERNAL',
+    category: 'types',
+    severity: 'info',
+    nodeTypes: ['HostCall'],
+    validate(node, context) {
+        const hostCallNode = node;
+        const functionName = hostCallNode.name;
+        // 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 [];
+        }
+        // Check if the result is immediately asserted
+        // This would require checking the parent node context
+        // For now, we'll provide a general recommendation
+        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
+            },
+        ];
+    },
+};
+//# sourceMappingURL=types.js.map

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

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

package/dist/check/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Check Types
+ * Type definitions for the rill-check static analysis tool.
+ */
+import type { SourceLocation, SourceSpan, ScriptNode, NodeType, ASTNode } from '../types.js';
+/** Diagnostic severity levels */
+export type Severity = 'error' | 'warning' | 'info';
+/** Rule state configuration */
+export type RuleState = 'on' | 'off' | 'warn';
+/**
+ * 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;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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;
+}
+/** 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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/check/types.d.ts.map

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

package/dist/check/types.js

@@ -0,0 +1,6 @@
+/**
+ * Check Types
+ * Type definitions for the rill-check static analysis tool.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/check/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/check/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/check/validator.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Script Validator
+ * Orchestrates validation by traversing AST and invoking enabled rules.
+ */
+import type { ScriptNode } from '../types.js';
+import type { CheckConfig, Diagnostic } from './types.js';
+/**
+ * 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 declare function validateScript(ast: ScriptNode, source: string, config: CheckConfig): Diagnostic[];
+//# sourceMappingURL=validator.d.ts.map

package/dist/check/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/check/validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAQ7E;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,UAAU,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,UAAU,EAAE,CAiDd"}