@rigour-labs/core 3.0.2 → 3.0.4

package/dist/gates/phantom-apis.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Phantom APIs Gate
+ *
+ * Detects calls to non-existent methods/properties on known stdlib modules.
+ * AI models confidently generate method names that look correct but don't exist —
+ * e.g. fs.readFileAsync(), path.combine(), crypto.generateHash().
+ *
+ * This is the #2 most dangerous AI hallucination after package hallucination.
+ * Unlike type checkers, this gate catches phantom APIs even in plain JS, Python,
+ * and other dynamically-typed languages where the call would silently fail at runtime.
+ *
+ * Supported languages:
+ *   JS/TS  — Node.js 22.x builtins (fs, path, crypto, http, os, child_process, etc.)
+ *   Python — stdlib modules (os, json, sys, re, datetime, pathlib, subprocess, etc.)
+ *   Go     — Common hallucinated stdlib patterns (strings vs bytes, os vs io, etc.)
+ *   C#     — Common .NET hallucinated APIs (LINQ, File I/O, string methods)
+ *   Java   — Common hallucinated JDK APIs (Collections, String, Stream, Files)
+ *
+ * @since v3.0.0
+ * @since v3.0.3 — Go, C#, Java pattern-based detection added
+ */
+import { Gate, GateContext } from './base.js';
+import { Failure, Provenance } from '../types/index.js';
+export interface PhantomApiCall {
+    file: string;
+    line: number;
+    module: string;
+    method: string;
+    reason: string;
+}
+export interface PhantomApisConfig {
+    enabled?: boolean;
+    check_node?: boolean;
+    check_python?: boolean;
+    check_go?: boolean;
+    check_csharp?: boolean;
+    check_java?: boolean;
+    ignore_patterns?: string[];
+}
+export declare class PhantomApisGate extends Gate {
+    private config;
+    constructor(config?: PhantomApisConfig);
+    protected get provenance(): Provenance;
+    run(context: GateContext): Promise<Failure[]>;
+    /**
+     * Node.js stdlib method verification.
+     * For each known module, we maintain the actual exported methods.
+     * Any call like fs.readFileAsync() that doesn't match is flagged.
+     */
+    private checkNodePhantomApis;
+    /**
+     * Python stdlib method verification.
+     */
+    private checkPythonPhantomApis;
+    /** Suggest the closest real method name (Levenshtein distance ≤ 3) */
+    private suggestNodeMethod;
+    private suggestPythonMethod;
+    private findClosest;
+    private levenshtein;
+    /**
+     * Go phantom API detection — pattern-based.
+     * AI commonly hallucinates Python/JS-style method names on Go packages.
+     * e.g. strings.Contains() exists, but strings.includes() doesn't.
+     */
+    private checkGoPhantomApis;
+    /**
+     * C# phantom API detection — pattern-based.
+     * AI hallucinates Java/Python-style method names on .NET types.
+     */
+    private checkCSharpPhantomApis;
+    /**
+     * Java/Kotlin phantom API detection — pattern-based.
+     * AI hallucinates Python/JS-style APIs on JDK classes.
+     */
+    private checkJavaPhantomApis;
+    private escapeRegex;
+}