boperators 0.1.0

package/dist/cjs/lib/operatorSymbols.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorSymbols = exports.Operator = void 0;
+/**
+ * Designed for internal use to ensure consistency.
+ */
+var Operator;
+(function (Operator) {
+    Operator["PLUS"] = "+";
+    Operator["PLUS_EQUALS"] = "+=";
+    Operator["MINUS"] = "-";
+    Operator["MINUS_EQUALS"] = "-=";
+    Operator["MULTIPLY"] = "*";
+    Operator["MULTIPLY_EQUALS"] = "*=";
+    Operator["DIVIDE"] = "/";
+    Operator["DIVIDE_EQUALS"] = "/=";
+    Operator["GREATER_THAN"] = ">";
+    Operator["GREATER_THAN_EQUAL_TO"] = ">=";
+    Operator["LESS_THAN"] = "<";
+    Operator["LESS_THAN_EQUAL_TO"] = "<=";
+    Operator["MODULO"] = "%";
+    Operator["MODULO_EQUALS"] = "%=";
+    Operator["EQUALS"] = "==";
+    Operator["STRICT_EQUALS"] = "===";
+    Operator["NOT_EQUALS"] = "!=";
+    Operator["STRICT_NOT_EQUALS"] = "!==";
+    Operator["AND"] = "&&";
+    Operator["AND_EQUALS"] = "&&=";
+    Operator["OR"] = "||";
+    Operator["OR_EQUALS"] = "||=";
+    Operator["NULLISH"] = "??";
+    Operator["NOT"] = "!";
+    Operator["BITWISE_NOT"] = "~";
+    Operator["INCREMENT"] = "++";
+    Operator["DECREMENT"] = "--";
+})(Operator || (exports.Operator = Operator = {}));
+exports.operatorSymbols = Object.values(Operator);

package/dist/esm/core/BopConfig.d.ts

@@ -0,0 +1,34 @@
+export type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+export interface BopLogger {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+}
+export interface BopConfig {
+    errorOnWarning: boolean;
+    logLevel: LogLevel;
+    logger: BopLogger;
+}
+/**
+ * Serialisable subset of {@link BopConfig} — the shape of `.bopconf.json`.
+ */
+export interface BopConfFile {
+    errorOnWarning?: boolean;
+    logLevel?: LogLevel;
+}
+export declare class ConsoleLogger implements BopLogger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+export interface LoadConfigOptions {
+    /** Directory to start searching for `.bopconf.json` (default: `process.cwd()`). */
+    searchDir?: string;
+    /** Programmatic overrides applied on top of file config (e.g. CLI flags, plugin config). */
+    overrides?: Partial<BopConfFile>;
+    /** Custom logger implementation (e.g. TS language server logger). */
+    logger?: BopLogger;
+}
+export declare function loadConfig(options?: LoadConfigOptions): BopConfig;

package/dist/esm/core/BopConfig.js

@@ -0,0 +1,65 @@
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG_FILE_NAME = ".bopconf.json";
+// ----- ConsoleLogger -----
+export class ConsoleLogger {
+    debug(msg) {
+        console.debug(`[boperators] ${msg}`);
+    }
+    info(msg) {
+        console.log(`[boperators] ${msg}`);
+    }
+    warn(msg) {
+        console.warn(`[boperators] ${msg}`);
+    }
+    error(msg) {
+        console.error(`[boperators] ${msg}`);
+    }
+}
+// ----- Filtered logger -----
+const LOG_LEVELS = ["debug", "info", "warn", "error", "silent"];
+function createFilteredLogger(inner, level) {
+    const minIndex = LOG_LEVELS.indexOf(level);
+    const noop = () => { };
+    return {
+        debug: minIndex <= 0 ? inner.debug.bind(inner) : noop,
+        info: minIndex <= 1 ? inner.info.bind(inner) : noop,
+        warn: minIndex <= 2 ? inner.warn.bind(inner) : noop,
+        error: minIndex <= 3 ? inner.error.bind(inner) : noop,
+    };
+}
+// ----- Config file discovery -----
+function findConfigFile(startDir) {
+    let dir = path.resolve(startDir);
+    while (true) {
+        const candidate = path.join(dir, CONFIG_FILE_NAME);
+        try {
+            const content = fs.readFileSync(candidate, "utf-8");
+            return JSON.parse(content);
+        }
+        catch (_a) {
+            // File not found or invalid JSON — keep walking up
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return {};
+}
+const DEFAULTS = {
+    errorOnWarning: false,
+    logLevel: "info",
+};
+export function loadConfig(options) {
+    var _a, _b;
+    const fileConfig = findConfigFile((_a = options === null || options === void 0 ? void 0 : options.searchDir) !== null && _a !== void 0 ? _a : process.cwd());
+    const merged = Object.assign(Object.assign(Object.assign({}, DEFAULTS), fileConfig), options === null || options === void 0 ? void 0 : options.overrides);
+    const baseLogger = (_b = options === null || options === void 0 ? void 0 : options.logger) !== null && _b !== void 0 ? _b : new ConsoleLogger();
+    const logger = createFilteredLogger(baseLogger, merged.logLevel);
+    return {
+        errorOnWarning: merged.errorOnWarning,
+        logLevel: merged.logLevel,
+        logger,
+    };
+}

package/dist/esm/core/ErrorManager.d.ts

@@ -0,0 +1,90 @@
+import type { BopConfig } from "./BopConfig.js";
+/**
+ * Stores information about an error or warning for later use.
+ */
+export declare class ErrorDescription {
+    readonly errorMessage: string;
+    readonly filePath: string;
+    readonly lineNumber: number;
+    readonly codeText: string;
+    /**
+     * The base filename where the error occurred,
+     * so we don't need the entire filepath.
+     */
+    readonly fileName: string;
+    /**
+     * Create an ErrorDescription.
+     *
+     * @param errorMessage Custom message text describing the error.
+     * @param filePath Error file path.
+     * @param lineNumber Error line number in its file.
+     * @param codeText Code relevant to the error.q
+     */
+    constructor(errorMessage: string, filePath: string, lineNumber: number, codeText: string);
+    toString(): string;
+}
+/**
+ * Stores errors and warnings in a way that means
+ * they can be logged or thrown at a later point.
+ */
+export declare class ErrorManager {
+    /**
+     * Array of warnings.
+     */
+    private _warnings;
+    /**
+     * Array of errors.
+     */
+    private _errors;
+    /**
+     * Whether or not warnings will cause this to throw.
+     */
+    private readonly _errorOnWarning;
+    private readonly _config;
+    constructor(config: BopConfig);
+    /**
+     * Add an ErrorDescription or a string as a "warning",
+     * meaning it will not throw unless `errorOnWarning` is true.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addWarning(description: ErrorDescription | string): void;
+    /**
+     * Add an ErrorDescription or a string as an "error",
+     * meaning it will throw when checked.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addError(description: ErrorDescription | string): void;
+    /**
+     * Gets all warnings as a single string, separated by newlines.
+     * @returns String of all warnings.
+     */
+    getWarningString(): string;
+    /**
+     * Gets all errors as a single string, separated by newlines.
+     * @returns String of all errors.
+     */
+    getErrorsString(): string;
+    /**
+     * Throws if there are any errors currently registered in the ErrorManager.
+     * If `errorOnWarning` is true then it will also throw if there are warnings.
+     */
+    throwIfErrors(): void;
+    /**
+     * Will throw if there are any errors, or if there are warnings and `errorOnWarning` is true.
+     * If it does not throw then it will log all wanrnings to the console.
+     * @param clearSelf If true, all warnings will be cleared after logging.
+     */
+    throwIfErrorsElseLogWarnings(clearSelf?: boolean): void;
+    /**
+     * Clear out registered warnings to prevent duplicate logging.
+     */
+    clearWarnings(): void;
+    /**
+     * Clear out registered errors.
+     */
+    clearErrors(): void;
+    /**
+     * Clear all registered errors and warnings.
+     */
+    clear(): void;
+}

package/dist/esm/core/ErrorManager.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+/**
+ * Stores information about an error or warning for later use.
+ */
+export class ErrorDescription {
+    /**
+     * Create an ErrorDescription.
+     *
+     * @param errorMessage Custom message text describing the error.
+     * @param filePath Error file path.
+     * @param lineNumber Error line number in its file.
+     * @param codeText Code relevant to the error.q
+     */
+    constructor(errorMessage, filePath, lineNumber, codeText) {
+        this.errorMessage = errorMessage;
+        this.filePath = filePath;
+        this.lineNumber = lineNumber;
+        this.codeText = codeText;
+        this.fileName = path.basename(filePath);
+    }
+    toString() {
+        return `${this.fileName}:${this.lineNumber}: ${this.errorMessage}\n${this.codeText}\n`;
+    }
+}
+/**
+ * Stores errors and warnings in a way that means
+ * they can be logged or thrown at a later point.
+ */
+export class ErrorManager {
+    constructor(config) {
+        /**
+         * Array of warnings.
+         */
+        this._warnings = [];
+        /**
+         * Array of errors.
+         */
+        this._errors = [];
+        this._config = config;
+        this._errorOnWarning = config.errorOnWarning;
+    }
+    /**
+     * Add an ErrorDescription or a string as a "warning",
+     * meaning it will not throw unless `errorOnWarning` is true.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addWarning(description) {
+        this._warnings.push(description);
+    }
+    /**
+     * Add an ErrorDescription or a string as an "error",
+     * meaning it will throw when checked.
+     * @param description Either a string describing the error or a {@link ErrorDescription} instance.
+     */
+    addError(description) {
+        this._errors.push(description);
+    }
+    /**
+     * Gets all warnings as a single string, separated by newlines.
+     * @returns String of all warnings.
+     */
+    getWarningString() {
+        return this._warnings.map((warning) => warning.toString()).join("\n");
+    }
+    /**
+     * Gets all errors as a single string, separated by newlines.
+     * @returns String of all errors.
+     */
+    getErrorsString() {
+        return this._errors.map((error) => error.toString()).join("\n");
+    }
+    /**
+     * Throws if there are any errors currently registered in the ErrorManager.
+     * If `errorOnWarning` is true then it will also throw if there are warnings.
+     */
+    throwIfErrors() {
+        const shouldThrow = this._errors.length > 0 ||
+            (this._errorOnWarning && this._warnings.length > 0);
+        if (!shouldThrow)
+            return;
+        const errorString = this.getErrorsString() +
+            (this._errorOnWarning ? this.getWarningString() : "");
+        throw new Error(errorString);
+    }
+    /**
+     * Will throw if there are any errors, or if there are warnings and `errorOnWarning` is true.
+     * If it does not throw then it will log all wanrnings to the console.
+     * @param clearSelf If true, all warnings will be cleared after logging.
+     */
+    throwIfErrorsElseLogWarnings(clearSelf = true) {
+        this.throwIfErrors();
+        if (this._warnings.length > 0) {
+            this._config.logger.warn(this.getWarningString());
+        }
+        if (clearSelf) {
+            this.clearWarnings();
+        }
+    }
+    /**
+     * Clear out registered warnings to prevent duplicate logging.
+     */
+    clearWarnings() {
+        this._warnings = [];
+    }
+    /**
+     * Clear out registered errors.
+     */
+    clearErrors() {
+        this._errors = [];
+    }
+    /**
+     * Clear all registered errors and warnings.
+     */
+    clear() {
+        this._errors = [];
+        this._warnings = [];
+    }
+}

package/dist/esm/core/OverloadInjector.d.ts

@@ -0,0 +1,33 @@
+import { SourceFile, type Project as TsMorphProject } from "ts-morph";
+import type { BopLogger } from "./BopConfig";
+import type { OverloadStore } from "./OverloadStore";
+import { SourceMap } from "./SourceMap";
+export type TransformResult = {
+    /** The mutated ts-morph SourceFile (same reference as input). */
+    sourceFile: SourceFile;
+    /** The full text after transformation. */
+    text: string;
+    /** Bidirectional source map between original and transformed text. */
+    sourceMap: SourceMap;
+};
+export declare class OverloadInjector {
+    /**
+     * TS Morph project.
+     */
+    private readonly _project;
+    /**
+     * Overload store.
+     */
+    private readonly _overloadStore;
+    private readonly _logger;
+    constructor(
+    /**
+     * TS Morph project.
+     */
+    _project: TsMorphProject, 
+    /**
+     * Overload store.
+     */
+    _overloadStore: OverloadStore, logger: BopLogger);
+    overloadFile(file: string | SourceFile): TransformResult;
+}

package/dist/esm/core/OverloadInjector.js

@@ -0,0 +1,129 @@
+import path from "node:path";
+import { SourceFile, SyntaxKind, } from "ts-morph";
+import { ensureImportedName } from "./helpers/ensureImportedName";
+import { getModuleSpecifier } from "./helpers/getModuleSpecifier";
+import { resolveExpressionType } from "./helpers/resolveExpressionType";
+import { isOperatorSyntaxKind, isPostfixUnaryOperatorSyntaxKind, isPrefixUnaryOperatorSyntaxKind, } from "./operatorMap";
+import { SourceMap } from "./SourceMap";
+export class OverloadInjector {
+    constructor(
+    /**
+     * TS Morph project.
+     */
+    _project, 
+    /**
+     * Overload store.
+     */
+    _overloadStore, logger) {
+        this._project = _project;
+        this._overloadStore = _overloadStore;
+        this._logger = logger;
+    }
+    overloadFile(file) {
+        const sourceFile = file instanceof SourceFile
+            ? file
+            : this._project.getSourceFileOrThrow(file);
+        const fileName = path.basename(sourceFile.getFilePath());
+        const originalText = sourceFile.getFullText();
+        let transformCount = 0;
+        // Process one innermost binary expression per iteration,
+        // re-fetching descendants each time so types resolve correctly
+        // after each transformation and AST references stay fresh.
+        let changed = true;
+        while (changed) {
+            changed = false;
+            // Reverse DFS pre-order → innermost expressions first
+            const binaryExpressions = sourceFile
+                .getDescendantsOfKind(SyntaxKind.BinaryExpression)
+                .reverse();
+            for (const expression of binaryExpressions) {
+                const operatorKind = expression.getOperatorToken().getKind();
+                if (!isOperatorSyntaxKind(operatorKind))
+                    continue;
+                const lhs = expression.getLeft();
+                const leftType = resolveExpressionType(lhs);
+                const rhs = expression.getRight();
+                const rightType = resolveExpressionType(rhs);
+                const overloadDesc = this._overloadStore.findOverload(operatorKind, leftType, rightType);
+                if (!overloadDesc)
+                    continue;
+                const { className: classNameRaw, classFilePath, operatorString, index, isStatic, } = overloadDesc;
+                // Look up the fresh ClassDeclaration from the project
+                const classSourceFile = this._project.getSourceFileOrThrow(classFilePath);
+                const classDecl = classSourceFile.getClassOrThrow(classNameRaw);
+                // Ensure class is imported, get its textual name
+                const classModuleSpecifier = getModuleSpecifier(sourceFile, classSourceFile);
+                const className = ensureImportedName(sourceFile, classDecl.getSymbol(), classModuleSpecifier);
+                // Build the text code to replace the binary operator with the overload call
+                const overloadCall = isStatic
+                    ? `${className}["${operatorString}"][${index}](${lhs.getText()}, ${rhs.getText()})`
+                    : `${lhs.getText()}["${operatorString}"][${index}].call(${lhs.getText()}, ${rhs.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break; // re-fetch descendants after each mutation
+            }
+        }
+        // Process prefix unary expressions (-x, +x, !x, ~x)
+        changed = true;
+        while (changed) {
+            changed = false;
+            const prefixExpressions = sourceFile
+                .getDescendantsOfKind(SyntaxKind.PrefixUnaryExpression)
+                .reverse();
+            for (const expression of prefixExpressions) {
+                const operatorKind = expression.getOperatorToken();
+                if (!isPrefixUnaryOperatorSyntaxKind(operatorKind))
+                    continue;
+                const operand = expression.getOperand();
+                const operandType = resolveExpressionType(operand);
+                const overloadDesc = this._overloadStore.findPrefixUnaryOverload(operatorKind, operandType);
+                if (!overloadDesc)
+                    continue;
+                const { className: classNameRaw, classFilePath, operatorString, index, } = overloadDesc;
+                const classSourceFile = this._project.getSourceFileOrThrow(classFilePath);
+                const classDecl = classSourceFile.getClassOrThrow(classNameRaw);
+                const classModuleSpecifier = getModuleSpecifier(sourceFile, classSourceFile);
+                const className = ensureImportedName(sourceFile, classDecl.getSymbol(), classModuleSpecifier);
+                const overloadCall = `${className}["${operatorString}"][${index}](${operand.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break;
+            }
+        }
+        // Process postfix unary expressions (x++, x--)
+        changed = true;
+        while (changed) {
+            changed = false;
+            const postfixExpressions = sourceFile
+                .getDescendantsOfKind(SyntaxKind.PostfixUnaryExpression)
+                .reverse();
+            for (const expression of postfixExpressions) {
+                const operatorKind = expression.getOperatorToken();
+                if (!isPostfixUnaryOperatorSyntaxKind(operatorKind))
+                    continue;
+                const operand = expression.getOperand();
+                const operandType = resolveExpressionType(operand);
+                const overloadDesc = this._overloadStore.findPostfixUnaryOverload(operatorKind, operandType);
+                if (!overloadDesc)
+                    continue;
+                const { operatorString, index } = overloadDesc;
+                const overloadCall = `${operand.getText()}["${operatorString}"][${index}].call(${operand.getText()})`;
+                this._logger.debug(`${fileName}: ${expression.getText()} => ${overloadCall}`);
+                expression.replaceWithText(overloadCall);
+                transformCount++;
+                changed = true;
+                break;
+            }
+        }
+        if (transformCount > 0) {
+            this._logger.debug(`${fileName}: ${transformCount} expression${transformCount === 1 ? "" : "s"} transformed`);
+        }
+        const text = sourceFile.getFullText();
+        const sourceMap = new SourceMap(originalText, text);
+        return { sourceFile, text, sourceMap };
+    }
+}

package/dist/esm/core/OverloadStore.d.ts

@@ -0,0 +1,114 @@
+import { SourceFile, type Project as TsMorphProject } from "ts-morph";
+import type { BopLogger } from "./BopConfig";
+import { type ErrorManager } from "./ErrorManager";
+import { type OperatorSyntaxKind, type PostfixUnaryOperatorSyntaxKind, type PrefixUnaryOperatorSyntaxKind } from "./operatorMap";
+/**
+ * Name of the type of node on the left-hand side of the operator.
+ * Exists purely to make it clear what's where in the map typings.
+ */
+type LhsTypeName = string;
+/**
+ * Name of the type of node on the right-hand side of the operator.
+ * Exists purely to make it clear what's where in the map typings.
+ */
+type RhsTypeName = string;
+/**
+ * Information about an overload so that we can
+ * substitute it over binary expressions.
+ */
+export type OverloadDescription = {
+    isStatic: boolean;
+    className: string;
+    classFilePath: string;
+    operatorString: string;
+    index: number;
+    returnType: string;
+};
+/**
+ * A flat representation of a registered overload, suitable for
+ * external consumption (e.g. MCP server, tooling).
+ */
+export type OverloadInfo = {
+    kind: "binary" | "prefixUnary" | "postfixUnary";
+    className: string;
+    classFilePath: string;
+    operatorString: string;
+    index: number;
+    isStatic: boolean;
+    /** LHS type name (binary overloads only). */
+    lhsType?: string;
+    /** RHS type name (binary overloads only). */
+    rhsType?: string;
+    /** Operand type name (unary overloads only). */
+    operandType?: string;
+};
+export declare class OverloadStore extends Map<OperatorSyntaxKind, Map<LhsTypeName, Map<RhsTypeName, OverloadDescription>>> {
+    private readonly _project;
+    private readonly _errorManager;
+    private readonly _parsedFiles;
+    /** Tracks which map entries came from which file, for targeted invalidation. */
+    private readonly _fileEntries;
+    /** Cache for type hierarchy chains: type name → [self, parent, grandparent, ...] */
+    private readonly _typeChainCache;
+    /** Storage for prefix unary overloads: operator → operandType → description */
+    private readonly _prefixUnaryOverloads;
+    /** Storage for postfix unary overloads: operator → operandType → description */
+    private readonly _postfixUnaryOverloads;
+    /** Tracks which prefix unary entries came from which file, for targeted invalidation. */
+    private readonly _prefixUnaryFileEntries;
+    /** Tracks which postfix unary entries came from which file, for targeted invalidation. */
+    private readonly _postfixUnaryFileEntries;
+    private readonly _logger;
+    constructor(project: TsMorphProject, errorManager: ErrorManager, logger: BopLogger);
+    /**
+     * Looks up an overload description for the given operator kind and
+     * LHS/RHS type pair. Walks up the class hierarchy for both sides
+     * when an exact match isn't found.
+     */
+    findOverload(operatorKind: OperatorSyntaxKind, lhsType: string, rhsType: string): OverloadDescription | undefined;
+    /**
+     * Looks up a prefix unary overload description for the given operator kind
+     * and operand type. Walks up the class hierarchy when an exact match isn't found.
+     */
+    findPrefixUnaryOverload(operatorKind: PrefixUnaryOperatorSyntaxKind, operandType: string): OverloadDescription | undefined;
+    /**
+     * Looks up a postfix unary overload description for the given operator kind
+     * and operand type. Walks up the class hierarchy when an exact match isn't found.
+     */
+    findPostfixUnaryOverload(operatorKind: PostfixUnaryOperatorSyntaxKind, operandType: string): OverloadDescription | undefined;
+    /**
+     * Returns a flat array of all registered overloads (binary, prefix unary,
+     * and postfix unary) with clean type names.
+     */
+    getAllOverloads(): OverloadInfo[];
+    /**
+     * Removes all overload entries that originated from the given file
+     * and marks it as unparsed so it will be re-scanned on the next call
+     * to `addOverloadsFromFile`.
+     *
+     * @returns `true` if the file had any overload entries (meaning files
+     * that were transformed using those overloads may now be stale).
+     */
+    invalidateFile(filePath: string): boolean;
+    addOverloadsFromFile(file: string | SourceFile): void;
+    private _addBinaryOverload;
+    private _addPrefixUnaryOverload;
+    private _addPostfixUnaryOverload;
+    /**
+     * Extracts overload info from a property's type annotation instead of its
+     * initializer. This handles `.d.ts` declaration files where the array
+     * literal (`= [...] as const`) has been replaced by a readonly tuple type.
+     */
+    private _addOverloadsFromTypeAnnotation;
+    /**
+     * Returns the type hierarchy chain for a given type name:
+     * [self, parent, grandparent, ...]. Primitives like "number"
+     * return a single-element array.
+     */
+    private _getTypeChain;
+    private _minifyString;
+    /** Strips `import("...").` prefixes from fully-qualified type names for readable logs. */
+    private _shortTypeName;
+    toString(): string;
+}
+export {};