boperators 0.1.0

package/dist/esm/core/SourceMap.js

@@ -0,0 +1,164 @@
+/**
+ * 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 class SourceMap {
+    constructor(original, transformed) {
+        this.edits = computeEdits(original, transformed);
+    }
+    /** Returns true if no edits were detected (original === transformed). */
+    get isEmpty() {
+        return this.edits.length === 0;
+    }
+    /** Map a position from original source to transformed source. */
+    originalToTransformed(pos) {
+        let delta = 0;
+        for (const edit of this.edits) {
+            if (pos < edit.origStart) {
+                // Before this edit — just apply accumulated delta
+                break;
+            }
+            if (pos < edit.origEnd) {
+                // Inside an edited region — map to start of the transformed replacement
+                return edit.transStart;
+            }
+            // Past this edit — accumulate the delta
+            delta = edit.transEnd - edit.origEnd;
+        }
+        return pos + delta;
+    }
+    /** Map a position from transformed source to original source. */
+    transformedToOriginal(pos) {
+        let delta = 0;
+        for (const edit of this.edits) {
+            if (pos < edit.transStart) {
+                break;
+            }
+            if (pos < edit.transEnd) {
+                // Inside a transformed region — map to start of the original span
+                return edit.origStart;
+            }
+            delta = edit.origEnd - edit.transEnd;
+        }
+        return pos + delta;
+    }
+    /** Map a text span { start, length } from transformed positions to original positions. */
+    remapSpan(span) {
+        const origStart = this.transformedToOriginal(span.start);
+        const origEnd = this.transformedToOriginal(span.start + span.length);
+        return { start: origStart, length: origEnd - origStart };
+    }
+    /** Check if an original-source position falls inside an edited region. */
+    isInsideEdit(originalPos) {
+        for (const edit of this.edits) {
+            if (originalPos < edit.origStart)
+                return false;
+            if (originalPos < edit.origEnd)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * For a position inside an edited region (in original coords),
+     * return the EditRecord it falls in, or undefined.
+     */
+    getEditAt(originalPos) {
+        for (const edit of this.edits) {
+            if (originalPos < edit.origStart)
+                return undefined;
+            if (originalPos < edit.origEnd)
+                return edit;
+        }
+        return undefined;
+    }
+}
+/**
+ * Compute edit records by scanning both texts for mismatches.
+ *
+ * Uses character-level comparison with anchor-based convergence:
+ * identical characters are skipped, mismatches start an edit region,
+ * and convergence is found by searching for a matching anchor substring
+ * in the remaining text.
+ */
+function computeEdits(original, transformed) {
+    if (original === transformed)
+        return [];
+    const edits = [];
+    let i = 0; // index in original
+    let j = 0; // index in transformed
+    while (i < original.length && j < transformed.length) {
+        // Skip matching characters
+        if (original[i] === transformed[j]) {
+            i++;
+            j++;
+            continue;
+        }
+        // Mismatch — start of an edit
+        const origEditStart = i;
+        const transEditStart = j;
+        // Find where the texts converge again.
+        // Search for an anchor: a substring from `original` that also
+        // appears at the corresponding position in `transformed`.
+        const ANCHOR_LEN = 8;
+        let found = false;
+        // Scan ahead in original from the mismatch point
+        for (let oi = origEditStart + 1; oi <= original.length - ANCHOR_LEN; oi++) {
+            const anchor = original.substring(oi, oi + ANCHOR_LEN);
+            const transPos = transformed.indexOf(anchor, transEditStart);
+            if (transPos >= 0) {
+                // Verify the anchor actually converges by checking a few more chars
+                let valid = true;
+                const verifyLen = Math.min(ANCHOR_LEN * 2, original.length - oi, transformed.length - transPos);
+                for (let k = ANCHOR_LEN; k < verifyLen; k++) {
+                    if (original[oi + k] !== transformed[transPos + k]) {
+                        valid = false;
+                        break;
+                    }
+                }
+                if (valid) {
+                    edits.push({
+                        origStart: origEditStart,
+                        origEnd: oi,
+                        transStart: transEditStart,
+                        transEnd: transPos,
+                    });
+                    i = oi;
+                    j = transPos;
+                    found = true;
+                    break;
+                }
+            }
+        }
+        if (!found) {
+            // No convergence — remaining text is all part of the edit.
+            // Use common suffix to tighten the bounds.
+            let suffixLen = 0;
+            while (suffixLen < original.length - origEditStart &&
+                suffixLen < transformed.length - transEditStart &&
+                original[original.length - 1 - suffixLen] ===
+                    transformed[transformed.length - 1 - suffixLen]) {
+                suffixLen++;
+            }
+            edits.push({
+                origStart: origEditStart,
+                origEnd: original.length - suffixLen,
+                transStart: transEditStart,
+                transEnd: transformed.length - suffixLen,
+            });
+            i = original.length;
+            j = transformed.length;
+        }
+    }
+    // Handle remaining text at the end
+    if (i < original.length || j < transformed.length) {
+        edits.push({
+            origStart: i,
+            origEnd: original.length,
+            transStart: j,
+            transEnd: transformed.length,
+        });
+    }
+    return edits;
+}

package/dist/esm/core/helpers/ensureImportedName.d.ts

@@ -0,0 +1,11 @@
+import { type Symbol as AstSymbol, type SourceFile } from "ts-morph";
+/**
+ * Ensures that the specified symbol is imported into the source file.
+ * If it is not already imported, adds it.
+ *
+ * @param sourceFile The SourceFile to modify.
+ * @param symbol The AstSymbol representing the class to import.
+ * @param moduleSpecifier The module from which the class should be imported.
+ * @returns The imported identifier name to use in the source file.
+ */
+export declare const ensureImportedName: (sourceFile: SourceFile, symbol: AstSymbol, moduleSpecifier: string) => string;

package/dist/esm/core/helpers/ensureImportedName.js

@@ -0,0 +1,46 @@
+import { SyntaxKind, } from "ts-morph";
+import { getImportedNameForSymbol } from "./getImportedNameForSymbol";
+/**
+ * Ensures that the specified symbol is imported into the source file.
+ * If it is not already imported, adds it.
+ *
+ * @param sourceFile The SourceFile to modify.
+ * @param symbol The AstSymbol representing the class to import.
+ * @param moduleSpecifier The module from which the class should be imported.
+ * @returns The imported identifier name to use in the source file.
+ */
+export const ensureImportedName = (sourceFile, symbol, moduleSpecifier) => {
+    // Attempt to get the imported name if it already exists
+    const existingName = getImportedNameForSymbol(sourceFile, symbol);
+    if (existingName)
+        return existingName; // Return the already-imported name
+    // Generate a unique name for the new import
+    const symbolName = symbol.getName();
+    let newImportName = symbolName;
+    // Ensure the name doesn't clash with existing identifiers in the source file
+    const existingIdentifiers = sourceFile.getDescendantsOfKind(SyntaxKind.Identifier);
+    const existingNames = new Set(existingIdentifiers.map((id) => id.getText()));
+    while (existingNames.has(newImportName)) {
+        newImportName = `${symbolName}_${Math.random().toString(36).substr(2, 5)}`;
+    }
+    // Check if the module is already imported
+    const existingImport = sourceFile
+        .getImportDeclarations()
+        .find((importDecl) => importDecl.getModuleSpecifierValue() === moduleSpecifier);
+    if (existingImport) {
+        // Add the new import to the named imports
+        existingImport.addNamedImport(newImportName === symbolName
+            ? symbolName
+            : { name: symbolName, alias: newImportName });
+    }
+    else {
+        // Add a new import declaration
+        sourceFile.addImportDeclaration({
+            moduleSpecifier,
+            namedImports: newImportName === symbolName
+                ? [symbolName]
+                : [{ name: symbolName, alias: newImportName }],
+        });
+    }
+    return newImportName;
+};

package/dist/esm/core/helpers/getImportedNameForSymbol.d.ts

@@ -0,0 +1,8 @@
+import type { Symbol as AstSymbol, SourceFile } from "ts-morph";
+/**
+ * Checks if the given symbol is already imported in the SourceFile.
+ * @param sourceFile The SourceFile to search for imports.
+ * @param symbol The AstSymbol to match against imports.
+ * @returns The imported identifier name if found, otherwise undefined.
+ */
+export declare const getImportedNameForSymbol: (sourceFile: SourceFile, symbol: AstSymbol) => string | undefined;

package/dist/esm/core/helpers/getImportedNameForSymbol.js

@@ -0,0 +1,60 @@
+/**
+ * Checks if the given symbol is already imported in the SourceFile.
+ * @param sourceFile The SourceFile to search for imports.
+ * @param symbol The AstSymbol to match against imports.
+ * @returns The imported identifier name if found, otherwise undefined.
+ */
+export const getImportedNameForSymbol = (sourceFile, symbol) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const aliasedSymbol = (_a = symbol.getAliasedSymbol()) !== null && _a !== void 0 ? _a : symbol;
+    // Helper function to compare symbols by their declarations
+    const symbolsAreEquivalent = (a, b) => {
+        if (!a || !b)
+            return false;
+        const aDecls = a.getDeclarations();
+        const bDecls = b.getDeclarations();
+        if (aDecls.length !== bDecls.length)
+            return false;
+        return aDecls.every((aDecl, i) => aDecl.getSourceFile() === bDecls[i].getSourceFile() &&
+            aDecl.getStart() === bDecls[i].getStart());
+    };
+    // Get all import declarations in the source file
+    const importDeclarations = sourceFile.getImportDeclarations();
+    for (const importDecl of importDeclarations) {
+        // Named imports
+        const namedImports = importDecl.getNamedImports();
+        for (const namedImport of namedImports) {
+            const importedSymbol = namedImport.getSymbol();
+            if (symbolsAreEquivalent(importedSymbol === null || importedSymbol === void 0 ? void 0 : importedSymbol.getAliasedSymbol(), aliasedSymbol)) {
+                return ((_c = (_b = namedImport.getAliasNode()) === null || _b === void 0 ? void 0 : _b.getText()) !== null && _c !== void 0 ? _c : namedImport.getNameNode().getText());
+            }
+        }
+        // Default import
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport) {
+            const defaultSymbol = (_d = defaultImport.getSymbol()) === null || _d === void 0 ? void 0 : _d.getAliasedSymbol();
+            if (symbolsAreEquivalent(defaultSymbol, aliasedSymbol)) {
+                // Return the default import name
+                return defaultImport.getText();
+            }
+        }
+        // Check namespace imports
+        const namespaceImport = importDecl.getNamespaceImport();
+        if (namespaceImport) {
+            const namespaceSymbol = namespaceImport.getSymbol();
+            if (namespaceSymbol) {
+                // Look for the symbol under this namespace
+                const exports = (_f = (_e = namespaceSymbol.getAliasedSymbol()) === null || _e === void 0 ? void 0 : _e.getExports()) !== null && _f !== void 0 ? _f : [];
+                for (const exportedSymbol of exports) {
+                    const resolvedExportedSymbol = (_g = exportedSymbol.getAliasedSymbol()) !== null && _g !== void 0 ? _g : exportedSymbol;
+                    if (symbolsAreEquivalent(resolvedExportedSymbol, aliasedSymbol)) {
+                        // Return namespace-qualified name (e.g., v3.Vector3)
+                        return `${namespaceImport.getText()}.${exportedSymbol.getName()}`;
+                    }
+                }
+            }
+        }
+    }
+    // No matching import found
+    return undefined;
+};

package/dist/esm/core/helpers/getModuleSpecifier.d.ts

@@ -0,0 +1,2 @@
+import type { SourceFile } from "ts-morph";
+export declare const getModuleSpecifier: (fromFile: SourceFile, toFile: SourceFile) => string;

package/dist/esm/core/helpers/getModuleSpecifier.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from "node:fs";
+import { posix as path } from "node:path";
+/**
+ * Walk up from a file path to find the nearest `package.json` with a `name`
+ * field. Returns the package name and the directory containing it.
+ */
+function findPackageInfo(filePath) {
+    const normalized = filePath.replace(/\\/g, "/");
+    let dir = path.dirname(normalized);
+    while (true) {
+        const pkgJsonPath = `${dir}/package.json`;
+        if (existsSync(pkgJsonPath)) {
+            try {
+                const content = readFileSync(pkgJsonPath, "utf-8");
+                const pkg = JSON.parse(content);
+                if (typeof pkg.name === "string") {
+                    return { name: pkg.name, dir };
+                }
+            }
+            catch (_a) {
+                // Malformed package.json, continue searching up
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Checks if `fromFile` already imports from `pkgName` (or a subpath of it)
+ * and returns that specifier if so. Otherwise returns `pkgName` bare.
+ */
+function reuseExistingImportOrReturn(fromFile, pkgName) {
+    for (const decl of fromFile.getImportDeclarations()) {
+        const specifier = decl.getModuleSpecifierValue();
+        if (specifier === pkgName || specifier.startsWith(`${pkgName}/`)) {
+            return specifier;
+        }
+    }
+    return pkgName;
+}
+export const getModuleSpecifier = (fromFile, toFile) => {
+    const toPath = toFile.getFilePath();
+    const fromPath = fromFile.getFilePath();
+    // Check if source and target belong to different packages
+    const toPkg = findPackageInfo(toPath);
+    const fromPkg = findPackageInfo(fromPath);
+    if (toPkg && fromPkg && toPkg.dir !== fromPkg.dir) {
+        return reuseExistingImportOrReturn(fromFile, toPkg.name);
+    }
+    // Same package (or couldn't determine) — use a relative path
+    const fromDir = path.dirname(fromPath);
+    const relativePath = path.relative(fromDir, toPath);
+    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+};

package/dist/esm/core/helpers/getOperatorStringFromProperty.d.ts

@@ -0,0 +1,13 @@
+import { type PropertyDeclaration } from "ts-morph";
+/**
+ * Extracts the operator string from a class property declaration, if it
+ * represents an operator overload.
+ *
+ * Handles three property name styles:
+ * - `["+"]` — ComputedPropertyName with a StringLiteral expression
+ * - `[Operator.PLUS]` — ComputedPropertyName with an enum member expression
+ * - `"+"` — StringLiteral property name
+ *
+ * Returns `undefined` if the property name doesn't resolve to an operator string.
+ */
+export declare function getOperatorStringFromProperty(property: PropertyDeclaration): string | undefined;

package/dist/esm/core/helpers/getOperatorStringFromProperty.js

@@ -0,0 +1,30 @@
+import { SyntaxKind } from "ts-morph";
+/**
+ * Extracts the operator string from a class property declaration, if it
+ * represents an operator overload.
+ *
+ * Handles three property name styles:
+ * - `["+"]` — ComputedPropertyName with a StringLiteral expression
+ * - `[Operator.PLUS]` — ComputedPropertyName with an enum member expression
+ * - `"+"` — StringLiteral property name
+ *
+ * Returns `undefined` if the property name doesn't resolve to an operator string.
+ */
+export function getOperatorStringFromProperty(property) {
+    const nameNode = property.getNameNode();
+    if (nameNode.isKind(SyntaxKind.ComputedPropertyName)) {
+        const expression = nameNode.getExpression();
+        if (expression.isKind(SyntaxKind.StringLiteral)) {
+            return expression.getLiteralValue();
+        }
+        // Handle Operator.PLUS style (enum member access)
+        const literalValue = expression.getType().getLiteralValue();
+        if (typeof literalValue === "string") {
+            return literalValue;
+        }
+    }
+    else if (nameNode.isKind(SyntaxKind.StringLiteral)) {
+        return nameNode.getLiteralValue();
+    }
+    return undefined;
+}

package/dist/esm/core/helpers/resolveExpressionType.d.ts

@@ -0,0 +1,11 @@
+import { type Node } from "ts-morph";
+/**
+ * Resolves the effective type name for a node in a binary expression.
+ *
+ * Handles special cases:
+ * - Numeric literals → `"number"`
+ * - Boolean literals (not in string context) → `"boolean"`
+ * - `"any"` type → falls back to the declared type of the symbol
+ *   (needed for compound assignments where TS can't infer the result type)
+ */
+export declare function resolveExpressionType(node: Node): string;

package/dist/esm/core/helpers/resolveExpressionType.js

@@ -0,0 +1,27 @@
+import { SyntaxKind } from "ts-morph";
+/**
+ * Resolves the effective type name for a node in a binary expression.
+ *
+ * Handles special cases:
+ * - Numeric literals → `"number"`
+ * - Boolean literals (not in string context) → `"boolean"`
+ * - `"any"` type → falls back to the declared type of the symbol
+ *   (needed for compound assignments where TS can't infer the result type)
+ */
+export function resolveExpressionType(node) {
+    var _a;
+    let typeName = node.getType().getText();
+    if (node.getKind() === SyntaxKind.NumericLiteral) {
+        return "number";
+    }
+    if (node.getKind() !== SyntaxKind.StringLiteral &&
+        (typeName === "true" || typeName === "false")) {
+        return "boolean";
+    }
+    if (typeName === "any") {
+        const decl = (_a = node.getSymbol()) === null || _a === void 0 ? void 0 : _a.getValueDeclaration();
+        if (decl)
+            typeName = decl.getType().getText();
+    }
+    return typeName;
+}

package/dist/esm/core/helpers/unwrapInitializer.d.ts

@@ -0,0 +1,9 @@
+import { type Expression } from "ts-morph";
+/**
+ * Unwraps `as const` and `satisfies` type assertions from an initializer
+ * expression, returning the underlying expression.
+ *
+ * For example, given `[fn1, fn2] as const`, this returns the
+ * `[fn1, fn2]` ArrayLiteralExpression.
+ */
+export declare function unwrapInitializer(initializer: Expression | undefined): Expression | undefined;

package/dist/esm/core/helpers/unwrapInitializer.js

@@ -0,0 +1,15 @@
+import { Node } from "ts-morph";
+/**
+ * Unwraps `as const` and `satisfies` type assertions from an initializer
+ * expression, returning the underlying expression.
+ *
+ * For example, given `[fn1, fn2] as const`, this returns the
+ * `[fn1, fn2]` ArrayLiteralExpression.
+ */
+export function unwrapInitializer(initializer) {
+    if (initializer && Node.isAsExpression(initializer))
+        initializer = initializer.getExpression();
+    if (initializer && Node.isSatisfiesExpression(initializer))
+        initializer = initializer.getExpression();
+    return initializer;
+}

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

@@ -0,0 +1,77 @@
+import { SyntaxKind } from "ts-morph";
+/**
+ * Maps operator string values to their corresponding TypeScript syntax kind.
+ */
+export declare const operatorMap: {
+    readonly "+": SyntaxKind.PlusToken;
+    readonly "+=": SyntaxKind.PlusEqualsToken;
+    readonly "-": SyntaxKind.MinusToken;
+    readonly "-=": SyntaxKind.MinusEqualsToken;
+    readonly "*": SyntaxKind.AsteriskToken;
+    readonly "*=": SyntaxKind.AsteriskEqualsToken;
+    readonly "/": SyntaxKind.SlashToken;
+    readonly "/=": SyntaxKind.SlashEqualsToken;
+    readonly ">": SyntaxKind.GreaterThanToken;
+    readonly ">=": SyntaxKind.GreaterThanEqualsToken;
+    readonly "<": SyntaxKind.LessThanToken;
+    readonly "<=": SyntaxKind.LessThanEqualsToken;
+    readonly "%": SyntaxKind.PercentToken;
+    readonly "%=": SyntaxKind.PercentEqualsToken;
+    readonly "==": SyntaxKind.EqualsEqualsToken;
+    readonly "===": SyntaxKind.EqualsEqualsEqualsToken;
+    readonly "!=": SyntaxKind.ExclamationEqualsToken;
+    readonly "!==": SyntaxKind.ExclamationEqualsEqualsToken;
+    readonly "&&": SyntaxKind.AmpersandAmpersandToken;
+    readonly "&&=": SyntaxKind.AmpersandAmpersandEqualsToken;
+    readonly "||": SyntaxKind.BarBarToken;
+    readonly "||=": SyntaxKind.BarBarEqualsToken;
+    readonly "??": SyntaxKind.QuestionQuestionToken;
+};
+export type OperatorString = keyof typeof operatorMap;
+export declare const operatorSyntaxKinds: (SyntaxKind.LessThanToken | SyntaxKind.GreaterThanToken | SyntaxKind.LessThanEqualsToken | SyntaxKind.GreaterThanEqualsToken | SyntaxKind.EqualsEqualsToken | SyntaxKind.ExclamationEqualsToken | SyntaxKind.EqualsEqualsEqualsToken | SyntaxKind.ExclamationEqualsEqualsToken | SyntaxKind.PlusToken | SyntaxKind.MinusToken | SyntaxKind.AsteriskToken | SyntaxKind.SlashToken | SyntaxKind.PercentToken | SyntaxKind.AmpersandAmpersandToken | SyntaxKind.BarBarToken | SyntaxKind.QuestionQuestionToken | SyntaxKind.PlusEqualsToken | SyntaxKind.MinusEqualsToken | SyntaxKind.AsteriskEqualsToken | SyntaxKind.SlashEqualsToken | SyntaxKind.PercentEqualsToken | SyntaxKind.BarBarEqualsToken | SyntaxKind.AmpersandAmpersandEqualsToken)[];
+export type OperatorSyntaxKind = (typeof operatorMap)[OperatorString];
+export declare const isOperatorSyntaxKind: (syntaxKind: SyntaxKind) => syntaxKind is OperatorSyntaxKind;
+/**
+ * Set of which operators whose overloads should be instance operators
+ * i.e. operate on the LHS object.
+ * These should return void.
+ */
+export declare const instanceOperators: Set<OperatorSyntaxKind>;
+/**
+ * Set of operators where the expected return type of their overload is a boolean.
+ */
+export declare const comparisonOperators: Set<OperatorSyntaxKind>;
+/**
+ * Maps prefix unary operator strings to their corresponding TypeScript syntax kind.
+ * Operators like `-` and `+` share SyntaxKind tokens with their binary counterparts;
+ * disambiguation happens at the AST node level (PrefixUnaryExpression vs BinaryExpression).
+ */
+export declare const prefixUnaryOperatorMap: {
+    readonly "-": SyntaxKind.MinusToken;
+    readonly "+": SyntaxKind.PlusToken;
+    readonly "!": SyntaxKind.ExclamationToken;
+    readonly "~": SyntaxKind.TildeToken;
+};
+export type PrefixUnaryOperatorString = keyof typeof prefixUnaryOperatorMap;
+export declare const prefixUnaryOperatorSyntaxKinds: (SyntaxKind.PlusToken | SyntaxKind.MinusToken | SyntaxKind.ExclamationToken | SyntaxKind.TildeToken)[];
+export type PrefixUnaryOperatorSyntaxKind = (typeof prefixUnaryOperatorMap)[PrefixUnaryOperatorString];
+export declare const isPrefixUnaryOperatorSyntaxKind: (syntaxKind: SyntaxKind) => syntaxKind is PrefixUnaryOperatorSyntaxKind;
+/**
+ * Maps postfix unary operator strings to their corresponding TypeScript syntax kind.
+ */
+export declare const postfixUnaryOperatorMap: {
+    readonly "++": SyntaxKind.PlusPlusToken;
+    readonly "--": SyntaxKind.MinusMinusToken;
+};
+export type PostfixUnaryOperatorString = keyof typeof postfixUnaryOperatorMap;
+export declare const postfixUnaryOperatorSyntaxKinds: (SyntaxKind.PlusPlusToken | SyntaxKind.MinusMinusToken)[];
+export type PostfixUnaryOperatorSyntaxKind = (typeof postfixUnaryOperatorMap)[PostfixUnaryOperatorString];
+export declare const isPostfixUnaryOperatorSyntaxKind: (syntaxKind: SyntaxKind) => syntaxKind is PostfixUnaryOperatorSyntaxKind;
+/**
+ * Set of operator strings that can appear as prefix unary overloads.
+ */
+export declare const prefixUnaryOperatorStrings: Set<string>;
+/**
+ * Set of operator strings that can appear as postfix unary overloads.
+ */
+export declare const postfixUnaryOperatorStrings: Set<string>;

package/dist/esm/core/operatorMap.js

@@ -0,0 +1,89 @@
+import { SyntaxKind } from "ts-morph";
+import { Operator } from "../lib/operatorSymbols";
+/**
+ * Maps operator string values to their corresponding TypeScript syntax kind.
+ */
+export const operatorMap = {
+    [Operator.PLUS]: SyntaxKind.PlusToken,
+    [Operator.PLUS_EQUALS]: SyntaxKind.PlusEqualsToken,
+    [Operator.MINUS]: SyntaxKind.MinusToken,
+    [Operator.MINUS_EQUALS]: SyntaxKind.MinusEqualsToken,
+    [Operator.MULTIPLY]: SyntaxKind.AsteriskToken,
+    [Operator.MULTIPLY_EQUALS]: SyntaxKind.AsteriskEqualsToken,
+    [Operator.DIVIDE]: SyntaxKind.SlashToken,
+    [Operator.DIVIDE_EQUALS]: SyntaxKind.SlashEqualsToken,
+    [Operator.GREATER_THAN]: SyntaxKind.GreaterThanToken,
+    [Operator.GREATER_THAN_EQUAL_TO]: SyntaxKind.GreaterThanEqualsToken,
+    [Operator.LESS_THAN]: SyntaxKind.LessThanToken,
+    [Operator.LESS_THAN_EQUAL_TO]: SyntaxKind.LessThanEqualsToken,
+    [Operator.MODULO]: SyntaxKind.PercentToken,
+    [Operator.MODULO_EQUALS]: SyntaxKind.PercentEqualsToken,
+    [Operator.EQUALS]: SyntaxKind.EqualsEqualsToken,
+    [Operator.STRICT_EQUALS]: SyntaxKind.EqualsEqualsEqualsToken,
+    [Operator.NOT_EQUALS]: SyntaxKind.ExclamationEqualsToken,
+    [Operator.STRICT_NOT_EQUALS]: SyntaxKind.ExclamationEqualsEqualsToken,
+    [Operator.AND]: SyntaxKind.AmpersandAmpersandToken,
+    [Operator.AND_EQUALS]: SyntaxKind.AmpersandAmpersandEqualsToken,
+    [Operator.OR]: SyntaxKind.BarBarToken,
+    [Operator.OR_EQUALS]: SyntaxKind.BarBarEqualsToken,
+    [Operator.NULLISH]: SyntaxKind.QuestionQuestionToken,
+};
+export const operatorSyntaxKinds = Object.values(operatorMap);
+export const isOperatorSyntaxKind = (syntaxKind) => operatorSyntaxKinds.includes(syntaxKind);
+/**
+ * Set of which operators whose overloads should be instance operators
+ * i.e. operate on the LHS object.
+ * These should return void.
+ */
+export const instanceOperators = new Set([
+    operatorMap[Operator.PLUS_EQUALS],
+    operatorMap[Operator.MINUS_EQUALS],
+    operatorMap[Operator.MULTIPLY_EQUALS],
+    operatorMap[Operator.DIVIDE_EQUALS],
+    operatorMap[Operator.MODULO_EQUALS],
+    operatorMap[Operator.AND_EQUALS],
+    operatorMap[Operator.OR_EQUALS],
+]);
+/**
+ * Set of operators where the expected return type of their overload is a boolean.
+ */
+export const comparisonOperators = new Set([
+    operatorMap[Operator.GREATER_THAN],
+    operatorMap[Operator.GREATER_THAN_EQUAL_TO],
+    operatorMap[Operator.LESS_THAN],
+    operatorMap[Operator.LESS_THAN_EQUAL_TO],
+    operatorMap[Operator.EQUALS],
+    operatorMap[Operator.STRICT_EQUALS],
+    operatorMap[Operator.NOT_EQUALS],
+    operatorMap[Operator.STRICT_NOT_EQUALS],
+]);
+/**
+ * Maps prefix unary operator strings to their corresponding TypeScript syntax kind.
+ * Operators like `-` and `+` share SyntaxKind tokens with their binary counterparts;
+ * disambiguation happens at the AST node level (PrefixUnaryExpression vs BinaryExpression).
+ */
+export const prefixUnaryOperatorMap = {
+    [Operator.MINUS]: SyntaxKind.MinusToken,
+    [Operator.PLUS]: SyntaxKind.PlusToken,
+    [Operator.NOT]: SyntaxKind.ExclamationToken,
+    [Operator.BITWISE_NOT]: SyntaxKind.TildeToken,
+};
+export const prefixUnaryOperatorSyntaxKinds = Object.values(prefixUnaryOperatorMap);
+export const isPrefixUnaryOperatorSyntaxKind = (syntaxKind) => prefixUnaryOperatorSyntaxKinds.includes(syntaxKind);
+/**
+ * Maps postfix unary operator strings to their corresponding TypeScript syntax kind.
+ */
+export const postfixUnaryOperatorMap = {
+    [Operator.INCREMENT]: SyntaxKind.PlusPlusToken,
+    [Operator.DECREMENT]: SyntaxKind.MinusMinusToken,
+};
+export const postfixUnaryOperatorSyntaxKinds = Object.values(postfixUnaryOperatorMap);
+export const isPostfixUnaryOperatorSyntaxKind = (syntaxKind) => postfixUnaryOperatorSyntaxKinds.includes(syntaxKind);
+/**
+ * Set of operator strings that can appear as prefix unary overloads.
+ */
+export const prefixUnaryOperatorStrings = new Set(Object.keys(prefixUnaryOperatorMap));
+/**
+ * Set of operator strings that can appear as postfix unary overloads.
+ */
+export const postfixUnaryOperatorStrings = new Set(Object.keys(postfixUnaryOperatorMap));

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

@@ -0,0 +1,30 @@
+import type { Project as TsMorphProject } from "ts-morph";
+import type { OverloadStore } from "./OverloadStore";
+export type ExportViolationReason = "not-exported-from-file" | "not-reachable-from-entry";
+export type ExportViolation = {
+    className: string;
+    classFilePath: string;
+    reason: ExportViolationReason;
+};
+export type ValidateExportsResult = {
+    violations: ExportViolation[];
+};
+/**
+ * Validate that all classes with registered operator overloads are exported
+ * and (optionally) reachable from a package entry point.
+ *
+ * @param project     The ts-morph project containing the source files.
+ * @param overloadStore  Populated OverloadStore for the project.
+ * @param projectDir  Absolute path to the project root — used to filter out
+ *                    overloads sourced from library dependencies.
+ * @param entryPoint  Absolute path to the source entry point (e.g. `src/index.ts`).
+ *                    When provided, a second pass checks that every overload
+ *                    class is transitively reachable from this file via its
+ *                    export graph. Omit to run the file-level check only.
+ */
+export declare function validateExports({ project, overloadStore, projectDir, entryPoint, }: {
+    project: TsMorphProject;
+    overloadStore: OverloadStore;
+    projectDir: string;
+    entryPoint?: string;
+}): ValidateExportsResult;