boperators 0.1.0

package/dist/esm/core/OverloadStore.js

@@ -0,0 +1,618 @@
+import { Node, SourceFile, SyntaxKind, } from "ts-morph";
+import { operatorSymbols } from "../lib/operatorSymbols";
+import { ErrorDescription } from "./ErrorManager";
+import { getOperatorStringFromProperty } from "./helpers/getOperatorStringFromProperty";
+import { unwrapInitializer } from "./helpers/unwrapInitializer";
+import { comparisonOperators, instanceOperators, operatorMap, postfixUnaryOperatorMap, prefixUnaryOperatorMap, } from "./operatorMap";
+export class OverloadStore extends Map {
+    constructor(project, errorManager, logger) {
+        super();
+        this._parsedFiles = new Set();
+        /** Tracks which map entries came from which file, for targeted invalidation. */
+        this._fileEntries = new Map();
+        /** Cache for type hierarchy chains: type name → [self, parent, grandparent, ...] */
+        this._typeChainCache = new Map();
+        /** Storage for prefix unary overloads: operator → operandType → description */
+        this._prefixUnaryOverloads = new Map();
+        /** Storage for postfix unary overloads: operator → operandType → description */
+        this._postfixUnaryOverloads = new Map();
+        /** Tracks which prefix unary entries came from which file, for targeted invalidation. */
+        this._prefixUnaryFileEntries = new Map();
+        /** Tracks which postfix unary entries came from which file, for targeted invalidation. */
+        this._postfixUnaryFileEntries = new Map();
+        this._project = project;
+        this._errorManager = errorManager;
+        this._logger = logger;
+    }
+    /**
+     * 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, lhsType, rhsType) {
+        const operatorOverloads = this.get(operatorKind);
+        if (!operatorOverloads)
+            return undefined;
+        const lhsChain = this._getTypeChain(lhsType);
+        const rhsChain = this._getTypeChain(rhsType);
+        // Try each combination, most specific types first
+        for (const lhs of lhsChain) {
+            const lhsMap = operatorOverloads.get(lhs);
+            if (!lhsMap)
+                continue;
+            for (const rhs of rhsChain) {
+                const match = lhsMap.get(rhs);
+                if (match)
+                    return match;
+            }
+        }
+        return 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, operandType) {
+        const operatorOverloads = this._prefixUnaryOverloads.get(operatorKind);
+        if (!operatorOverloads)
+            return undefined;
+        const typeChain = this._getTypeChain(operandType);
+        for (const t of typeChain) {
+            const match = operatorOverloads.get(t);
+            if (match)
+                return match;
+        }
+        return 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, operandType) {
+        const operatorOverloads = this._postfixUnaryOverloads.get(operatorKind);
+        if (!operatorOverloads)
+            return undefined;
+        const typeChain = this._getTypeChain(operandType);
+        for (const t of typeChain) {
+            const match = operatorOverloads.get(t);
+            if (match)
+                return match;
+        }
+        return undefined;
+    }
+    /**
+     * Returns a flat array of all registered overloads (binary, prefix unary,
+     * and postfix unary) with clean type names.
+     */
+    getAllOverloads() {
+        const results = [];
+        const sl = this._shortTypeName.bind(this);
+        for (const [_syntaxKind, lhsMap] of this) {
+            for (const [lhsType, rhsMap] of lhsMap) {
+                for (const [rhsType, desc] of rhsMap) {
+                    results.push(Object.assign(Object.assign({ kind: "binary" }, desc), { lhsType: sl(lhsType), rhsType: sl(rhsType) }));
+                }
+            }
+        }
+        for (const [_syntaxKind, operandMap] of this._prefixUnaryOverloads) {
+            for (const [operandType, desc] of operandMap) {
+                results.push(Object.assign(Object.assign({ kind: "prefixUnary" }, desc), { operandType: sl(operandType) }));
+            }
+        }
+        for (const [_syntaxKind, operandMap] of this._postfixUnaryOverloads) {
+            for (const [operandType, desc] of operandMap) {
+                results.push(Object.assign(Object.assign({ kind: "postfixUnary" }, desc), { operandType: sl(operandType) }));
+            }
+        }
+        return results;
+    }
+    /**
+     * 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) {
+        var _a, _b, _c, _d;
+        this._parsedFiles.delete(filePath);
+        this._typeChainCache.clear();
+        let hadEntries = false;
+        const entries = this._fileEntries.get(filePath);
+        if (entries) {
+            for (const { syntaxKind, lhsType, rhsType } of entries) {
+                (_b = (_a = this.get(syntaxKind)) === null || _a === void 0 ? void 0 : _a.get(lhsType)) === null || _b === void 0 ? void 0 : _b.delete(rhsType);
+            }
+            this._fileEntries.delete(filePath);
+            hadEntries = true;
+        }
+        const prefixEntries = this._prefixUnaryFileEntries.get(filePath);
+        if (prefixEntries) {
+            for (const { syntaxKind, operandType } of prefixEntries) {
+                (_c = this._prefixUnaryOverloads.get(syntaxKind)) === null || _c === void 0 ? void 0 : _c.delete(operandType);
+            }
+            this._prefixUnaryFileEntries.delete(filePath);
+            hadEntries = true;
+        }
+        const postfixEntries = this._postfixUnaryFileEntries.get(filePath);
+        if (postfixEntries) {
+            for (const { syntaxKind, operandType } of postfixEntries) {
+                (_d = this._postfixUnaryOverloads.get(syntaxKind)) === null || _d === void 0 ? void 0 : _d.delete(operandType);
+            }
+            this._postfixUnaryFileEntries.delete(filePath);
+            hadEntries = true;
+        }
+        return hadEntries;
+    }
+    addOverloadsFromFile(file) {
+        const sourceFile = file instanceof SourceFile
+            ? file
+            : this._project.getSourceFileOrThrow(file);
+        const filePath = sourceFile.getFilePath();
+        if (this._parsedFiles.has(filePath))
+            return;
+        this._parsedFiles.add(filePath);
+        const classes = sourceFile.getClasses();
+        classes.forEach((classDecl) => {
+            const classType = classDecl.getType().getText();
+            classDecl.getProperties().forEach((property) => {
+                var _a, _b;
+                if (!Node.isPropertyDeclaration(property))
+                    return;
+                const isStatic = property.isStatic();
+                const operatorString = getOperatorStringFromProperty(property);
+                if (!operatorString || !operatorSymbols.includes(operatorString))
+                    return;
+                // Look up the operator in all three maps
+                const binarySyntaxKind = operatorMap[operatorString];
+                const prefixUnarySyntaxKind = prefixUnaryOperatorMap[operatorString];
+                const postfixUnarySyntaxKind = postfixUnaryOperatorMap[operatorString];
+                if (!binarySyntaxKind &&
+                    !prefixUnarySyntaxKind &&
+                    !postfixUnarySyntaxKind)
+                    return;
+                // Property-level static/instance validation.
+                // Determine what this property should be based on the operator kinds it supports.
+                const shouldBeStatic = (binarySyntaxKind != null &&
+                    !instanceOperators.has(binarySyntaxKind)) ||
+                    prefixUnarySyntaxKind != null;
+                const shouldBeInstance = (binarySyntaxKind != null &&
+                    instanceOperators.has(binarySyntaxKind)) ||
+                    postfixUnarySyntaxKind != null;
+                if ((isStatic && !shouldBeStatic) || (!isStatic && !shouldBeInstance)) {
+                    this._errorManager.addWarning(new ErrorDescription(`Expected overload for operator ${operatorString} ` +
+                        `to be ${isStatic ? "a static" : "an instance"} field.`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), property.getText().split("\n")[0]));
+                    return;
+                }
+                const rawInitializer = property.getInitializer();
+                // No initializer — try type-annotation-based extraction (.d.ts files)
+                if (!rawInitializer) {
+                    this._addOverloadsFromTypeAnnotation(property, classDecl, classType, filePath, isStatic, operatorString, binarySyntaxKind, prefixUnarySyntaxKind, postfixUnarySyntaxKind);
+                    return;
+                }
+                const hasAsConst = Node.isAsExpression(rawInitializer) &&
+                    ((_a = rawInitializer.getTypeNode()) === null || _a === void 0 ? void 0 : _a.getText()) === "const";
+                const initializer = unwrapInitializer(rawInitializer);
+                if (!initializer || !Node.isArrayLiteralExpression(initializer)) {
+                    this._errorManager.addWarning(new ErrorDescription(`Overload field for operator ${operatorString} ` +
+                        "must be an array of overload functions.", property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(property.getName())));
+                    return;
+                }
+                if (!hasAsConst) {
+                    this._errorManager.addError(new ErrorDescription(`Overload array for operator ${operatorString} must use "as const". ` +
+                        "Without it, TypeScript widens the array type and loses individual " +
+                        "function signatures, causing type errors in generated code.", property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString((_b = property.getText().split("\n")[0]) !== null && _b !== void 0 ? _b : "")));
+                    return;
+                }
+                initializer.getElements().forEach((element, index) => {
+                    if (element.isKind(SyntaxKind.ArrowFunction) && !isStatic) {
+                        this._errorManager.addError(new ErrorDescription(`Overload ${index} for operator ${operatorString} must not be an arrow function. ` +
+                            "Use a function expression instead, as arrow functions cannot bind `this` correctly for instance operators.", element.getSourceFile().getFilePath(), element.getStartLineNumber(), this._minifyString(element.getText())));
+                        return;
+                    }
+                    if (!element.isKind(SyntaxKind.FunctionExpression) &&
+                        !element.isKind(SyntaxKind.FunctionDeclaration) &&
+                        !element.isKind(SyntaxKind.ArrowFunction)) {
+                        this._errorManager.addWarning(new ErrorDescription(`Expected overload ${index} for operator ${operatorString} to be a function.`, element.getSourceFile().getFilePath(), element.getStartLineNumber(), this._minifyString(element.getText())));
+                        return;
+                    }
+                    // At this point element is guaranteed to be a function-like node
+                    const funcElement = element;
+                    // Exclude `this` pseudo-parameter from count
+                    const parameters = funcElement
+                        .getParameters()
+                        .filter((p) => p.getName() !== "this");
+                    const paramCount = parameters.length;
+                    // Dispatch by parameter count to determine overload kind
+                    if (paramCount === 2 &&
+                        isStatic &&
+                        binarySyntaxKind &&
+                        !instanceOperators.has(binarySyntaxKind)) {
+                        this._addBinaryOverload(binarySyntaxKind, classDecl, classType, filePath, property, funcElement, parameters, operatorString, index, true);
+                    }
+                    else if (paramCount === 1 &&
+                        !isStatic &&
+                        binarySyntaxKind &&
+                        instanceOperators.has(binarySyntaxKind)) {
+                        this._addBinaryOverload(binarySyntaxKind, classDecl, classType, filePath, property, funcElement, parameters, operatorString, index, false);
+                    }
+                    else if (paramCount === 1 && isStatic && prefixUnarySyntaxKind) {
+                        this._addPrefixUnaryOverload(prefixUnarySyntaxKind, classDecl, classType, filePath, property, funcElement, parameters, operatorString, index);
+                    }
+                    else if (paramCount === 0 && !isStatic && postfixUnarySyntaxKind) {
+                        this._addPostfixUnaryOverload(postfixUnarySyntaxKind, classDecl, classType, filePath, property, funcElement, operatorString, index);
+                    }
+                    else {
+                        this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for operator ${operatorString} ` +
+                            `has invalid parameter count (${paramCount}) for this operator context.`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(funcElement.getText())));
+                    }
+                });
+            });
+        });
+    }
+    _addBinaryOverload(syntaxKind, classDecl, classType, filePath, property, element, parameters, operatorString, index, isStatic) {
+        var _a, _b, _c, _d, _e;
+        let hasWarning = false;
+        const lhsType = isStatic ? (_a = parameters[0]) === null || _a === void 0 ? void 0 : _a.getType().getText() : classType;
+        const rhsType = isStatic
+            ? (_b = parameters[1]) === null || _b === void 0 ? void 0 : _b.getType().getText()
+            : (_c = parameters[0]) === null || _c === void 0 ? void 0 : _c.getType().getText();
+        if (isStatic && lhsType !== classType && rhsType !== classType) {
+            this._errorManager.addWarning(new ErrorDescription(`Overload for operator ${operatorString} ` +
+                "must have either LHS or RHS parameter matching its class type.", property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        const returnType = element.getReturnType().getText();
+        if (comparisonOperators.has(syntaxKind) && returnType !== "boolean") {
+            this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for comparison operator ${operatorString} ` +
+                `must have a return type of 'boolean', got '${returnType}'.`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        if (!isStatic && returnType !== "void") {
+            this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for instance operator ${operatorString} ` +
+                `must have a return type of 'void', got '${returnType}'.`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        const operatorOverloads = (_d = this.get(syntaxKind)) !== null && _d !== void 0 ? _d : new Map();
+        const lhsMap = (_e = operatorOverloads.get(lhsType)) !== null && _e !== void 0 ? _e : new Map();
+        if (lhsMap.has(rhsType)) {
+            this._errorManager.addWarning(new ErrorDescription(`Duplicate overload for operator ${operatorString} with LHS type ${lhsType} and RHS type ${rhsType}`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        if (hasWarning)
+            return;
+        lhsMap.set(rhsType, {
+            isStatic,
+            className: classDecl.getName(),
+            classFilePath: filePath,
+            operatorString,
+            index,
+            returnType,
+        });
+        operatorOverloads.set(lhsType, lhsMap);
+        this.set(syntaxKind, operatorOverloads);
+        const funcName = Node.isFunctionExpression(element)
+            ? element.getName()
+            : undefined;
+        const sl = this._shortTypeName.bind(this);
+        const label = funcName
+            ? `${funcName}(${sl(lhsType)}, ${sl(rhsType)})`
+            : `(${sl(lhsType)}, ${sl(rhsType)})`;
+        this._logger.debug(`Loaded ${classDecl.getName()}["${operatorString}"][${index}]: ${label} => ${sl(element.getReturnType().getText())}${isStatic ? " (static)" : " (instance)"}`);
+        let fileEntries = this._fileEntries.get(filePath);
+        if (!fileEntries) {
+            fileEntries = [];
+            this._fileEntries.set(filePath, fileEntries);
+        }
+        fileEntries.push({ syntaxKind, lhsType, rhsType });
+    }
+    _addPrefixUnaryOverload(syntaxKind, classDecl, classType, filePath, property, element, parameters, operatorString, index) {
+        var _a, _b;
+        let hasWarning = false;
+        const operandType = (_a = parameters[0]) === null || _a === void 0 ? void 0 : _a.getType().getText();
+        if (operandType !== classType) {
+            this._errorManager.addWarning(new ErrorDescription(`Prefix unary overload for operator ${operatorString} ` +
+                "must have its parameter matching its class type.", property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        const operatorOverloads = (_b = this._prefixUnaryOverloads.get(syntaxKind)) !== null && _b !== void 0 ? _b : new Map();
+        if (operatorOverloads.has(operandType)) {
+            this._errorManager.addWarning(new ErrorDescription(`Duplicate prefix unary overload for operator ${operatorString} with operand type ${operandType}`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        if (hasWarning)
+            return;
+        const returnType = element.getReturnType().getText();
+        operatorOverloads.set(operandType, {
+            isStatic: true,
+            className: classDecl.getName(),
+            classFilePath: filePath,
+            operatorString,
+            index,
+            returnType,
+        });
+        this._prefixUnaryOverloads.set(syntaxKind, operatorOverloads);
+        const funcName = Node.isFunctionExpression(element)
+            ? element.getName()
+            : undefined;
+        const sl = this._shortTypeName.bind(this);
+        const label = funcName
+            ? `${funcName}(${sl(operandType)})`
+            : `(${sl(operandType)})`;
+        this._logger.debug(`Loaded ${classDecl.getName()}["${operatorString}"][${index}]: ${operatorString}${label} => ${sl(returnType)} (prefix unary)`);
+        let fileEntries = this._prefixUnaryFileEntries.get(filePath);
+        if (!fileEntries) {
+            fileEntries = [];
+            this._prefixUnaryFileEntries.set(filePath, fileEntries);
+        }
+        fileEntries.push({ syntaxKind, operandType });
+    }
+    _addPostfixUnaryOverload(syntaxKind, classDecl, classType, filePath, property, element, operatorString, index) {
+        var _a;
+        let hasWarning = false;
+        const returnType = element.getReturnType().getText();
+        if (returnType !== "void") {
+            this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for postfix operator ${operatorString} ` +
+                `must have a return type of 'void', got '${returnType}'.`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        const operandType = classType;
+        const operatorOverloads = (_a = this._postfixUnaryOverloads.get(syntaxKind)) !== null && _a !== void 0 ? _a : new Map();
+        if (operatorOverloads.has(operandType)) {
+            this._errorManager.addWarning(new ErrorDescription(`Duplicate postfix unary overload for operator ${operatorString} with operand type ${operandType}`, property.getSourceFile().getFilePath(), property.getStartLineNumber(), this._minifyString(element.getText())));
+            hasWarning = true;
+        }
+        if (hasWarning)
+            return;
+        operatorOverloads.set(operandType, {
+            isStatic: false,
+            className: classDecl.getName(),
+            classFilePath: filePath,
+            operatorString,
+            index,
+            returnType,
+        });
+        this._postfixUnaryOverloads.set(syntaxKind, operatorOverloads);
+        const funcName = Node.isFunctionExpression(element)
+            ? element.getName()
+            : undefined;
+        const label = funcName ? `${funcName}()` : "()";
+        this._logger.debug(`Loaded ${classDecl.getName()}["${operatorString}"][${index}]: ${this._shortTypeName(operandType)}${operatorString} ${label} (postfix unary)`);
+        let fileEntries = this._postfixUnaryFileEntries.get(filePath);
+        if (!fileEntries) {
+            fileEntries = [];
+            this._postfixUnaryFileEntries.set(filePath, fileEntries);
+        }
+        fileEntries.push({ syntaxKind, operandType });
+    }
+    /**
+     * 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.
+     */
+    _addOverloadsFromTypeAnnotation(property, classDecl, classType, filePath, isStatic, operatorString, binarySyntaxKind, prefixUnarySyntaxKind, postfixUnarySyntaxKind) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+        const propertyType = property.getType();
+        if (!propertyType.isTuple())
+            return;
+        const tupleElements = propertyType.getTupleElements();
+        const className = classDecl.getName();
+        if (!className)
+            return;
+        const sl = this._shortTypeName.bind(this);
+        for (let index = 0; index < tupleElements.length; index++) {
+            const elementType = tupleElements[index];
+            const callSigs = elementType.getCallSignatures();
+            if (callSigs.length === 0)
+                continue;
+            const sig = callSigs[0];
+            // Extract parameter types, filtering out the `this` pseudo-parameter
+            const params = [];
+            for (const sym of sig.getParameters()) {
+                const name = sym.getName();
+                if (name === "this")
+                    continue;
+                const decl = sym.getValueDeclaration();
+                if (!decl)
+                    continue;
+                params.push({ name, type: decl.getType().getText() });
+            }
+            const paramCount = params.length;
+            const returnType = sig.getReturnType().getText();
+            // --- Binary static ---
+            if (paramCount === 2 &&
+                isStatic &&
+                binarySyntaxKind &&
+                !instanceOperators.has(binarySyntaxKind)) {
+                const lhsType = params[0].type;
+                const rhsType = params[1].type;
+                if (lhsType !== classType && rhsType !== classType) {
+                    this._errorManager.addWarning(new ErrorDescription(`Overload for operator ${operatorString} ` +
+                        "must have either LHS or RHS parameter matching its class type.", filePath, property.getStartLineNumber(), this._minifyString((_a = property.getText().split("\n")[0]) !== null && _a !== void 0 ? _a : "")));
+                    continue;
+                }
+                if (comparisonOperators.has(binarySyntaxKind) &&
+                    returnType !== "boolean") {
+                    this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for comparison operator ${operatorString} ` +
+                        `must have a return type of 'boolean', got '${returnType}'.`, filePath, property.getStartLineNumber(), this._minifyString((_b = property.getText().split("\n")[0]) !== null && _b !== void 0 ? _b : "")));
+                    continue;
+                }
+                const operatorOverloads = (_c = this.get(binarySyntaxKind)) !== null && _c !== void 0 ? _c : new Map();
+                const lhsMap = (_d = operatorOverloads.get(lhsType)) !== null && _d !== void 0 ? _d : new Map();
+                if (lhsMap.has(rhsType))
+                    continue; // duplicate — skip silently for .d.ts
+                lhsMap.set(rhsType, {
+                    isStatic: true,
+                    className,
+                    classFilePath: filePath,
+                    operatorString,
+                    index,
+                    returnType,
+                });
+                operatorOverloads.set(lhsType, lhsMap);
+                this.set(binarySyntaxKind, operatorOverloads);
+                this._logger.debug(`Loaded ${className}["${operatorString}"][${index}]: (${sl(lhsType)}, ${sl(rhsType)}) => ${sl(returnType)} (static, from .d.ts)`);
+                let fileEntries = this._fileEntries.get(filePath);
+                if (!fileEntries) {
+                    fileEntries = [];
+                    this._fileEntries.set(filePath, fileEntries);
+                }
+                fileEntries.push({ syntaxKind: binarySyntaxKind, lhsType, rhsType });
+            }
+            // --- Binary instance (compound assignment) ---
+            else if (paramCount === 1 &&
+                !isStatic &&
+                binarySyntaxKind &&
+                instanceOperators.has(binarySyntaxKind)) {
+                const lhsType = classType;
+                const rhsType = params[0].type;
+                if (returnType !== "void") {
+                    this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for instance operator ${operatorString} ` +
+                        `must have a return type of 'void', got '${returnType}'.`, filePath, property.getStartLineNumber(), this._minifyString((_e = property.getText().split("\n")[0]) !== null && _e !== void 0 ? _e : "")));
+                    continue;
+                }
+                const operatorOverloads = (_f = this.get(binarySyntaxKind)) !== null && _f !== void 0 ? _f : new Map();
+                const lhsMap = (_g = operatorOverloads.get(lhsType)) !== null && _g !== void 0 ? _g : new Map();
+                if (lhsMap.has(rhsType))
+                    continue;
+                lhsMap.set(rhsType, {
+                    isStatic: false,
+                    className,
+                    classFilePath: filePath,
+                    operatorString,
+                    index,
+                    returnType,
+                });
+                operatorOverloads.set(lhsType, lhsMap);
+                this.set(binarySyntaxKind, operatorOverloads);
+                this._logger.debug(`Loaded ${className}["${operatorString}"][${index}]: (${sl(lhsType)}, ${sl(rhsType)}) => void (instance, from .d.ts)`);
+                let fileEntries = this._fileEntries.get(filePath);
+                if (!fileEntries) {
+                    fileEntries = [];
+                    this._fileEntries.set(filePath, fileEntries);
+                }
+                fileEntries.push({ syntaxKind: binarySyntaxKind, lhsType, rhsType });
+            }
+            // --- Prefix unary ---
+            else if (paramCount === 1 && isStatic && prefixUnarySyntaxKind) {
+                const operandType = params[0].type;
+                if (operandType !== classType) {
+                    this._errorManager.addWarning(new ErrorDescription(`Prefix unary overload for operator ${operatorString} ` +
+                        "must have its parameter matching its class type.", filePath, property.getStartLineNumber(), this._minifyString((_h = property.getText().split("\n")[0]) !== null && _h !== void 0 ? _h : "")));
+                    continue;
+                }
+                const operatorOverloads = (_j = this._prefixUnaryOverloads.get(prefixUnarySyntaxKind)) !== null && _j !== void 0 ? _j : new Map();
+                if (operatorOverloads.has(operandType))
+                    continue;
+                operatorOverloads.set(operandType, {
+                    isStatic: true,
+                    className,
+                    classFilePath: filePath,
+                    operatorString,
+                    index,
+                    returnType,
+                });
+                this._prefixUnaryOverloads.set(prefixUnarySyntaxKind, operatorOverloads);
+                this._logger.debug(`Loaded ${className}["${operatorString}"][${index}]: ${operatorString}(${sl(operandType)}) => ${sl(returnType)} (prefix unary, from .d.ts)`);
+                let fileEntries = this._prefixUnaryFileEntries.get(filePath);
+                if (!fileEntries) {
+                    fileEntries = [];
+                    this._prefixUnaryFileEntries.set(filePath, fileEntries);
+                }
+                fileEntries.push({ syntaxKind: prefixUnarySyntaxKind, operandType });
+            }
+            // --- Postfix unary ---
+            else if (paramCount === 0 && !isStatic && postfixUnarySyntaxKind) {
+                if (returnType !== "void") {
+                    this._errorManager.addWarning(new ErrorDescription(`Overload function ${index} for postfix operator ${operatorString} ` +
+                        `must have a return type of 'void', got '${returnType}'.`, filePath, property.getStartLineNumber(), this._minifyString((_k = property.getText().split("\n")[0]) !== null && _k !== void 0 ? _k : "")));
+                    continue;
+                }
+                const operandType = classType;
+                const operatorOverloads = (_l = this._postfixUnaryOverloads.get(postfixUnarySyntaxKind)) !== null && _l !== void 0 ? _l : new Map();
+                if (operatorOverloads.has(operandType))
+                    continue;
+                operatorOverloads.set(operandType, {
+                    isStatic: false,
+                    className,
+                    classFilePath: filePath,
+                    operatorString,
+                    index,
+                    returnType,
+                });
+                this._postfixUnaryOverloads.set(postfixUnarySyntaxKind, operatorOverloads);
+                this._logger.debug(`Loaded ${className}["${operatorString}"][${index}]: ${sl(operandType)}${operatorString} () (postfix unary, from .d.ts)`);
+                let fileEntries = this._postfixUnaryFileEntries.get(filePath);
+                if (!fileEntries) {
+                    fileEntries = [];
+                    this._postfixUnaryFileEntries.set(filePath, fileEntries);
+                }
+                fileEntries.push({ syntaxKind: postfixUnarySyntaxKind, operandType });
+            }
+        }
+    }
+    /**
+     * Returns the type hierarchy chain for a given type name:
+     * [self, parent, grandparent, ...]. Primitives like "number"
+     * return a single-element array.
+     */
+    _getTypeChain(typeName) {
+        var _a, _b;
+        const cached = this._typeChainCache.get(typeName);
+        if (cached)
+            return cached;
+        const chain = [typeName];
+        // Extract simple class name from fully-qualified type strings
+        // e.g. 'import("C:/path/to/Foo").Foo' → 'Foo'
+        const simpleName = (_b = (_a = typeName.match(/\.(\w+)$/)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : typeName;
+        for (const sourceFile of this._project.getSourceFiles()) {
+            const classDecl = sourceFile.getClass(simpleName);
+            if (classDecl) {
+                let current = classDecl.getBaseClass();
+                while (current) {
+                    chain.push(current.getType().getText());
+                    current = current.getBaseClass();
+                }
+                break;
+            }
+        }
+        this._typeChainCache.set(typeName, chain);
+        return chain;
+    }
+    _minifyString(str) {
+        return str.replace(/\s+/g, " ").replace("\n", "").trim();
+    }
+    /** Strips `import("...").` prefixes from fully-qualified type names for readable logs. */
+    _shortTypeName(typeName) {
+        return typeName.replace(/import\("[^"]*"\)\./g, "");
+    }
+    toString() {
+        let str = "";
+        for (const [operatorSyntaxKind, lhsMap] of this) {
+            str += `\n\nBinary Operator: ${SyntaxKind[operatorSyntaxKind]}`;
+            for (const [lhsType, rhsMap] of lhsMap) {
+                str += `\n  - LHS Type: ${lhsType}`;
+                for (const [rhsType, overload] of rhsMap) {
+                    str += `\n      - RHS Type: ${rhsType}`;
+                    str += `\n          Overload: ${JSON.stringify(overload)}`;
+                }
+            }
+        }
+        for (const [syntaxKind, operandMap] of this._prefixUnaryOverloads) {
+            str += `\n\nPrefix Unary Operator: ${SyntaxKind[syntaxKind]}`;
+            for (const [operandType, overload] of operandMap) {
+                str += `\n  - Operand Type: ${operandType}`;
+                str += `\n      Overload: ${JSON.stringify(overload)}`;
+            }
+        }
+        for (const [syntaxKind, operandMap] of this._postfixUnaryOverloads) {
+            str += `\n\nPostfix Unary Operator: ${SyntaxKind[syntaxKind]}`;
+            for (const [operandType, overload] of operandMap) {
+                str += `\n  - Operand Type: ${operandType}`;
+                str += `\n      Overload: ${JSON.stringify(overload)}`;
+            }
+        }
+        return str;
+    }
+}

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

@@ -0,0 +1,41 @@
+export type EditRecord = {
+    /** Start position in the original source */
+    origStart: number;
+    /** End position (exclusive) in the original source */
+    origEnd: number;
+    /** Start position in the transformed source */
+    transStart: number;
+    /** End position (exclusive) in the transformed source */
+    transEnd: number;
+};
+/**
+ * Bidirectional position mapping between original and transformed source text.
+ *
+ * Computes a list of edit records by diffing the two texts, then provides
+ * O(edits) position and span mapping in both directions.
+ */
+export declare class SourceMap {
+    readonly edits: readonly EditRecord[];
+    constructor(original: string, transformed: string);
+    /** Returns true if no edits were detected (original === transformed). */
+    get isEmpty(): boolean;
+    /** Map a position from original source to transformed source. */
+    originalToTransformed(pos: number): number;
+    /** Map a position from transformed source to original source. */
+    transformedToOriginal(pos: number): number;
+    /** Map a text span { start, length } from transformed positions to original positions. */
+    remapSpan(span: {
+        start: number;
+        length: number;
+    }): {
+        start: number;
+        length: number;
+    };
+    /** Check if an original-source position falls inside an edited region. */
+    isInsideEdit(originalPos: number): boolean;
+    /**
+     * For a position inside an edited region (in original coords),
+     * return the EditRecord it falls in, or undefined.
+     */
+    getEditAt(originalPos: number): EditRecord | undefined;
+}