@rigour-labs/core 4.3.0 → 4.3.1

package/dist/gates/side-effect-helpers.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Side-Effect Analysis Helpers
+ *
+ * Context-aware utilities for smart side-effect detection.
+ * Follows the same architectural patterns as promise-safety-helpers.ts:
+ *   - Scope-aware analysis (brace/indent tracking)
+ *   - Variable binding tracking (pair resource creation with cleanup)
+ *   - Framework detection (React useEffect, Go defer, Python with, etc.)
+ *   - Path overlap analysis (circular file watcher detection)
+ *
+ * These helpers make side-effect detection SMART — instead of asking
+ * "does clearInterval exist anywhere in the file?", we ask
+ * "is the specific timer variable cleaned up in the right scope?"
+ *
+ * @since v4.3.0
+ */
+export type SideEffectLang = 'js' | 'ts' | 'py' | 'go' | 'rs' | 'cs' | 'java' | 'rb';
+export interface SideEffectViolation {
+    rule: string;
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    file: string;
+    line: number;
+    match: string;
+    description: string;
+    hint: string;
+}
+/**
+ * Tracks a resource creation and its expected cleanup.
+ * E.g.: { varName: 'timer', createLine: 5, createCall: 'setInterval' }
+ */
+export interface ResourceBinding {
+    varName: string | null;
+    createLine: number;
+    createCall: string;
+    scopeStart: number;
+    scopeEnd: number;
+}
+export declare const LANG_MAP: Record<string, SideEffectLang>;
+export declare const FILE_GLOBS: string[];
+export declare function stripStrings(line: string): string;
+/**
+ * Find the enclosing function scope for a given line.
+ * Returns { start, end } of the function body.
+ * For module-level code, returns { start: 0, end: lines.length }.
+ *
+ * Follows promise-safety's approach of backward scanning with brace tracking.
+ */
+export declare function findEnclosingFunction(lines: string[], lineIdx: number, lang: SideEffectLang): {
+    start: number;
+    end: number;
+};
+/**
+ * Find the end of a brace-delimited block starting at `start`.
+ */
+export declare function findBlockEndBrace(lines: string[], start: number): number;
+/**
+ * Find the end of an indentation-delimited block (Python).
+ */
+export declare function findBlockEndIndent(lines: string[], start: number): number;
+/**
+ * Extract the variable name from an assignment.
+ * "const timer = setInterval(...)"  → "timer"
+ * "let fd = fs.open(...)"           → "fd"
+ * "self.watcher = chokidar.watch()" → "self.watcher"
+ * "timer := time.NewTicker(...)"    → "timer" (Go)
+ *
+ * Returns null if the call result is NOT stored in a variable.
+ */
+export declare function extractVariableBinding(line: string, lang: SideEffectLang): string | null;
+/**
+ * Check if a specific variable is used in a cleanup call within a scope.
+ *
+ * Unlike the naive "does clearInterval exist in the file?", this checks:
+ * 1. The cleanup function references the specific variable
+ * 2. The cleanup is within the correct scope (same function or cleanup callback)
+ *
+ * Example: for variable "timer" and cleanup patterns [/clearInterval/],
+ * matches: `clearInterval(timer)`, `clearInterval(this.timer)`, `timer.close()`
+ */
+export declare function hasCleanupForVariable(lines: string[], varName: string, scopeStart: number, scopeEnd: number, cleanupPatterns: RegExp[], lang: SideEffectLang): boolean;
+/**
+ * Check if a line is inside a cleanup/teardown context.
+ *
+ * Cleanup contexts where resource cleanup is expected:
+ * - JS/TS: useEffect return function, componentWillUnmount, beforeDestroy, ngOnDestroy, dispose()
+ * - Python: __del__, __exit__, close(), cleanup(), teardown
+ * - Go: defer statement
+ * - Java: finally block, close() method, @PreDestroy
+ * - C#: Dispose(), using block, finalizer
+ * - Ruby: ensure block, at_exit
+ */
+export declare function isInsideCleanupContext(lines: string[], lineIdx: number, lang: SideEffectLang): boolean;
+/**
+ * Check if a timer/resource creation is inside a React useEffect
+ * that returns a cleanup function.
+ *
+ * Pattern:
+ *   useEffect(() => {
+ *     const timer = setInterval(...)  ← creation
+ *     return () => clearInterval(timer)  ← cleanup
+ *   }, [deps])
+ */
+export declare function isInUseEffectWithCleanup(lines: string[], lineIdx: number): boolean;
+/**
+ * Check if a Go resource open is immediately followed by defer close.
+ *
+ * Idiomatic Go:
+ *   f, err := os.Open(path)
+ *   if err != nil { return err }
+ *   defer f.Close()
+ */
+export declare function hasGoDefer(lines: string[], openLine: number, varName: string): boolean;
+/**
+ * Check if a Python open() is inside a `with` statement (context manager).
+ */
+export declare function isPythonWithStatement(line: string): boolean;
+/**
+ * Check if a Java resource open is inside try-with-resources.
+ * Pattern: try (var x = new FileStream(...)) { ... }
+ */
+export declare function isJavaTryWithResources(lines: string[], lineIdx: number): boolean;
+/**
+ * Check if a C# resource is inside a using statement/declaration.
+ * Patterns: `using (var x = ...)` or `using var x = ...` (C# 8+)
+ */
+export declare function isCSharpUsing(line: string): boolean;
+/**
+ * Check if a Ruby File.open uses block form (auto-closes).
+ * Pattern: File.open(path) do |f| ... end
+ *          File.open(path) { |f| ... }
+ */
+export declare function isRubyBlockForm(line: string): boolean;
+/**
+ * Check if a Rust resource is automatically dropped (RAII).
+ * In Rust, all resources are dropped when they go out of scope,
+ * so we only flag resources in unsafe blocks or static/global context.
+ */
+export declare function isRustAutoDropped(lines: string[], lineIdx: number): boolean;
+/**
+ * Extract the path being watched from a file watcher call.
+ * Returns null if path cannot be determined.
+ *
+ * Handles:
+ * - fs.watch('./src', ...)
+ * - chokidar.watch(['./src', './lib'], ...)
+ * - Observer(path=...)
+ * - fsnotify.NewWatcher() + watcher.Add(path)
+ */
+export declare function extractWatchedPath(line: string): string | null;
+/**
+ * Extract write target path from a file write call.
+ * Returns null if path cannot be determined.
+ */
+export declare function extractWritePath(line: string): string | null;
+/**
+ * Check if a write path could trigger a file watcher.
+ *
+ * Smart matching:
+ * - "./src/output.js" is inside watched "./src"
+ * - "./dist/bundle.js" is NOT inside "./src"
+ * - If either path is a variable reference ($var), consider it suspicious
+ * - Exact matches always overlap
+ */
+export declare function pathsOverlap(watchPath: string | null, writePath: string | null): boolean;
+/**
+ * Extract loop body with correct scope tracking.
+ * Uses brace/indent matching (not just "next N lines").
+ */
+export declare function extractLoopBody(lines: string[], loopLine: number, lang: SideEffectLang): {
+    body: string;
+    start: number;
+    end: number;
+};
+/**
+ * Extract all function definitions with their bodies.
+ * Used for recursion detection — need to check if function calls itself
+ * within its own extracted body (not just anywhere in the file).
+ */
+export declare function extractFunctionDefs(lines: string[], lang: SideEffectLang): {
+    name: string;
+    start: number;
+    end: number;
+    params: string;
+}[];
+/**
+ * Check if a function has a base case (return/break before recursive call).
+ * Smart: actually checks that the base case comes BEFORE the recursive call,
+ * not just that both exist somewhere in the body.
+ */
+export declare function hasBaseCase(bodyLines: string[], funcName: string): boolean;
+/**
+ * Check if a function has a depth/limit parameter (implies bounded recursion).
+ * Smarter than just checking for the word "depth" anywhere — checks the
+ * function signature specifically.
+ */
+export declare function hasDepthParameter(funcLine: string): boolean;
+/**
+ * Check if a code block contains I/O operations.
+ * Language-aware: knows which stdlib calls are I/O.
+ */
+export declare function containsIO(body: string, lang: SideEffectLang): boolean;
+/**
+ * Check if a loop body or its preamble contains a retry limit.
+ *
+ * Smart: checks variable declarations before the loop AND inside the loop.
+ * Recognizes both explicit counters and library patterns.
+ */
+export declare function hasRetryLimit(lines: string[], loopLine: number, bodyEnd: number): boolean;
+/**
+ * Check if error handling inside a loop constitutes a retry pattern.
+ * Not just "catch exists" but "catch is followed by continue or the loop wraps the try".
+ */
+export declare function hasCatchWithContinue(body: string, lang: SideEffectLang): boolean;
+/**
+ * Check if a line contains a process spawn call.
+ */
+export declare function isProcessSpawn(line: string, lang: SideEffectLang): RegExpMatchArray | null;
+/**
+ * Check if a line contains a timer creation call.
+ * Returns the timer function name if matched.
+ */
+export declare function isTimerCreation(line: string, lang: SideEffectLang): string | null;
+/**
+ * Get cleanup patterns for timers (language-specific).
+ */
+export declare function getTimerCleanupPatterns(lang: SideEffectLang): RegExp[];
+/**
+ * Get cleanup patterns for spawned processes.
+ */
+export declare function getProcessCleanupPatterns(lang: SideEffectLang): RegExp[];
+/**
+ * Check if a line contains an unbounded loop construct.
+ */
+export declare function isUnboundedLoop(line: string, lang: SideEffectLang): boolean;
+/**
+ * Check if a line creates a file watcher.
+ * Returns the watcher function name if matched.
+ */
+export declare function isFileWatcher(line: string, lang: SideEffectLang): string | null;
+/**
+ * Check if a code body contains file write operations.
+ * Returns the first write call found, or null.
+ */
+export declare function findWriteInBody(body: string, lang: SideEffectLang): string | null;
+/**
+ * Check if a file watcher callback has debounce/throttle protection.
+ */
+export declare function hasDebounceProtection(body: string): boolean;
+/**
+ * Get resource open patterns for lifecycle checking.
+ */
+export declare function isResourceOpen(line: string, lang: SideEffectLang): string | null;
+/**
+ * Get resource close patterns.
+ */
+export declare function getResourceClosePatterns(lang: SideEffectLang): RegExp[];
+/**
+ * Check if an exit/signal handler respawns the process (auto-restart pattern).
+ */
+export declare function isExitHandler(line: string, lang: SideEffectLang): boolean;