ushman-characterize 0.4.0

package/dist/purity-classifier.js

@@ -0,0 +1,363 @@
+import * as t from '@babel/types';
+import { isTrivialGetterLike } from "./function-utils.js";
+import { parseBundleAst } from "./shared.js";
+const DENIED_IDENTIFIER_READS = new Set([
+    'Date',
+    'XMLHttpRequest',
+    'crypto',
+    'document',
+    'fetch',
+    'localStorage',
+    'performance',
+    'sessionStorage',
+    'window',
+]);
+const MUTATING_METHOD_NAMES = new Set([
+    'add',
+    'clear',
+    'copyWithin',
+    'delete',
+    'fill',
+    'pop',
+    'push',
+    'remove',
+    'reverse',
+    'set',
+    'shift',
+    'sort',
+    'splice',
+    'unshift',
+]);
+const ALLOWED_GLOBAL_CALLS = new Set([
+    'Array.from',
+    'Array.isArray',
+    'JSON.parse',
+    'JSON.stringify',
+    'Number.isFinite',
+    'Number.isInteger',
+    'Object.assign',
+    'Object.entries',
+    'Object.freeze',
+    'Object.fromEntries',
+    'Object.keys',
+    'Object.values',
+    'String.raw',
+]);
+const isLiteralish = (value) => {
+    if (!value) {
+        return false;
+    }
+    if (t.isBooleanLiteral(value) ||
+        t.isNullLiteral(value) ||
+        t.isNumericLiteral(value) ||
+        t.isRegExpLiteral(value) ||
+        t.isStringLiteral(value)) {
+        return true;
+    }
+    if (t.isIdentifier(value, { name: 'undefined' })) {
+        return true;
+    }
+    if (t.isArrayExpression(value)) {
+        return value.elements.every((entry) => entry !== null && isLiteralish(entry));
+    }
+    if (t.isObjectExpression(value)) {
+        return value.properties.every((property) => t.isObjectProperty(property) && !property.computed && isLiteralish(property.value));
+    }
+    return false;
+};
+const isFunctionLikeBinding = (binding) => t.isFunctionDeclaration(binding.path.node) ||
+    (t.isVariableDeclarator(binding.path.node) &&
+        (t.isArrowFunctionExpression(binding.path.node.init) || t.isFunctionExpression(binding.path.node.init)));
+const isAllowedOuterRead = (binding) => binding.kind === 'module' ||
+    isFunctionLikeBinding(binding) ||
+    (binding.kind === 'const' && t.isVariableDeclarator(binding.path.node) && isLiteralish(binding.path.node.init));
+const getMemberPath = (value) => {
+    if (t.isIdentifier(value)) {
+        return value.name;
+    }
+    if (!t.isMemberExpression(value) || value.computed || !t.isIdentifier(value.property)) {
+        return null;
+    }
+    const objectPath = getMemberPath(value.object);
+    return objectPath ? `${objectPath}.${value.property.name}` : null;
+};
+const getAssignmentRootIdentifier = (value) => {
+    if (t.isIdentifier(value)) {
+        return value;
+    }
+    if (t.isTSAsExpression(value) ||
+        t.isTSSatisfiesExpression(value) ||
+        t.isTSNonNullExpression(value) ||
+        t.isTypeCastExpression(value)) {
+        return getAssignmentRootIdentifier(value.expression);
+    }
+    if (t.isMemberExpression(value) || t.isOptionalMemberExpression(value)) {
+        return getAssignmentRootIdentifier(value.object);
+    }
+    return null;
+};
+const resolveBinding = ({ identifier, scope, }) => (identifier ? scope.getBinding(identifier.name) : null);
+const bindingWritesOuterState = ({ binding, functionScope, }) => Boolean(binding && binding.scope !== functionScope);
+const isAllowedGlobalCall = (calleePath) => calleePath !== 'Math.random' && (calleePath.startsWith('Math.') || ALLOWED_GLOBAL_CALLS.has(calleePath));
+const isDeniedGlobalPath = (calleePath) => [...DENIED_IDENTIFIER_READS].some((prefix) => calleePath === prefix || calleePath.startsWith(`${prefix}.`));
+const isDeniedBuiltinCall = (calleePath) => calleePath === 'Math.random' || calleePath === 'Date.now' || calleePath === 'performance.now';
+const isMutatingMemberCall = (callPath, functionScope) => {
+    const callee = callPath.node.callee;
+    if ((!t.isMemberExpression(callee) && !t.isOptionalMemberExpression(callee)) || !t.isIdentifier(callee.property)) {
+        return false;
+    }
+    if (!MUTATING_METHOD_NAMES.has(callee.property.name)) {
+        return false;
+    }
+    return bindingWritesOuterState({
+        binding: resolveBinding({
+            identifier: getAssignmentRootIdentifier(callee.object),
+            scope: callPath.scope,
+        }),
+        functionScope,
+    });
+};
+const classifyIdentifierCall = ({ callee, callPath, functionPath, mark, }) => {
+    const binding = callPath.scope.getBinding(callee.name);
+    if (!binding) {
+        if (DENIED_IDENTIFIER_READS.has(callee.name)) {
+            mark('calls-denied-global');
+            callPath.stop();
+        }
+        return;
+    }
+    if (binding.scope === functionPath.scope && !isFunctionLikeBinding(binding)) {
+        mark('calls-denied-global');
+        callPath.stop();
+        return;
+    }
+    if (binding.scope !== functionPath.scope && !isAllowedOuterRead(binding)) {
+        mark('calls-denied-global');
+        callPath.stop();
+    }
+};
+const classifyCallExpression = ({ callPath, functionPath, mark, }) => {
+    const callee = callPath.node.callee;
+    const calleePath = getMemberPath(callee);
+    if (calleePath) {
+        if (isDeniedBuiltinCall(calleePath)) {
+            mark('calls-denied-global');
+            callPath.stop();
+            return;
+        }
+        if (isAllowedGlobalCall(calleePath)) {
+            return;
+        }
+        if (isDeniedGlobalPath(calleePath)) {
+            mark('calls-denied-global');
+            callPath.stop();
+            return;
+        }
+    }
+    if (isMutatingMemberCall(callPath, functionPath.scope)) {
+        mark('writes-outer-binding');
+        callPath.stop();
+        return;
+    }
+    if (!t.isIdentifier(callee)) {
+        return;
+    }
+    classifyIdentifierCall({
+        callee,
+        callPath,
+        functionPath,
+        mark,
+    });
+};
+const classifyIdentifierRead = ({ identifierPath, functionPath, mark, }) => {
+    if (!identifierPath.isReferencedIdentifier()) {
+        return;
+    }
+    if (DENIED_IDENTIFIER_READS.has(identifierPath.node.name)) {
+        mark('reads-denied-global');
+        identifierPath.stop();
+        return;
+    }
+    const binding = identifierPath.scope.getBinding(identifierPath.node.name);
+    if (!binding || binding.scope === functionPath.scope || isAllowedOuterRead(binding)) {
+        return;
+    }
+    mark('reads-mutable-outer-binding');
+    identifierPath.stop();
+};
+const classifyWrite = ({ functionPath, mark, targetPath, }) => {
+    if (!bindingWritesOuterState({
+        binding: resolveBinding({
+            identifier: getAssignmentRootIdentifier(targetPath.node),
+            scope: targetPath.scope,
+        }),
+        functionScope: functionPath.scope,
+    })) {
+        return;
+    }
+    mark('writes-outer-binding');
+    targetPath.stop();
+};
+const classifyPurity = ({ path }) => {
+    if (path.node.async || path.node.generator) {
+        return 'async-or-generator';
+    }
+    let reason = null;
+    const mark = (value) => {
+        if (!reason) {
+            reason = value;
+        }
+    };
+    path.traverse({
+        AssignmentExpression(inner) {
+            classifyWrite({
+                functionPath: path,
+                mark,
+                targetPath: inner.get('left'),
+            });
+        },
+        AwaitExpression(inner) {
+            mark('async-or-generator');
+            inner.stop();
+        },
+        CallExpression(inner) {
+            classifyCallExpression({
+                callPath: inner,
+                functionPath: path,
+                mark,
+            });
+        },
+        Identifier(inner) {
+            classifyIdentifierRead({
+                functionPath: path,
+                identifierPath: inner,
+                mark,
+            });
+        },
+        ThrowStatement(inner) {
+            const argument = inner.node.argument;
+            if (t.isNewExpression(argument) &&
+                t.isIdentifier(argument.callee) &&
+                /Error$/u.test(argument.callee.name)) {
+                return;
+            }
+            mark('throws-non-error');
+            inner.stop();
+        },
+        UnaryExpression(inner) {
+            if (inner.node.operator !== 'delete') {
+                return;
+            }
+            const target = inner.get('argument');
+            if (!target.isExpression()) {
+                return;
+            }
+            classifyWrite({
+                functionPath: path,
+                mark,
+                targetPath: target,
+            });
+        },
+        UpdateExpression(inner) {
+            const target = inner.get('argument');
+            if (!target.isExpression()) {
+                return;
+            }
+            classifyWrite({
+                functionPath: path,
+                mark,
+                targetPath: target,
+            });
+        },
+    });
+    return reason;
+};
+const visitClassMethods = ({ bundle, skippedForTracing, }) => {
+    let totalTopLevelFunctions = 0;
+    const collectClassMethod = ({ className, memberPath, }) => {
+        if (memberPath.node.kind !== 'method') {
+            return;
+        }
+        const memberName = t.isIdentifier(memberPath.node.key) && !memberPath.node.computed ? memberPath.node.key.name : null;
+        if (!memberName) {
+            return;
+        }
+        totalTopLevelFunctions += 1;
+        if (isTrivialGetterLike(memberPath.node)) {
+            skippedForTracing.add(`${className}.${memberName}`);
+        }
+    };
+    bundle.programPath.traverse({
+        ClassDeclaration(path) {
+            const className = path.node.id?.name;
+            if (!className) {
+                return;
+            }
+            for (const memberPath of path.get('body.body')) {
+                if (!memberPath.isClassMethod()) {
+                    continue;
+                }
+                collectClassMethod({
+                    className,
+                    memberPath,
+                });
+            }
+        },
+    });
+    return totalTopLevelFunctions;
+};
+export const classifyPureTopLevelFunctionsFromBundle = (bundle) => {
+    const pureFunctions = [];
+    const impureFunctions = [];
+    const skippedForTracing = new Set();
+    let totalTopLevelFunctions = visitClassMethods({
+        bundle,
+        skippedForTracing,
+    });
+    bundle.programPath.traverse({
+        FunctionDeclaration(path) {
+            const directParent = path.parentPath;
+            const isTopLevel = directParent === bundle.programPath ||
+                ((directParent?.isExportNamedDeclaration() || directParent?.isExportDefaultDeclaration()) &&
+                    directParent.parentPath === bundle.programPath);
+            const name = path.node.id?.name;
+            if (!name || !isTopLevel) {
+                return;
+            }
+            totalTopLevelFunctions += 1;
+            if (isTrivialGetterLike(path.node)) {
+                skippedForTracing.add(name);
+            }
+            const reason = classifyPurity({
+                path,
+            });
+            if (reason) {
+                impureFunctions.push({
+                    name,
+                    reason,
+                });
+                return;
+            }
+            pureFunctions.push({
+                arity: path.node.params.length,
+                bindingName: name,
+                kind: 'function',
+                name,
+                parameterNames: path.node.params.map((parameter, index) => t.isIdentifier(parameter) ? parameter.name : `arg${index}`),
+            });
+        },
+    });
+    return {
+        impureFunctions,
+        pureFunctions,
+        skippedForTracing: [...skippedForTracing].sort((left, right) => left.localeCompare(right)),
+        totalTopLevelFunctions,
+    };
+};
+/**
+ * Classify top-level function declarations into conservative pure/impure buckets.
+ */
+export const classifyPureTopLevelFunctions = ({ source, sourcePath, }) => classifyPureTopLevelFunctionsFromBundle(parseBundleAst({
+    source,
+    sourcePath,
+}));

package/dist/rebind.d.ts

@@ -0,0 +1,26 @@
+type RebindPreview = {
+    readonly after: string;
+    readonly before: string;
+    readonly filePath: string;
+};
+type ParsedRebindMapping = {
+    readonly selector: string;
+    readonly symbol: string;
+    readonly target: string;
+    readonly workspaceModule: null | string;
+};
+export declare const parseRebindMapping: (pair: string) => ParsedRebindMapping;
+/**
+ * Rewrite generated replay imports to point at extracted source modules.
+ */
+export declare const rewriteReplayImports: ({ dryRun, mappings, workspaceRoot, yes, }: {
+    readonly dryRun?: boolean;
+    readonly mappings: ReadonlyMap<string, string>;
+    readonly workspaceRoot: string;
+    readonly yes?: boolean;
+}) => Promise<{
+    files: string[];
+    previews: RebindPreview[];
+}>;
+export {};
+//# sourceMappingURL=rebind.d.ts.map

package/dist/rebind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebind.d.ts","sourceRoot":"","sources":["../src/rebind.ts"],"names":[],"mappings":"AAUA,KAAK,aAAa,GAAG;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,eAAe,EAAE,IAAI,GAAG,MAAM,CAAC;CAC3C,CAAC;AAkFF,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,mBAWjD,CAAC;AAkWF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAU,2CAKxC;IACC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CAC1B;;;EAqEA,CAAC"}