monkeypatchlist 0.0.0-stage → 0.1.0

package/dist/packages/analysis/binding.js

@@ -0,0 +1,5 @@
+// The binding-resolution seam (§19): it sits inside the JS resolver, between parsing and monkeypatchlist's own scope rules.
+// `eslint-scope` is the implementation monkeypatchlist ships; `@typescript-eslint/scope-manager` is a verified drop-in.
+// monkeypatchlist's four post-passes (§5) run above the seam, so swapping implementations never touches them.
+export { eslintScopeBindings, scopeKinds, } from "./lib/binding.js";
+export { createJsResolver } from "./lib/resolver.js";

package/dist/packages/analysis/index.d.ts

@@ -0,0 +1,10 @@
+export { codeCallees, effects, guardClasses, globalForms, ineffectiveReasons, installContexts, limitationKinds, mechanisms, reachabilities, throwsValues, traceStepKinds, type AliasStep, type AnalyzeGroupInput, type AnalyzeGroupOutput, type ArtifactRef, type ArtifactSource, type BindingStep, type CallStep, type CodeCallee, type ConfidenceReasonStep, type CreationSiteStep, type DiscoveredReference, type Effect, type FoldStep, type GeneratedLocation, type GuardClass, type GuardStep, type GlobalDeclarationKind, type GlobalForm, type IneffectiveReason, type IneffectiveWrite, type LexicalCollisionStep, type LexicalDeclaration, type Limitation, type LimitationKind, type InstallContext, type Locks, type Lookup, type Mechanism, type ModuleLinking, type ModuleLinkStep, type NestedCodeStep, type RestoreStep, type RewrittenDeleteStep, type OutcomeStep, type RawOccurrence, type Reachability, type ReachabilityBasis, type RealmInstance, type Resolver, type Strictness, type Target, type TraceStep, type TraceStepKind, type Throws, } from './lib/types.ts';
+export { defaultBudget, type Budget, type Caps } from './lib/budget.ts';
+export { chunkRegistries } from './lib/chunk-registry.ts';
+export { lexicalCollisions, type RealmDeclaration, type RealmOccurrence } from './lib/collisions.ts';
+import type { Resolver } from './lib/types.ts';
+/**
+ * The JavaScript resolver: `oxc-parser` with an explicit `sourceType`, `eslint-scope` behind the binding-resolution
+ * seam, and monkeypatchlist's scope post-passes above it (§5). `binding.ts` builds one with another binding resolver.
+ */
+export declare const jsResolver: Resolver;

package/dist/packages/analysis/index.js

@@ -0,0 +1,13 @@
+// Analysis (§19, module 4): the resolver seam. It takes link groups, the catalog and a budget, and returns raw
+// occurrences, ineffective writes, limitations and discovered references. Everything that crosses it is plain
+// JSON-serializable data, so that a native analyzer (§18) can replace this module and nothing else.
+export { codeCallees, effects, guardClasses, globalForms, ineffectiveReasons, installContexts, limitationKinds, mechanisms, reachabilities, throwsValues, traceStepKinds, } from "./lib/types.js";
+export { defaultBudget } from "./lib/budget.js";
+export { chunkRegistries } from "./lib/chunk-registry.js";
+export { lexicalCollisions } from "./lib/collisions.js";
+import { createJsResolver } from "./lib/resolver.js";
+/**
+ * The JavaScript resolver: `oxc-parser` with an explicit `sourceType`, `eslint-scope` behind the binding-resolution
+ * seam, and monkeypatchlist's scope post-passes above it (§5). `binding.ts` builds one with another binding resolver.
+ */
+export const jsResolver = createJsResolver();

package/dist/packages/analysis/job.d.ts

@@ -0,0 +1,33 @@
+import type { SerializedCatalog } from '../../catalog.ts';
+import type { Budget } from './lib/budget.ts';
+import type { AnalyzeGroupOutput, ArtifactRef, ArtifactSource, Resolver } from './lib/types.ts';
+/** One link group's analysis, as plain JSON-serializable data. */
+export interface GroupJob {
+    entry: ArtifactRef;
+    /** Each name `artifact(name)` may be asked for, with what it returns, in the order they were found. */
+    artifacts: [name: string, source: ArtifactSource][];
+    /** Each module request `resolveImport(from, specifier)` resolves, with the name it resolves to. */
+    imports: [from: string, specifier: string, to: string][];
+    /** Each chunk lookup `chunks(registry, id)` answers (§6 idiom 6), with the names it returns; `null` is every id. */
+    chunks?: [registry: string, id: string | null, names: string[]][];
+    /** Each lookup `initialChunks(registry)` answers, with the names it returns. */
+    initialChunks?: [registry: string, names: string[]][];
+}
+/**
+ * Writes the group of `entry` out as a job: every artifact the seam's callbacks can reach from it, through the module
+ * requests `requestsOf` lists for each importer and the chunk registries each one's loaders read, and what each request
+ * and chunk lookup resolves to. A request `requestsOf` doesn't list resolves to nothing, as `resolveImport` must say
+ * for it too.
+ */
+export declare function groupJob(input: {
+    entry: ArtifactRef;
+    artifact(name: string): ArtifactSource | undefined;
+    resolveImport(from: string, specifier: string): string | undefined;
+    requestsOf(from: string): readonly string[];
+    chunks?(registry: string, id: string | null): readonly string[];
+    initialChunks?(registry: string): readonly string[];
+}): GroupJob;
+/** The UTF-8 bytes of a job's artifacts, which its step budget and its estimated peak heap scale with (§18). */
+export declare function jobBytes(job: GroupJob): number;
+/** Analyzes a job with `resolver`, answering the seam's callbacks from the job's tables. */
+export declare function analyzeJob(resolver: Resolver, job: GroupJob, catalog: SerializedCatalog, budget: Budget): AnalyzeGroupOutput;

package/dist/packages/analysis/job.js

@@ -0,0 +1,85 @@
+// A link group as plain data (§18 Parallelism, §19 Serializable seams): the resolver seam's callbacks, `artifact`,
+// `resolveImport`, `chunks` and `initialChunks`, written out as the tables they read, so that a group can cross a
+// worker boundary as JSON and be analyzed there exactly as it would be in process.
+import { chunkRegistries } from "./lib/chunk-registry.js";
+/**
+ * Writes the group of `entry` out as a job: every artifact the seam's callbacks can reach from it, through the module
+ * requests `requestsOf` lists for each importer and the chunk registries each one's loaders read, and what each request
+ * and chunk lookup resolves to. A request `requestsOf` doesn't list resolves to nothing, as `resolveImport` must say
+ * for it too.
+ */
+export function groupJob(input) {
+    const artifacts = new Map();
+    const imports = [];
+    const chunks = new Map();
+    const initialChunks = new Map();
+    const queue = [input.entry.url];
+    const seen = new Set(queue);
+    const reach = (to) => {
+        if (seen.has(to))
+            return;
+        seen.add(to);
+        queue.push(to);
+    };
+    for (let next = 0; next < queue.length; next++) {
+        const name = queue[next];
+        const source = input.artifact(name);
+        if (source === undefined)
+            continue;
+        artifacts.set(name, source);
+        for (const specifier of input.requestsOf(source.url)) {
+            const to = input.resolveImport(source.url, specifier);
+            if (to === undefined)
+                continue;
+            imports.push([source.url, specifier, to]);
+            reach(to);
+        }
+        if (input.chunks === undefined && input.initialChunks === undefined)
+            continue;
+        // The chunks the source's loaders link (§6 idiom 6), looked up as the link group looks them up.
+        for (const { registry, ids } of chunkRegistries(source.text, source.sourceType).loads) {
+            if (input.initialChunks !== undefined && !initialChunks.has(registry)) {
+                const names = [...input.initialChunks(registry)];
+                initialChunks.set(registry, names);
+                names.forEach(reach);
+            }
+            if (input.chunks === undefined)
+                continue;
+            for (const id of ids ?? [null]) {
+                const key = JSON.stringify([registry, id]);
+                if (chunks.has(key))
+                    continue;
+                const names = [...input.chunks(registry, id)];
+                chunks.set(key, [registry, id, names]);
+                names.forEach(reach);
+            }
+        }
+    }
+    return {
+        entry: input.entry,
+        artifacts: [...artifacts],
+        imports,
+        ...(chunks.size === 0 ? {} : { chunks: [...chunks.values()] }),
+        ...(initialChunks.size === 0 ? {} : { initialChunks: [...initialChunks] }),
+    };
+}
+/** The UTF-8 bytes of a job's artifacts, which its step budget and its estimated peak heap scale with (§18). */
+export function jobBytes(job) {
+    return job.artifacts.reduce((bytes, [, { text }]) => bytes + Buffer.byteLength(text, 'utf8'), 0);
+}
+/** Analyzes a job with `resolver`, answering the seam's callbacks from the job's tables. */
+export function analyzeJob(resolver, job, catalog, budget) {
+    const artifacts = new Map(job.artifacts);
+    const imports = new Map(job.imports.map(([from, specifier, to]) => [JSON.stringify([from, specifier]), to]));
+    const chunks = new Map((job.chunks ?? []).map(([registry, id, names]) => [JSON.stringify([registry, id]), names]));
+    const initialChunks = new Map(job.initialChunks ?? []);
+    return resolver.analyzeGroup({
+        entry: job.entry,
+        artifact: (name) => artifacts.get(name),
+        resolveImport: (from, specifier) => imports.get(JSON.stringify([from, specifier])),
+        chunks: (registry, id) => chunks.get(JSON.stringify([registry, id])) ?? [],
+        initialChunks: (registry) => initialChunks.get(registry) ?? [],
+        catalog,
+        budget,
+    });
+}

package/dist/packages/analysis/lib/absence-tags.d.ts

@@ -0,0 +1,34 @@
+import type { Realm, SerializedCatalog } from '../../../catalog.ts';
+import { type AstNode } from './ast.ts';
+import type { Definitions } from './definitions.ts';
+import { type GlobalResolution, type Position } from './global-object.ts';
+import { type Judged, type Judgement } from './reachability.ts';
+import type { Replaced } from './wrap.ts';
+import type { Source, Write } from './writes.ts';
+import type { Effect, GuardStep } from './types.ts';
+export interface TagContext {
+    resolution: GlobalResolution;
+    definitions: Definitions;
+    catalog: SerializedCatalog;
+    realm: Realm;
+    /** The realm's global holder, e.g. `Window`. */
+    global: string;
+    /** The function whose own code holds a node, if any. */
+    functionOf(node: AstNode): AstNode | undefined;
+    /** The judgement of a write at `site` reached at `at`, along its call chain to its install entry (§7). */
+    judge(site: AstNode, at: Position, target: Judged['target']): Judgement;
+    /** Wrap evidence (§5 Resolver capabilities 10): whether each alternative of a value calls the original. */
+    evidence(sources: readonly Source[], replaced: Replaced): Set<boolean>;
+}
+/** The outcome a write gives: its target, and the effect the alternatives of its value must give to count. */
+export interface Tagged {
+    name: string;
+    holder: string;
+    shadows?: string | undefined;
+    effect: Effect;
+}
+/**
+ * The absence tags of writes over one program: for a write, the outcome it gives and where it is, the `guard` steps of
+ * the absence tests that tag it, or undefined when it keeps no tag.
+ */
+export declare function absenceTags(context: TagContext): (write: Write, outcome: Tagged, at: Position) => GuardStep[] | undefined;

package/dist/packages/analysis/lib/absence-tags.js

@@ -0,0 +1,340 @@
+// Absence tags on values (§5 Resolver capabilities 7, §7): a holder or value chosen on a branch where a native is
+// absent keeps `guarded-native-absence` wherever it is later written, whether it travelled through variables,
+// parameters or heap fields. The absence of any native counts, not only the target's.
+//
+// A write's holder and its written value are followed back, through the same routes the resolver evaluates them by, to
+// the expressions they are chosen from: the arms of `?:`, `||`, `&&` and `??`, the reaching definitions of a variable,
+// the arguments a parameter takes at each resolved call, and the expressions a heap field is given. Each expression on a
+// route is judged as a write there would be (§7: the guards between it and its install entry), and a route is tagged
+// when the guards along it, together, give `guarded-native-absence`. The alternatives that give the write combine by the
+// OR rule: the write keeps the tag only when every one of them is tagged.
+import { calleeExpression } from "./ast.js";
+import { truthiness, windowOf } from "./global-object.js";
+import { memberName } from "./keys.js";
+import { along } from "./reachability.js";
+import { frameOf, isFunction } from "./summaries.js";
+const absent = 'guarded-native-absence';
+/**
+ * The absence tags of writes over one program: for a write, the outcome it gives and where it is, the `guard` steps of
+ * the absence tests that tag it, or undefined when it keeps no tag.
+ */
+export function absenceTags(context) {
+    const { resolution, definitions } = context;
+    const targets = context.catalog.targets[context.realm];
+    const target = (name) => (Object.hasOwn(targets, name) ? targets[name] : undefined);
+    /** The position code owned by `owner` is evaluated at: in the frame of `at`, or one around it, that instantiates it. */
+    const framed = (owner, at) => {
+        for (let frame = at.frame; frame !== undefined; frame = frame.outer) {
+            if (frame.fn === owner)
+                return { guard: () => undefined, topLevel: false, frame };
+        }
+        return { guard: () => undefined, topLevel: false };
+    };
+    /** Where a call is: its `typeof` guards, whether it is top-level, and its caller's frame. */
+    const positionOf = ({ site, caller }) => ({
+        guard: (name) => site.guards.get(name),
+        topLevel: site.topLevel,
+        frame: caller,
+    });
+    /** The resolved calls a function's parameters take their arguments from: its frame's, or every resolved call of it. */
+    const bindingsOf = (fn, frame) => {
+        const own = frameOf(frame, fn);
+        if (own === undefined)
+            return resolution.callersOf(fn);
+        return own.how === 'creation' ? [] : own.bindings;
+    };
+    /** The index of the parameter an identifier reads, when it is a plain parameter of the function it is in. */
+    const parameterOf = (id) => {
+        const fn = context.functionOf(id);
+        if (fn === undefined || !isFunction(fn))
+            return undefined;
+        const key = definitions.keyOf(id);
+        if (key === undefined || definitions.of(key).length > 0)
+            return undefined;
+        const index = fn['params'].findIndex((param) => param.type === 'Identifier' && param['name'] === id['name']);
+        return index < 0 ? undefined : { fn, index };
+    };
+    /**
+     * The expressions a holder or value is chosen from. `object` follows a member read's object when the heap doesn't
+     * give the read and the object is a native, as a holder written through a chain (`h.prototype`) is chosen where `h`
+     * is. `followed` ends a cycle.
+     */
+    const alternatives = (node, at, hops, object, followed) => {
+        const seen = `${node.start}:${node.end}@${at.frame?.id ?? ''}`;
+        if (followed.has(seen))
+            return [];
+        followed.add(seen);
+        const route = [...hops, { node, at, site: node }];
+        switch (node.type) {
+            case 'ParenthesizedExpression':
+            case 'ChainExpression':
+            case 'TSAsExpression':
+            case 'TSNonNullExpression':
+                return alternatives(node['expression'], at, hops, object, followed);
+            case 'ConditionalExpression':
+                return [
+                    ...alternatives(node['consequent'], at, hops, object, followed),
+                    ...alternatives(node['alternate'], at, hops, object, followed),
+                ];
+            case 'LogicalExpression': {
+                // A literal left side that can't be the result (a falsy one of `||`, a truthy one of `&&`, a nullish one of
+                // `??`) is no alternative: the right side's value is.
+                const operator = node['operator'];
+                const kept = (alternative) => {
+                    if (alternative.start === true)
+                        return operator === '&&';
+                    if (!literal(alternative.node))
+                        return true;
+                    const values = resolution.evaluate(alternative.node, alternative.at);
+                    if (operator === '??') {
+                        return !values.every((value) => value.kind === 'constant' && (value.value === null || value.value === undefined));
+                    }
+                    const truthy = values.length === 0 ? undefined : truthiness(values);
+                    return truthy === undefined || truthy === (operator === '||');
+                };
+                return [
+                    ...alternatives(node['left'], at, hops, object, followed).filter(kept),
+                    ...alternatives(node['right'], at, hops, object, followed),
+                ];
+            }
+            case 'SequenceExpression':
+                return alternatives(node['expressions'].at(-1), at, hops, object, followed);
+            case 'AssignmentExpression':
+                if (node['operator'] !== '=')
+                    break;
+                return alternatives(node['right'], at, hops, object, followed);
+            case 'Identifier': {
+                const parameter = parameterOf(node);
+                if (parameter !== undefined) {
+                    const bindings = bindingsOf(parameter.fn, at.frame);
+                    if (bindings.length === 0)
+                        break;
+                    return bindings.flatMap((binding) => {
+                        // An iteration native's callback is passed the element it visits (§5 Resolver capabilities 4).
+                        if (binding.element !== undefined) {
+                            const given = resolution.givenSource(binding, parameter.index);
+                            if (given === undefined)
+                                return [{ node, at, hops: route }];
+                            return alternatives(given.node, given.at, route, object, followed);
+                        }
+                        const argument = binding.site.args[parameter.index];
+                        const listed = binding.site.unlisted === undefined || parameter.index < binding.site.unlisted;
+                        if (argument === undefined || argument.type === 'SpreadElement' || !listed)
+                            return [{ node, at, hops: route }];
+                        return alternatives(argument, positionOf(binding), route, object, followed);
+                    });
+                }
+                const key = definitions.keyOf(node);
+                if (key === undefined)
+                    break;
+                const reaching = definitions.reaching(node, key);
+                if (reaching.definitions.length === 0)
+                    break;
+                const found = reaching.start ? [{ node, at, hops: route, start: true }] : [];
+                for (const definition of reaching.definitions) {
+                    const where = framed(definition.owner, at);
+                    if (definition.pattern.type !== 'Identifier' || definition.source === undefined) {
+                        found.push({ node, at, hops: route });
+                        continue;
+                    }
+                    // A logical assignment (`x ||= p`) chooses its source on its own test, and keeps the value it had otherwise.
+                    const hop = definition.logical ? [...route, { node: definition.source, at: where, site: definition.site }] : route;
+                    found.push(...alternatives(definition.source, where, hop, object, followed));
+                    if (definition.logical)
+                        found.push(...alternatives(definition.pattern, where, route, object, followed));
+                }
+                return found;
+            }
+            case 'MemberExpression': {
+                const sources = resolution.fieldSources(node, at);
+                if (sources !== undefined) {
+                    return sources.flatMap((source) => alternatives(source.node, source.at, route, object, followed));
+                }
+                // A read in a function the position has no frame of is read in each frame the function is instantiated in.
+                const fn = context.functionOf(node);
+                if (fn !== undefined && frameOf(at.frame, fn) === undefined) {
+                    const frames = resolution.framesOf(fn);
+                    if (frames.length > 0) {
+                        followed.delete(seen);
+                        return frames.flatMap((frame) => alternatives(node, { ...at, frame }, hops, object, followed));
+                    }
+                }
+                // A member of a native read from it: the holder is chosen where the object it is read from is.
+                const from = node['object'];
+                const native = (value) => value.kind === 'holder' || value.kind === 'native' || value.kind === 'member';
+                if (object && from.type !== 'Super' && resolution.evaluate(from, at).some(native)) {
+                    return alternatives(from, at, route, object, followed).map((alternative) => ({
+                        ...alternative,
+                        descended: true,
+                    }));
+                }
+                break;
+            }
+        }
+        return [{ node, at, hops: route }];
+    };
+    /** The `guard` steps that tag a route, or undefined when the guards along it don't give `guarded-native-absence`. */
+    const tagOf = (alternative, tested) => {
+        let reachability = 'unconditional';
+        const steps = [];
+        for (const hop of alternative.hops) {
+            const judged = context.judge(hop.site, hop.at, tested);
+            reachability = along(reachability, judged.reachability);
+            steps.push(...judged.steps.filter((step) => step.kind === 'guard' && step.result === absent));
+        }
+        return reachability === absent ? steps : undefined;
+    };
+    /**
+     * Whether a value is the native the target holds before the write, read through the window written, which writing
+     * back changes nothing. Another window's copy is no write-back.
+     */
+    const isOriginal = (value, original, window) => {
+        if (window === undefined || !('leaves' in value) || windowOf(value.leaves) !== window)
+            return false;
+        switch (value.kind) {
+            case 'member':
+                return value.target === original;
+            case 'native':
+                return value.name === original || memberName(context.global, value.name) === original;
+            case 'holder':
+                return target(original)?.holds === value.holder;
+            default:
+                return false;
+        }
+    };
+    /**
+     * Whether a holder's alternative can give the holder written: it holds a leaf the holder was reached from, or it may
+     * be a native, and, unless the holder is read from it, it may be that holder.
+     */
+    const givesHolder = (alternative, write) => {
+        if (alternative.start === true)
+            return false;
+        if (write.leaves.some((leaf) => within(leaf.node, alternative.node)))
+            return true;
+        const values = resolution.evaluate(alternative.node, alternative.at);
+        if (values.length > 0 && values.every((value) => value.kind === 'object' || value.kind === 'constant'))
+            return false;
+        if (alternative.descended === true)
+            return false;
+        return !(values.length > 0 && values.every((value) => value.kind === 'holder' && value.holder !== write.holder));
+    };
+    /** The tag every alternative carries, with the steps of the first; undefined when some alternative has none. */
+    const everyTagged = (found, tested) => {
+        if (found.length === 0)
+            return undefined;
+        let first;
+        for (const alternative of found) {
+            if (alternative.start === true)
+                return undefined;
+            const steps = tagOf(alternative, tested);
+            if (steps === undefined)
+                return undefined;
+            first ??= steps;
+        }
+        return first;
+    };
+    return (write, outcome, at) => {
+        const tested = { name: outcome.name, ...(outcome.shadows === undefined ? {} : { shadows: outcome.shadows }) };
+        const original = outcome.shadows ?? outcome.name;
+        const window = windowOf(write.leaves);
+        // The holder: the alternatives that can give the holder written.
+        const holder = holderExpression(write.site, resolution);
+        if (holder !== undefined) {
+            const found = alternatives(holder, at, [], true, new Set()).filter((alternative) => givesHolder(alternative, write));
+            const steps = everyTagged(found, tested);
+            if (steps !== undefined)
+                return steps;
+        }
+        // The value: the alternatives that change the target (no write-back of the original) and give the outcome's effect.
+        const sources = valueSources(write);
+        if (sources.length === 0)
+            return undefined;
+        const found = sources
+            .flatMap((source) => alternatives(source.node, source.at, [], false, new Set()))
+            .filter((alternative) => {
+            if (alternative.start === true)
+                return true;
+            const values = resolution.evaluate(alternative.node, alternative.at);
+            return values.length === 0 || !values.every((value) => isOriginal(value, original, window));
+        });
+        // Only an alternative that is tagged can tag the write, so the effect of each is judged only when one is.
+        if (!found.some((alternative) => alternative.start !== true && tagOf(alternative, tested) !== undefined))
+            return undefined;
+        const replaced = { holder: write.holder, original, leaves: write.leaves };
+        const giving = outcome.effect === 'wrap' || outcome.effect === 'replace'
+            ? found.filter((alternative) => {
+                if (alternative.start === true)
+                    return outcome.effect === 'replace';
+                const answers = context.evidence([{ node: alternative.node, at: alternative.at }], replaced);
+                return answers.has(outcome.effect === 'wrap');
+            })
+            : found;
+        return everyTagged(giving, tested);
+    };
+}
+/** The expressions a write's new value comes from: an assigned value, or a defined descriptor's `value`. */
+function valueSources(write) {
+    const { change } = write;
+    if (change.kind === 'set')
+        return change.sources ?? [];
+    if (change.kind !== 'define')
+        return [];
+    const descriptors = change.alternatives ?? [change.descriptor];
+    return descriptors.flatMap((descriptor) => (descriptor === 'refused' ? [] : (descriptor.value?.sources ?? [])));
+}
+/**
+ * The expression that gives the object a write writes: the object of the member an assignment, update or `delete`
+ * writes, the object a legacy accessor method is called on, or the first argument of a writer call (`Object.
+ * defineProperty(h, …)`, `Reflect.set(h, …)`, `Object.assign(h, …)`). Undefined for a write that names none.
+ */
+function holderExpression(site, resolution) {
+    const objectOf = (member) => {
+        let node = member;
+        while (node.type === 'ChainExpression' || node.type === 'ParenthesizedExpression')
+            node = node['expression'];
+        return node.type === 'MemberExpression' ? node['object'] : undefined;
+    };
+    switch (site.type) {
+        case 'AssignmentExpression':
+            return objectOf(site['left']);
+        case 'UpdateExpression':
+        case 'UnaryExpression':
+            return objectOf(site['argument']);
+        case 'CallExpression': {
+            const callee = calleeExpression(site['callee']);
+            const key = callee.type === 'MemberExpression' && callee['computed'] !== true ? callee['property']['name'] : undefined;
+            if (typeof key === 'string' && key.startsWith('__'))
+                return callee['object'];
+            const [first] = site['arguments'];
+            return first === undefined || first.type === 'SpreadElement' ? undefined : first;
+        }
+        case 'Property': {
+            // A bulk mechanism's property: the object it is in is a call's argument, and the holder the call's first.
+            const literal = resolution.parentOf(site);
+            const call = literal === undefined ? undefined : resolution.parentOf(literal);
+            if (call?.type !== 'CallExpression')
+                return undefined;
+            const [first] = call['arguments'];
+            return first === undefined || first === literal || first.type === 'SpreadElement' ? undefined : first;
+        }
+        default:
+            return undefined;
+    }
+}
+/** Whether `node` lies within `outer`. */
+const within = (node, outer) => node.start >= outer.start && node.end <= outer.end;
+/** Whether an expression is a literal value: a literal, `undefined`, `void …`, or `!` of one. */
+function literal(node) {
+    switch (node.type) {
+        case 'Literal':
+            return true;
+        case 'Identifier':
+            return node['name'] === 'undefined';
+        case 'TemplateLiteral':
+            return node['expressions'].length === 0;
+        case 'UnaryExpression':
+            return node['operator'] === 'void' || (node['operator'] === '!' && literal(node['argument']));
+        default:
+            return false;
+    }
+}

package/dist/packages/analysis/lib/ast.d.ts

@@ -0,0 +1,28 @@
+export interface AstNode {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+/**
+ * Visits every node in document order, without recursion: `enter` before a node's children, with its parent, and
+ * `leave` after them. When `enter` returns `false`, the node's children are skipped and `leave` is not called for it.
+ */
+export declare function walkTree(root: AstNode, visitor: {
+    enter(node: AstNode, parent: AstNode | null): void | false;
+    leave?(node: AstNode): void;
+}): void;
+export declare function isNode(value: unknown): value is AstNode;
+/** The expression a callee takes its function from: past the discarded operands of comma sequences, as in `(0, a.b)`. */
+export declare function calleeExpression(callee: AstNode): AstNode;
+/**
+ * A call that is a direct eval when its `eval` is the global one (ECMA-262 PerformEval): `eval(…)` through the plain
+ * name, parenthesized or not. An optional call (`eval?.(s)`) and a sequence (`(0, eval)(s)`) are indirect.
+ */
+export declare function isEvalCall(node: AstNode): boolean;
+/**
+ * Whether an object literal's property with key `key` is `__proto__: p`, which sets the literal's prototype rather than
+ * defining an own property (ECMA-262 PropertyDefinitionEvaluation). A computed key, a shorthand, a method or an
+ * accessor named `__proto__` defines an own property like any other.
+ */
+export declare function setsLiteralPrototype(property: AstNode, key: string): boolean;

package/dist/packages/analysis/lib/ast.js

@@ -0,0 +1,64 @@
+// oxc's ESTree nodes, walked generically through its visitor keys.
+import { visitorKeys } from 'oxc-parser';
+/**
+ * Visits every node in document order, without recursion: `enter` before a node's children, with its parent, and
+ * `leave` after them. When `enter` returns `false`, the node's children are skipped and `leave` is not called for it.
+ */
+export function walkTree(root, visitor) {
+    const stack = [{ node: root, parent: null, leaving: false }];
+    while (stack.length > 0) {
+        const { node, parent, leaving } = stack.pop();
+        if (leaving) {
+            visitor.leave?.(node);
+            continue;
+        }
+        if (visitor.enter(node, parent) === false)
+            continue;
+        if (visitor.leave !== undefined)
+            stack.push({ node, parent, leaving: true });
+        const keys = visitorKeys[node.type] ?? [];
+        for (let k = keys.length - 1; k >= 0; k--) {
+            const child = node[keys[k]];
+            if (Array.isArray(child)) {
+                for (let c = child.length - 1; c >= 0; c--) {
+                    if (isNode(child[c]))
+                        stack.push({ node: child[c], parent: node, leaving: false });
+                }
+            }
+            else if (isNode(child))
+                stack.push({ node: child, parent: node, leaving: false });
+        }
+    }
+}
+export function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}
+/** The expression a callee takes its function from: past the discarded operands of comma sequences, as in `(0, a.b)`. */
+export function calleeExpression(callee) {
+    let expression = callee;
+    while (expression.type === 'SequenceExpression')
+        expression = expression['expressions'].at(-1);
+    return expression;
+}
+/**
+ * A call that is a direct eval when its `eval` is the global one (ECMA-262 PerformEval): `eval(…)` through the plain
+ * name, parenthesized or not. An optional call (`eval?.(s)`) and a sequence (`(0, eval)(s)`) are indirect.
+ */
+export function isEvalCall(node) {
+    if (node.type !== 'CallExpression' || node['optional'] === true)
+        return false;
+    const callee = node['callee'];
+    return callee.type === 'Identifier' && callee['name'] === 'eval';
+}
+/**
+ * Whether an object literal's property with key `key` is `__proto__: p`, which sets the literal's prototype rather than
+ * defining an own property (ECMA-262 PropertyDefinitionEvaluation). A computed key, a shorthand, a method or an
+ * accessor named `__proto__` defines an own property like any other.
+ */
+export function setsLiteralPrototype(property, key) {
+    return (key === '__proto__' &&
+        property['kind'] === 'init' &&
+        property['computed'] !== true &&
+        property['shorthand'] !== true &&
+        property['method'] !== true);
+}