monkeypatchlist 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,22 @@
+import type { Realm, SerializedCatalog } from '../../../catalog.ts';
+import type { LexicalDeclaration, RawOccurrence } from './types.ts';
+/** An occurrence, with the realm of the group that found it. */
+export interface RealmOccurrence {
+    realm: Realm;
+    occurrence: RawOccurrence;
+}
+/**
+ * A classic script's top-level lexical declaration, with its realm, and `id`: the name its artifact's occurrences give
+ * it, so that a script's own writes are never checked against its own declarations.
+ */
+export interface RealmDeclaration {
+    realm: Realm;
+    id: string;
+    declaration: LexicalDeclaration;
+}
+/**
+ * Each occurrence, in the order given, with the scan-wide lexical-name check applied. The result depends only on the
+ * set of declarations, never on the order artifacts are listed in: each occurrence's notes are sorted by the declaring
+ * artifact and the declaration's place in it.
+ */
+export declare function lexicalCollisions(occurrences: readonly RealmOccurrence[], declarations: readonly RealmDeclaration[], catalog: SerializedCatalog): RawOccurrence[];

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

@@ -0,0 +1,103 @@
+// The scan-wide lexical-name check (§3 Declarations in classic scripts, §9 Mutation confidence). There is no
+// evaluation-order modelling between scripts. Instead, per realm, the top-level `let`, `const` and `class` names of
+// every classic script are collected, and a write in another script that reads one of those names bare keeps its
+// finding with a `note` naming the declaring artifact:
+// - a bare-identifier write of the name (`fetch = w`, `delete fetch`)
+// - a write whose holder chain starts at the name (`Node.prototype.foo = f`, `var P = Promise; P.prototype.x = g`)
+// An assignment to a name another script declares with `const` throws, so it also gets the mutation-confidence reason
+// `const-collision`. Reading a `const` doesn't throw, so a holder chain through one doesn't. A redeclaration across
+// scripts (a `declare` write of the name) is ignored.
+import { mutationConfidence, mutationReasons } from "../../confidence/index.js";
+import { globalHolder } from "./global-object.js";
+/**
+ * Each occurrence, in the order given, with the scan-wide lexical-name check applied. The result depends only on the
+ * set of declarations, never on the order artifacts are listed in: each occurrence's notes are sorted by the declaring
+ * artifact and the declaration's place in it.
+ */
+export function lexicalCollisions(occurrences, declarations, catalog) {
+    const byName = new Map();
+    for (const declared of declarations) {
+        const key = JSON.stringify([declared.realm, declared.declaration.name]);
+        const found = byName.get(key);
+        if (found === undefined)
+            byName.set(key, [declared]);
+        else
+            found.push(declared);
+    }
+    for (const found of byName.values())
+        found.sort(inDeclarationOrder);
+    if (byName.size === 0)
+        return occurrences.map(({ occurrence }) => occurrence);
+    return occurrences.map(({ realm, occurrence }) => {
+        // A redeclaration across scripts is ignored.
+        if (occurrence.mechanism === 'declare')
+            return occurrence;
+        const global = globalHolder(catalog, realm);
+        let throws;
+        let noted = false;
+        const trace = [];
+        for (const step of occurrence.trace) {
+            trace.push(step);
+            if (!isBareGlobalRead(step, realm))
+                continue;
+            const colliding = (byName.get(JSON.stringify([realm, step.name])) ?? []).filter(({ id }) => id !== occurrence.artifact);
+            if (colliding.length === 0)
+                continue;
+            noted = true;
+            trace.push(...colliding.map(({ declaration }) => noteStep(declaration)));
+            const bareWrite = occurrence.target.name === `${global}.${step.name}`;
+            if (bareWrite && occurrence.mechanism === 'assign' && colliding.some(({ declaration }) => declaration.kind === 'const')) {
+                throws ??= step.name;
+            }
+        }
+        if (!noted)
+            return occurrence;
+        if (throws === undefined)
+            return { ...occurrence, trace };
+        const { target, mutation } = occurrence.confidence;
+        return {
+            ...occurrence,
+            confidence: { target, mutation: mutationConfidence([...mutation.reasons, 'const-collision']) },
+            trace: [...trace, constCollisionStep(throws)],
+        };
+    });
+}
+/** A free name that resolved to no declaration, as the global object's property: a bare name read in global code. */
+function isBareGlobalRead(step, realm) {
+    return (step.kind === 'binding' &&
+        step.resolution === 'global' &&
+        step.form === 'global-property' &&
+        step.realm === realm &&
+        step.realmInstance === 'current');
+}
+function inDeclarationOrder(a, b) {
+    const x = a.declaration;
+    const y = b.declaration;
+    if (x.artifact !== y.artifact)
+        return x.artifact < y.artifact ? -1 : 1;
+    if (a.id !== b.id)
+        return a.id < b.id ? -1 : 1;
+    return x.generated.start - y.generated.start;
+}
+function noteStep({ name, kind, artifact, generated }) {
+    return {
+        kind: 'note',
+        about: 'lexical-collision',
+        name,
+        declaration: kind,
+        artifact,
+        generated,
+        text: `${artifact} declares \`${name}\` with a top-level \`${kind}\` at ${generated.line}:${generated.column}, so when ` +
+            `both scripts load, \`${name}\` here reaches that binding and not the global object's property`,
+    };
+}
+function constCollisionStep(name) {
+    return {
+        kind: 'confidence-reason',
+        dimension: 'mutation',
+        reason: 'const-collision',
+        level: mutationReasons['const-collision'],
+        name,
+        text: `another classic script in the realm declares \`${name}\` with \`const\`, so assigning it most likely throws`,
+    };
+}

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

@@ -0,0 +1,76 @@
+import { type AstNode } from './ast.ts';
+import { type ScopeRules } from './scope.ts';
+/** A variable: a local declaration's name, or a name bound on the global object (`global`). */
+export interface VariableKey {
+    scope: AstNode | 'global';
+    name: string;
+}
+/**
+ * A definition of a variable: a declarator with an initializer, an assignment, an update, or a `for…in`/`for…of`
+ * head. `pattern` destructures `source` to give the variable its value. A definition with no `source` gives a value the
+ * syntax doesn't show (`x += 1`, `x++`, a loop head). A logical assignment (`x ||= e`) may keep the value before it.
+ */
+export interface Definition {
+    /** The declarator, assignment, update or loop head that defines the variable. */
+    site: AstNode;
+    name: string;
+    pattern: AstNode;
+    source?: AstNode;
+    logical: boolean;
+    /**
+     * For a compound assignment of an identifier (`x += e`, `x **= e`, but not `||=`, `&&=` or `??=`), the binary
+     * expression ECMA-262 evaluates it as: `x op e`, with the assignment's own `x` and `e` as operands.
+     */
+    compound?: AstNode;
+    /**
+     * The function, program or instance field initializer whose own code the definition is in, where the walk orders it:
+     * a class's static blocks and static field initializers are the code of the function the class is evaluated in.
+     */
+    owner: AstNode;
+    /** Whether `this` at the definition is the script's top-level `this`: no non-arrow function or class code around it. */
+    topLevel: boolean;
+}
+/**
+ * The definitions that reach a read: `start` when the variable's start value does, and the definitions whose values it
+ * may have. `ordered` says whether the walk ordered the read.
+ */
+export interface Reaching {
+    start: boolean;
+    definitions: readonly Definition[];
+    ordered: boolean;
+    /**
+     * The start value and definitions that reach the read only past a lazy init that didn't assign (§5 Resolver
+     * capabilities 6), each with the tests their values passed there: only its values that pass every one remain.
+     */
+    narrowed?: ReadonlyMap<Definition | 'start', readonly Narrowing[]>;
+}
+/**
+ * What a lazy init's test lets past without assigning (§5 Resolver capabilities 6): after `if (!k) k = …` only the
+ * truthy entry values remain, after `if (k == null) k = …` only the non-nullish ones.
+ */
+export type Narrowing = 'truthy' | 'falsy' | 'nullish' | 'notNullish' | 'null' | 'notNull' | 'undefined' | 'notUndefined';
+/** Whether a primitive passes a narrowing's test. */
+export declare function passes(narrowing: Narrowing, value: unknown): boolean;
+export interface Definitions {
+    /** The variable an identifier reads or writes, or none when the seam has no declaration for a local name. */
+    keyOf(id: AstNode): VariableKey | undefined;
+    /** Every definition of a variable in the program, in document order. */
+    of(key: VariableKey): readonly Definition[];
+    /** The definitions of `key` that reach the read `id`. */
+    reaching(id: AstNode, key: VariableKey): Reaching;
+}
+/** Whether an assignment operator is a compound one that reads its target and folds (`+=`, `**=`), not `=` or a logical one. */
+export declare const compoundOperator: (operator: string) => boolean;
+/**
+ * The binary expression a compound assignment of an identifier, `x op= e`, evaluates (ECMA-262 13.15.2): `x op e`,
+ * spanning the assignment, with its own operand nodes. One per assignment, so it is a stable node to memoize and trace
+ * by. Undefined for any other node.
+ */
+export declare function compoundOf(site: AstNode): AstNode | undefined;
+/** The function declaration a variable is the name of, when its key is the `id` of one a parameter shadows. */
+export declare const shadowedNameOf: (scope: AstNode | "global") => AstNode | undefined;
+/** Whether a function binds `name` in itself, as a parameter or `arguments`. */
+export declare const bindsOwn: (fn: AstNode, name: string) => boolean;
+export declare function definitionsOf(program: AstNode, scope: ScopeRules): Definitions;
+/** The identifiers a binding or assignment pattern binds, in source order. */
+export declare function identifiersOf(pattern: AstNode): AstNode[];