@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

package/dist/src/exemptions/installed-globals.js

@@ -0,0 +1,173 @@
+/**
+ * The classes a program installs as globals: a class value written into a property of
+ * the global object, which code outside the analysis that names the global constructs.
+ * The checker finds each write: the receiver's type is the global object's, the callee is
+ * the standard library's `Object.defineProperty` or a test runner's stub, and the
+ * property is the one of the key's name that `typeof globalThis` declares.
+ */
+import { isIdentifier, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isPropertyAssignment, isShorthandPropertyAssignment, isStringLiteral, } from "@typescript/native/ast";
+import { SignatureKind, SymbolFlags, } from "@typescript/native/sync";
+import { typesAt } from "../class-members.js";
+import { packageOfPath } from "../dependencies.js";
+import { must } from "../query.js";
+import { parenthesesRemoved, unwrapped } from "../unwrap.js";
+import { spansOf } from "./argument-places.js";
+import { classesCarried } from "./calls.js";
+/**
+ * The test runners' stubs of a global, by method name and the packages that declare it:
+ * `vi.stubGlobal` of vitest, and `jest.replaceProperty`, which `@jest/environment` types
+ * for `@jest/globals` and `@types/jest` declares for the `jest` global.
+ */
+const STUBS = new Map([
+    [
+        "stubGlobal",
+        { packages: new Set(["vitest"]), object: undefined, key: 0, value: 1, described: false },
+    ],
+    [
+        "replaceProperty",
+        {
+            packages: new Set(["@jest/environment", "@jest/globals", "@types/jest"]),
+            object: 0,
+            key: 1,
+            value: 2,
+            described: false,
+        },
+    ],
+]);
+/** `Object.defineProperty(object, key, descriptor)`. */
+const DEFINE = { object: 0, key: 1, value: 2, described: true };
+/** The text of a key written as a string literal. */
+function keyText(node) {
+    const key = node === undefined ? undefined : parenthesesRemoved(node);
+    return key !== undefined && (isStringLiteral(key) || isNoSubstitutionTemplateLiteral(key))
+        ? key.text
+        : undefined;
+}
+/** Whether a property's name is `value`. */
+function named(name) {
+    return (isIdentifier(name) || isStringLiteral(name)) && name.text === "value";
+}
+/** The value a property descriptor written as an object literal gives. */
+function describedValue(node) {
+    const descriptor = node === undefined ? undefined : parenthesesRemoved(node);
+    if (descriptor === undefined || !isObjectLiteralExpression(descriptor)) {
+        return undefined;
+    }
+    for (const property of descriptor.properties) {
+        if (isPropertyAssignment(property) && named(property.name)) {
+            return property.initializer;
+        }
+        if (isShorthandPropertyAssignment(property) &&
+            isIdentifier(property.name) &&
+            named(property.name)) {
+            return property.name;
+        }
+    }
+    return undefined;
+}
+/** How a call's callee writes a property: the standard library's `Object.defineProperty` or a runner's stub. */
+function writerOf(project, method) {
+    if (method.name === "defineProperty") {
+        const standard = method.declarations.some((handle) => project.program.getSourceFileMetadata(handle.path)?.isDefaultLibrary === true);
+        return standard && must(project.queries.parentOf(method))?.name === "ObjectConstructor"
+            ? DEFINE
+            : undefined;
+    }
+    const stub = STUBS.get(method.name);
+    return stub !== undefined &&
+        method.declarations.some((handle) => stub.packages.has(packageOfPath(handle.path) ?? ""))
+        ? stub
+        : undefined;
+}
+/** Each write of one project's own files that may install a value as a global, read from syntax and the callee. */
+function writesOf(project, sites) {
+    const found = sites.stores.map((store) => ({
+        site: store.store,
+        receiver: store.receiver,
+        key: store.key,
+        value: store.value,
+    }));
+    for (const { call } of sites.calls) {
+        const method = sites.invocations.callee(call);
+        const writer = method === undefined ? undefined : writerOf(project, method);
+        if (writer === undefined) {
+            continue;
+        }
+        const invoked = sites.invocations.of(call);
+        // With no types asked, a spread has no known length, so only a place no spread
+        // comes at or before is read.
+        const spans = spansOf(project, invoked.arguments, invoked.listed, []);
+        const at = (place) => {
+            const span = spans.find((one) => !one.open && one.first === place);
+            return span === undefined ? undefined : invoked.arguments[span.argument];
+        };
+        const key = keyText(at(writer.key));
+        const receiver = writer.object === undefined ? undefined : at(writer.object);
+        const value = writer.described ? describedValue(at(writer.value)) : at(writer.value);
+        if (key !== undefined &&
+            value !== undefined &&
+            (writer.object === undefined || receiver !== undefined)) {
+            found.push({ site: call, receiver, key, value });
+        }
+    }
+    return found;
+}
+/**
+ * The classes one project installs as globals. A write installs one where its object is
+ * the global object, as the checker types it (`window` and `self` are intersections that
+ * hold `typeof globalThis`, and an object asserted to `any` is read inside the
+ * assertion), and where the global object declares a property of the key's name with a
+ * construct signature, whose instances code outside the analysis makes.
+ */
+export function installedGlobals(project, held, chains, sites) {
+    const { queries } = project;
+    const writes = writesOf(project, sites);
+    if (writes.length === 0) {
+        return [];
+    }
+    const global = must(queries.resolveName("globalThis", SymbolFlags.Value, undefined, false));
+    const globalType = global === undefined ? undefined : must(queries.typeOfSymbol(global));
+    if (global === undefined || globalType === undefined) {
+        return [];
+    }
+    const properties = new Map(must(queries.propertiesOf(globalType)).map((property) => [property.name, property]));
+    const keyed = writes.filter((write) => properties.has(write.key));
+    const objects = keyed.flatMap((write) => write.receiver === undefined ? [] : [unwrapped(write.receiver)]);
+    const objectTypes = new Map(typesAt(project, objects).map((type, at) => [objects[at], type]));
+    const globals = new Map();
+    const isGlobal = (type) => {
+        if (type === undefined) {
+            return false;
+        }
+        let known = globals.get(type.id);
+        if (known === undefined) {
+            const parts = type.isUnionType() || type.isIntersectionType() ? must(queries.constituents(type)) : [type];
+            known = parts.some((part) => must(queries.symbolOfType(part))?.id === global.id);
+            globals.set(type.id, known);
+        }
+        return known;
+    };
+    const installs = keyed.filter((write) => write.receiver === undefined || isGlobal(objectTypes.get(unwrapped(write.receiver))));
+    if (installs.length === 0) {
+        return [];
+    }
+    const instances = new Map();
+    const instancesOf = (key) => {
+        let made = instances.get(key);
+        if (made === undefined) {
+            const property = properties.get(key);
+            const type = property === undefined ? undefined : must(queries.typeOfSymbol(property));
+            made = (type === undefined ? [] : must(queries.signaturesOf(type, SignatureKind.Construct))).flatMap((signature) => must(queries.returnTypeOf(signature)) ?? []);
+            instances.set(key, made);
+        }
+        return made;
+    };
+    const carried = classesCarried(project, held, chains, sites, installs.map((write) => [write.value]));
+    return installs.flatMap((write, at) => {
+        const uses = carried[at] ?? [];
+        const made = uses.length === 0 ? [] : instancesOf(write.key);
+        return made.length === 0
+            ? []
+            : uses.map((use) => ({ id: use.id, site: write.site, global: write.key, instances: made }));
+    });
+}

package/dist/src/{interface-satisfaction.js → exemptions/interface-satisfaction.js}

@@ -3,85 +3,41 @@
  * reaches a position typed as an interface, or an object type a type alias names, that
  * requires the member: an `implements` entry, a typed initializer, an assignment, an
  * argument, a return, an array element, an object property or an `as` or `satisfies`
- * operand. `this` is a value of its class; a type parameter reaches its constraint. The
+ * operand. `this` is a value of its class; a type parameter reaches its constraint. A
+ * class installed as a global reaches the instance type the global constructs, whether
+ * or not it is assignable to it, because a stub answers only what its caller uses. The
  * contextual lookup has no batch form, so it is asked only of a value of a target class.
  */
-import { isCallExpression, isClassDeclaration, isClassExpression, isClassStaticBlockDeclaration, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isHeritageClause, isMethodDeclaration, isNewExpression, isObjectLiteralExpression, isSetAccessorDeclaration, isTypeLiteralNode, ModifierFlags, SyntaxKind, } from "@typescript/native/ast";
+import { isCallExpression, isHeritageClause, isNewExpression, isTypeLiteralNode, SyntaxKind, } from "@typescript/native/ast";
 import { SymbolFlags } from "@typescript/native/sync";
-import { aliasChains } from "./alias-chain.js";
-import { emptyImplementation } from "./implementations.js";
-import { nodeKey } from "./inventory.js";
-import { renderPosition } from "./position.js";
-import { must } from "./query.js";
-import { handedOn, valuesOf } from "./value-flow.js";
+import { aliasChains } from "../alias-chain.js";
+import { emptyImplementation } from "../findings/implementations.js";
+import { installedGlobals } from "./installed-globals.js";
+import { renderPosition } from "../position.js";
+import { must } from "../query.js";
 /** Whether a type alias names one type: the client's type object carries the alias it was written through. */
 function aliased(type) {
     return type.aliasSymbol !== undefined;
 }
-/** Whether one node declares a static member, whose `this` is the class itself. */
-function isStatic(node) {
-    const flags = node.modifierFlags ?? 0;
-    return (flags & ModifierFlags.Static) !== 0;
-}
-/** Whether one node is a method or an accessor of an object literal, whose `this` is the literal. */
-function isObjectLiteralMethod(node) {
-    return ((isMethodDeclaration(node) ||
-        isGetAccessorDeclaration(node) ||
-        isSetAccessorDeclaration(node)) &&
-        isObjectLiteralExpression(node.parent));
-}
 /**
- * The classes, the `implements` entries and the flowing values of one project's own
- * files. `this` is the class an instance member belongs to, so a function that is not
- * an arrow, a static member and a static block each stop it.
+ * The named classes, the `implements` entries and the flowing values of one project's own
+ * files, a value `this` standing for the class it is an instance of.
  */
-function walk(files, declarations) {
-    const classes = [];
-    const clauses = [];
-    const flows = [];
-    for (const file of files) {
-        const visit = (node, self) => {
-            let inner = self;
-            if (isClassDeclaration(node) || isClassExpression(node)) {
-                const id = declarations.get(nodeKey(file, node));
-                const name = node.name;
-                const owner = id === undefined || name === undefined
-                    ? undefined
-                    : { id, name, generic: node.typeParameters !== undefined };
-                if (owner !== undefined) {
-                    classes.push(owner);
-                    for (const clause of node.heritageClauses ?? []) {
-                        if (isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword) {
-                            clauses.push(...clause.types.map((entry) => ({ owner, entry })));
-                        }
-                    }
-                }
-                inner = owner;
-            }
-            else if (isFunctionDeclaration(node) ||
-                isFunctionExpression(node) ||
-                isClassStaticBlockDeclaration(node) ||
-                isStatic(node) ||
-                isObjectLiteralMethod(node)) {
-                inner = undefined;
-            }
-            for (const written of handedOn(node)) {
-                for (const value of valuesOf(written)) {
-                    flows.push({
-                        value,
-                        self: value.kind === SyntaxKind.ThisKeyword ? inner : undefined,
-                    });
-                }
-            }
-            node.forEachChild((child) => {
-                visit(child, inner);
-            });
-        };
-        file.forEachChild((child) => {
-            visit(child, undefined);
-        });
-    }
-    return { classes, clauses, flows };
+function walked(sites) {
+    const classes = sites.classes.flatMap(({ id, node }) => node.name === undefined
+        ? []
+        : [{ id, name: node.name, generic: node.typeParameters !== undefined, node }]);
+    const byId = new Map(classes.map((owner) => [owner.id, owner]));
+    return {
+        classes,
+        clauses: classes.flatMap((owner) => (owner.node.heritageClauses ?? []).flatMap((clause) => isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword
+            ? clause.types.map((entry) => ({ owner, entry }))
+            : [])),
+        flows: sites.flows.map((flow) => ({
+            value: flow.value,
+            self: flow.self === undefined ? undefined : byId.get(flow.self),
+        })),
+    };
 }
 /**
  * The interface-satisfaction detector: for each class type that reaches an interface
@@ -91,8 +47,8 @@ function walk(files, declarations) {
 export function interfaceSatisfaction(input) {
     const { project, held, targetRoot } = input;
     const queries = project.queries;
-    const files = project.ownSourceFiles();
-    const { classes, clauses, flows } = walk(files, held.declarations);
+    const chains = aliasChains(project, held);
+    const { classes, clauses, flows } = walked(input.sites);
     if (classes.length === 0) {
         return [];
     }
@@ -197,13 +153,15 @@ export function interfaceSatisfaction(input) {
     const pairs = new Map();
     const reach = (owner, source, target, name, site) => {
         const key = `${String(source.id)}:${String(target.id)}`;
-        const pair = pairs.get(key);
+        let pair = pairs.get(key);
         if (pair === undefined) {
-            pairs.set(key, { owner, source, target, name, sites: [site] });
+            pair = { owner, source, target, name, sites: [site] };
+            pairs.set(key, pair);
         }
         else {
             pair.sites.push(site);
         }
+        return pair;
     };
     for (const clause of clauses) {
         const source = instanceOf.get(clause.owner.id);
@@ -237,14 +195,26 @@ export function interfaceSatisfaction(input) {
             }
         }
     });
-    const chains = aliasChains(project, held);
+    const byId = new Map(classes.map((owner) => [owner.id, owner]));
+    for (const one of installedGlobals(project, held, chains, input.sites)) {
+        const owner = byId.get(one.id);
+        const source = instanceOf.get(one.id);
+        if (owner === undefined || source === undefined) {
+            continue;
+        }
+        for (const instance of one.instances) {
+            reach(owner, source, instance, one.global, one.site).installed = one.global;
+        }
+    }
     const required = new Map();
     const members = new Map();
     const found = [];
-    const asking = [...pairs.values()];
-    const assignable = queries.assignableEach(asking);
-    for (const [index, pair] of asking.entries()) {
-        if (!must(assignable[index] ?? false)) {
+    const asking = [...pairs.values()].filter((pair) => pair.installed === undefined);
+    const assignable = new Set(queries
+        .assignableEach(asking)
+        .flatMap((answer, index) => (must(answer) ? [asking[index]] : [])));
+    for (const pair of pairs.values()) {
+        if (pair.installed === undefined && !assignable.has(pair)) {
             continue;
         }
         let names = required.get(pair.target.id);
@@ -267,7 +237,9 @@ export function interfaceSatisfaction(input) {
             ]));
             members.set(pair.owner.id, answering);
         }
-        const detail = `satisfies ${pair.name}`;
+        const detail = pair.installed === undefined
+            ? `satisfies ${pair.name}`
+            : `installed as the global ${pair.installed}`;
         for (const [name, methods] of names) {
             const member = answering.get(name);
             for (const id of member?.ids ?? []) {
@@ -284,44 +256,3 @@ export function interfaceSatisfaction(input) {
     }
     return found;
 }
-/**
- * Each project's records with every record dropped whose member implements only interface
- * methods nothing calls, unless every implementation of such a method is empty, and a
- * reference from each such method to the member, which then falls with the method.
- * `references` is every reference of the run, a consumer's included.
- */
-export function settledSatisfaction(projects, references) {
-    const methods = new Set(projects.flatMap((one) => one.held.symbols.filter((symbol) => symbol.kind === "interface-method").map((one) => one.id)));
-    const called = new Set(references.map((reference) => reference.to));
-    const bodies = new Map();
-    for (const record of projects.flatMap((one) => one.evidence)) {
-        for (const method of record.implementing?.methods ?? []) {
-            bodies.set(method, (bodies.get(method) ?? true) && record.implementing?.empty === true);
-        }
-    }
-    const uncalled = (method) => methods.has(method) && !called.has(method) && bodies.get(method) !== true;
-    return projects.map(({ evidence }) => {
-        const kept = [];
-        const added = [];
-        for (const record of evidence) {
-            const implemented = record.implementing?.methods ?? [];
-            if (record.class !== "interface-satisfaction" ||
-                implemented.length === 0 ||
-                !implemented.every(uncalled)) {
-                kept.push(record);
-                continue;
-            }
-            for (const method of implemented) {
-                added.push({
-                    from: method,
-                    to: record.id,
-                    position: record.site,
-                    use: "read",
-                    resolution: "override",
-                    test: false,
-                });
-            }
-        }
-        return { evidence: kept, references: added };
-    });
-}

package/dist/src/exemptions/lifecycle.js

@@ -0,0 +1,150 @@
+/**
+ * The exemption lifecycle: the classes of reason for which a declaration the reference
+ * graph alone would report is live all the same. A class is policy over what one
+ * project's checker answers, and its detector names the declarations it holds back. This
+ * module runs the detectors over one project, then settles every project's records
+ * against the run: the writes they wait for, the interface methods they wait to be
+ * called, and the mode and test files that decide which of them hold. It names no class:
+ * the composition hands it the table of the classes it has.
+ */
+import { EXEMPTION_CLASSES } from "../contract/contract.generated.js";
+import { byPosition } from "../position.js";
+import { Unanswerable } from "../query.js";
+import { bytewise } from "../text/compare.js";
+import { TS_EXEMPTION_CLASSES, typescriptVisibilityOf, } from "./classes.js";
+import { projectSites } from "./sites.js";
+/**
+ * Whether a class whose row states `allowed` may retain a member of one visibility. A
+ * declaration the inventory does not hold has no visibility to refuse it by.
+ */
+function retainable(allowed, visibility) {
+    if (visibility === "private") {
+        return allowed.private;
+    }
+    if (visibility === "private-name") {
+        return allowed.privateName;
+    }
+    return true;
+}
+/** The kinds of declaration each class can hold back, which a detector that stops holds back whole. */
+const RETAINABLE = new Map(EXEMPTION_CLASSES.flatMap((row) => "ts" in row.retainsKinds ? [[row.class, new Set(row.retainsKinds.ts)]] : []));
+/**
+ * What one detector holds back over one project. A detector that stops because the
+ * checker left a question it needs unanswered holds back every declaration of the
+ * project its class could hold back, each recorded at its own position, so the gap
+ * never yields a finding.
+ */
+function detected(exemptionClass, detect, input) {
+    try {
+        return detect(input);
+    }
+    catch (error) {
+        if (!(error instanceof Unanswerable)) {
+            throw error;
+        }
+        const kinds = RETAINABLE.get(exemptionClass);
+        return input.held.symbols
+            .filter((symbol) => kinds?.has(symbol.kind) === true)
+            .map((symbol) => ({
+            id: symbol.id,
+            detail: "kept live by a question the checker did not answer",
+            site: symbol.position,
+            unanswered: true,
+        }));
+    }
+}
+/**
+ * Every record one project's detectors found, one per piece of evidence, before the run
+ * settles which of them hold. Classes run in the vocabulary's order and a switched-off
+ * class runs not at all; evidence on a private member the class's row says it cannot
+ * retain is dropped, whatever the detector found.
+ */
+export function detect(input, detectors, disabled) {
+    const visibility = new Map(input.held.symbols.map((symbol) => [symbol.id, symbol.visibility]));
+    const sited = { ...input, sites: projectSites(input.project, input.held) };
+    return TS_EXEMPTION_CLASSES.flatMap((exemptionClass) => {
+        const run = detectors.get(exemptionClass);
+        if (run === undefined || disabled.has(exemptionClass)) {
+            return [];
+        }
+        const allowed = typescriptVisibilityOf(exemptionClass);
+        return detected(exemptionClass, run, sited).flatMap((evidence) => retainable(allowed, visibility.get(evidence.id))
+            ? [{ ...evidence, class: exemptionClass }]
+            : []);
+    });
+}
+/**
+ * Every project's records settled against the run, in three steps. A record that holds
+ * only while written holds where a write the mode counts stores into its declaration.
+ * A record whose member implements only interface methods nothing calls is dropped,
+ * unless every implementation of such a method is empty. Under a production mode a
+ * record whose evidence a test file writes holds nothing, and is a test reference to its
+ * declaration, as a reference the test file wrote would be.
+ */
+export function settle(projects, run) {
+    const written = projects.map((one) => one.records.flatMap(({ whileWritten, ...record }) => whileWritten === undefined || run.written.has(record.id) ? [record] : []));
+    const methods = new Set(projects.flatMap((one) => one.held.symbols.filter((symbol) => symbol.kind === "interface-method").map((one) => one.id)));
+    const called = new Set(run.references.map((reference) => reference.to));
+    const bodies = new Map();
+    for (const record of written.flat()) {
+        for (const method of record.implementing?.methods ?? []) {
+            bodies.set(method, (bodies.get(method) ?? true) && record.implementing?.empty === true);
+        }
+    }
+    const uncalled = (method) => methods.has(method) && !called.has(method) && bodies.get(method) !== true;
+    return projects.map((project, index) => {
+        const files = new Map(project.held.symbols
+            .filter((symbol) => symbol.kind === "file")
+            .map((symbol) => [symbol.position.path, symbol.id]));
+        const kept = [];
+        const references = [];
+        const tested = [];
+        for (const record of written[index] ?? []) {
+            const implemented = record.implementing?.methods ?? [];
+            if (implemented.length > 0 && implemented.every(uncalled)) {
+                references.push(...implemented.map((method) => ({
+                    from: method,
+                    to: record.id,
+                    position: record.site,
+                    use: "read",
+                    resolution: "override",
+                    test: false,
+                })));
+            }
+            else if (run.mode.production && project.testFiles.has(record.site.path)) {
+                const from = files.get(record.site.path);
+                if (from !== undefined) {
+                    tested.push({
+                        from,
+                        to: record.id,
+                        position: record.site,
+                        use: "read",
+                        resolution: "syntax",
+                        test: true,
+                    });
+                }
+            }
+            else {
+                kept.push(record);
+            }
+        }
+        return { records: exemptionsOf(kept), references: [...references, ...tested] };
+    });
+}
+/**
+ * Records as a run holds them: ordered by site, then class, then declaration, and one
+ * per declaration, class, detail and file it holds while live, the one at the first
+ * site. A fact found at many sites, or by several projects, is one record.
+ */
+export function exemptionsOf(found) {
+    const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || bytewise(a.class, b.class) || bytewise(a.id, b.id));
+    const seen = new Set();
+    return ordered.filter((record) => {
+        const fact = [record.id, record.class, record.detail, record.whileLive ?? ""].join("\u0000");
+        if (seen.has(fact)) {
+            return false;
+        }
+        seen.add(fact);
+        return true;
+    });
+}

package/dist/src/{reflective-lookup.js → exemptions/reflective-lookup.js}

@@ -14,9 +14,9 @@
  */
 import { isCallExpression, isElementAccessExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isPropertyAccessExpression, isStringLiteral, } from "@typescript/native/ast";
 import { TypeFlags } from "@typescript/native/sync";
-import { memberNames } from "./member-names.js";
-import { renderPosition } from "./position.js";
-import { isAnswered, UNANSWERED } from "./query.js";
+import { memberNames } from "../member-names.js";
+import { renderPosition } from "../position.js";
+import { isAnswered, UNANSWERED } from "../query.js";
 /** The `Reflect` methods whose second argument is a property key. */
 const REFLECT_KEYED = new Set(["get", "set", "has"]);
 /** The text one key denotes, where it is literal text. */