@nodesecure/js-x-ray/dist/VariableTracer.d.ts

JavaScript AST XRay analysis

import { EventEmitter } from "node:events";
import { type ESTree } from "meriyah";
export interface DataIdentifierOptions {
    /**
     * If true, removes global identifier prefixes (globalThis, window, etc.)
     * @default false
     * @example "globalThis.require" becomes "require"
     */
    removeGlobalIdentifier?: boolean;
}
export interface SourceTraced {
    /**
     * If true, assignments to other variables will also be traced
     * @default false
     * @example const r = require; // 'r' will also be traced
     */
    followConsecutiveAssignment?: boolean;
    /**
     * If true, return values assigned to variables will be traced
     * @default false
     * @example const result = someTracedFunction();
     */
    followReturnValueAssignement?: boolean;
    /**
     * Module name to associate with this traced identifier
     * Used to track if the module has been imported
     * @default null
     */
    moduleName?: string | null;
    /**
     * Human-readable name for this traced identifier
     * @default identifierOrMemberExpr
     */
    name?: string;
}
export interface AssignmentMemory {
    /**
     * Type of assignment:
     * - "AliasBinding": Direct variable assignment (const x = require)
     * - "ReturnValueAssignment": Assignment from function return (const x = require())
     */
    type: "AliasBinding" | "ReturnValueAssignment";
    /**
     * Name of the variable that received the assignment
     */
    name: string;
}
export interface Traced extends Required<SourceTraced> {
    identifierOrMemberExpr: string;
    assignmentMemory: AssignmentMemory[];
}
export interface TracedIdentifierReport {
    /**
     * Human-readable name of the traced identifier
     */
    name: string;
    /**
     * Full identifier or member expression being traced
     * @example "process.mainModule.require"
     */
    identifierOrMemberExpr: string;
    /**
     * History of assignments made to this traced identifier
     */
    assignmentMemory: AssignmentMemory[];
}
export interface AssignmentEventPayload {
    name: string;
    identifierOrMemberExpr: string;
    id: string;
    location: ESTree.SourceLocation | null | undefined;
}
export interface ImportEventPayload {
    moduleName: string;
    value: string;
    location: ESTree.SourceLocation | null | undefined;
}
export interface LiteralIdentifier {
    value: string;
    type: "Literal" | "TemplateLiteral";
}
export declare class VariableTracer extends EventEmitter {
    #private;
    static AssignmentEvent: symbol;
    static ImportEvent: symbol;
    literalIdentifiers: Map<string, LiteralIdentifier>;
    importedModules: Set<string>;
    debug(): void;
    enableDefaultTracing(): this;
    /**
     * @example
     * new VariableTracer()
     *  .trace("require", { followConsecutiveAssignment: true })
     *  .trace("process.mainModule")
     */
    trace(identifierOrMemberExpr: string, options?: SourceTraced): this;
    getDataFromIdentifier(identifierOrMemberExpr: string, options?: DataIdentifierOptions): null | TracedIdentifierReport;
    walk(node: ESTree.Node): void;
}
//# sourceMappingURL=VariableTracer.d.ts.map