@cplieger/deadset-ts 3.1.0 → 3.3.0

package/dist/src/interface-satisfaction.js

@@ -0,0 +1,310 @@
+/**
+ * The interface-satisfaction class: a class member is held back when a value of the
+ * class reaches a position the checker types as an interface requiring a member of
+ * that name, so a caller reaches the member through the interface while no name in
+ * the program resolves to it.
+ *
+ * A value reaches such a position as an `implements` entry, the initializer of a
+ * declaration whose type is written, an assignment, an argument, a returned value, an
+ * array element, an object property, or the operand of `as` or `satisfies`, read
+ * through parentheses, conditionals and the operators whose result is an operand.
+ * `this` in an instance member is a value of its class. Types are asked in batches;
+ * the contextual lookup has none, so it is asked only of a value whose type is a class
+ * of the target, and each distinct pair, interface and class is asked once.
+ */
+import { isArrayLiteralExpression, isArrowFunction, isAsExpression, isBinaryExpression, isCallExpression, isClassDeclaration, isClassExpression, isClassStaticBlockDeclaration, isConditionalExpression, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isHeritageClause, isIdentifier, isMethodDeclaration, isNewExpression, isObjectLiteralExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAssignment, isPropertyDeclaration, isReturnStatement, isSatisfiesExpression, isSetAccessorDeclaration, isShorthandPropertyAssignment, isSpreadElement, isVariableDeclaration, ModifierFlags, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.js";
+import { nodeKey } from "./inventory.js";
+import { renderPosition } from "./position.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The operators of an assignment whose right side is stored into the left side's type. */
+const STORES = new Set([
+    SyntaxKind.EqualsToken,
+    SyntaxKind.QuestionQuestionEqualsToken,
+    SyntaxKind.BarBarEqualsToken,
+    SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+/** 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));
+}
+/** Whether a declaration writes its type, so its initializer is read in that type's context. */
+function writesType(node) {
+    return node.type !== undefined;
+}
+/**
+ * The values one written expression hands on: the expression itself, or what it
+ * evaluates to through parentheses, a conditional and the operators whose result is
+ * one of their operands.
+ */
+function valuesOf(expression) {
+    if (isParenthesizedExpression(expression)) {
+        return valuesOf(expression.expression);
+    }
+    if (isConditionalExpression(expression)) {
+        return [...valuesOf(expression.whenTrue), ...valuesOf(expression.whenFalse)];
+    }
+    if (isBinaryExpression(expression)) {
+        const operator = expression.operatorToken.kind;
+        if (operator === SyntaxKind.QuestionQuestionToken || operator === SyntaxKind.BarBarToken) {
+            return [...valuesOf(expression.left), ...valuesOf(expression.right)];
+        }
+        if (operator === SyntaxKind.AmpersandAmpersandToken || operator === SyntaxKind.CommaToken) {
+            return valuesOf(expression.right);
+        }
+    }
+    return [expression];
+}
+/** The expressions one node hands to a position typed by its context. */
+function handedOn(node) {
+    if ((isVariableDeclaration(node) || isPropertyDeclaration(node) || isParameterDeclaration(node)) &&
+        node.initializer !== undefined &&
+        writesType(node)) {
+        return [node.initializer];
+    }
+    if (isBinaryExpression(node) && STORES.has(node.operatorToken.kind)) {
+        return [node.right];
+    }
+    if (isCallExpression(node) || isNewExpression(node)) {
+        return (node.arguments ?? []).filter((argument) => !isSpreadElement(argument));
+    }
+    if (isReturnStatement(node)) {
+        return node.expression === undefined ? [] : [node.expression];
+    }
+    if (isArrowFunction(node)) {
+        return node.body.kind === SyntaxKind.Block ? [] : [node.body];
+    }
+    if (isArrayLiteralExpression(node)) {
+        return node.elements.filter((element) => !isSpreadElement(element) && element.kind !== SyntaxKind.OmittedExpression);
+    }
+    if (isPropertyAssignment(node)) {
+        return [node.initializer];
+    }
+    if (isShorthandPropertyAssignment(node)) {
+        return isIdentifier(node.name) ? [node.name] : [];
+    }
+    if (isAsExpression(node) || isSatisfiesExpression(node)) {
+        return [node.expression];
+    }
+    return [];
+}
+/**
+ * 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.
+ */
+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 };
+}
+/**
+ * The interface-satisfaction detector: for each class type that reaches an interface
+ * type it is assignable to, the class's members whose names the interface's members
+ * carry, each recorded at the place the value flows.
+ */
+export function interfaceSatisfaction(input) {
+    const { project, held, targetRoot } = input;
+    const checker = project.checker;
+    const files = project.ownSourceFiles();
+    const { classes, clauses, flows } = walk(files, held.declarations);
+    if (classes.length === 0) {
+        return [];
+    }
+    // One list, so the batches are capped runs of the whole project rather than of a
+    // file: a class's name, an `implements` entry and a value are each one question.
+    const asked = [
+        ...classes.map((owner) => owner.name),
+        ...clauses.map((clause) => clause.entry),
+        ...flows.filter((flow) => flow.self === undefined).map((flow) => flow.value),
+    ];
+    const typeAt = new Map();
+    for (let from = 0; from < asked.length; from += DEFAULT_BATCH_CAP) {
+        const run = asked.slice(from, from + DEFAULT_BATCH_CAP);
+        checker.getTypeAtLocation(run).forEach((type, index) => {
+            const node = run[index];
+            if (type !== undefined && node !== undefined) {
+                typeAt.set(node, type);
+            }
+        });
+    }
+    const classOfType = new Map();
+    const instanceOf = new Map();
+    for (const owner of classes) {
+        const type = typeAt.get(owner.name);
+        if (type !== undefined) {
+            classOfType.set(type.id, owner);
+            instanceOf.set(owner.id, type);
+        }
+    }
+    const instantiates = classes.some((owner) => owner.generic);
+    const constituents = new Map();
+    const partsOf = (type) => {
+        if (!type.isUnionType() && !type.isIntersectionType()) {
+            return [type];
+        }
+        let parts = constituents.get(type.id);
+        if (parts === undefined) {
+            parts = type.getTypes();
+            constituents.set(type.id, parts);
+        }
+        return parts;
+    };
+    const targets = new Map();
+    /** The classes of the target one value's type is an instance of, with the instance type. */
+    const classesOf = (type) => partsOf(type).flatMap((part) => {
+        const direct = classOfType.get(part.id);
+        if (direct !== undefined) {
+            return [{ owner: direct, type: part }];
+        }
+        if (!instantiates || !part.isTypeReference()) {
+            return [];
+        }
+        if (!targets.has(part.id)) {
+            targets.set(part.id, classOfType.get(part.getTarget().id));
+        }
+        const generic = targets.get(part.id);
+        return generic === undefined ? [] : [{ owner: generic, type: part }];
+    });
+    const interfaceNames = new Map();
+    /** The interface types one position's type is or holds, each with the interface's name. */
+    const interfacesOf = (type) => partsOf(type).flatMap((part) => {
+        if (!interfaceNames.has(part.id)) {
+            const symbol = part.isObjectType() ? part.getSymbol() : undefined;
+            interfaceNames.set(part.id, symbol !== undefined && (symbol.flags & SymbolFlags.Interface) !== 0
+                ? symbol.name
+                : undefined);
+        }
+        const name = interfaceNames.get(part.id);
+        return name === undefined ? [] : [{ type: part, name }];
+    });
+    const pairs = new Map();
+    const reach = (owner, source, target, name, site) => {
+        const key = `${String(source.id)}:${String(target.id)}`;
+        const pair = pairs.get(key);
+        if (pair === undefined) {
+            pairs.set(key, { owner, source, target, name, sites: [site] });
+        }
+        else {
+            pair.sites.push(site);
+        }
+    };
+    for (const clause of clauses) {
+        const source = instanceOf.get(clause.owner.id);
+        const target = typeAt.get(clause.entry);
+        if (source === undefined || target === undefined) {
+            continue;
+        }
+        for (const reached of interfacesOf(target)) {
+            reach(clause.owner, source, reached.type, reached.name, clause.entry);
+        }
+    }
+    for (const flow of flows) {
+        const self = flow.self === undefined ? undefined : instanceOf.get(flow.self.id);
+        const valueType = typeAt.get(flow.value);
+        const sources = flow.self !== undefined && self !== undefined
+            ? [{ owner: flow.self, type: self }]
+            : valueType === undefined
+                ? []
+                : classesOf(valueType);
+        if (sources.length === 0) {
+            continue;
+        }
+        const position = checker.getContextualType(flow.value);
+        if (position === undefined) {
+            continue;
+        }
+        for (const reached of interfacesOf(position)) {
+            for (const source of sources) {
+                reach(source.owner, source.type, reached.type, reached.name, flow.value);
+            }
+        }
+    }
+    const chains = aliasChains(project, held);
+    const required = new Map();
+    const members = new Map();
+    const found = [];
+    for (const pair of pairs.values()) {
+        if (!checker.isTypeAssignableTo(pair.source, pair.target)) {
+            continue;
+        }
+        let names = required.get(pair.target.id);
+        if (names === undefined) {
+            names = new Set(checker.getPropertiesOfType(pair.target).map((property) => property.escapedName));
+            required.set(pair.target.id, names);
+        }
+        let answering = members.get(pair.owner.id);
+        if (answering === undefined) {
+            const instance = instanceOf.get(pair.owner.id) ?? pair.source;
+            answering = new Map(checker
+                .getPropertiesOfType(instance)
+                .map((property) => [property.escapedName, chains.declarationsOf(property)]));
+            members.set(pair.owner.id, answering);
+        }
+        const detail = `satisfies ${pair.name}`;
+        for (const name of names) {
+            for (const id of answering.get(name) ?? []) {
+                for (const site of pair.sites) {
+                    found.push({
+                        id,
+                        detail,
+                        site: renderPosition(site.getSourceFile(), targetRoot, site.getStart()),
+                    });
+                }
+            }
+        }
+    }
+    return found;
+}

package/dist/src/member-names.js

@@ -0,0 +1,76 @@
+/**
+ * The members of one project's inventory by the name each is written with, for the
+ * classes whose evidence is a name rather than a type relation: a template and a
+ * string key both hold a name and nothing else, so each holds back every member of
+ * that name its own mechanism can reach.
+ */
+import { isIdentifier, isNumericLiteral, isPrivateIdentifier, isStringLiteral, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+/** The kinds of declaration a member name can name. */
+const MEMBER_KINDS = new Set([
+    "method",
+    "class-member",
+    "interface-method",
+    "type-member",
+    "enum-member",
+]);
+/**
+ * The name a member declaration is written with: an identifier's text, a private
+ * name's text without its `#`, a string key's value and a numeric key's text. A
+ * private name is indexed under the name a template or a string would spell, so the
+ * rule that no such evidence holds it back is the framework's alone. A computed key
+ * names nothing a string can be equal to before the program runs.
+ */
+function writtenName(name) {
+    if (name === undefined) {
+        return undefined;
+    }
+    if (isPrivateIdentifier(name)) {
+        return name.text.replace(/^#/u, "");
+    }
+    if (isIdentifier(name)) {
+        return name.text;
+    }
+    if (isStringLiteral(name) || isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}
+/**
+ * Every member the inventory holds, keyed by the name it is written with, each
+ * member once and in inventory order. A getter and a setter of one name are one
+ * member.
+ */
+export function memberNames(files, held) {
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    const named = new Map();
+    for (const file of files) {
+        const visit = (node) => {
+            const id = held.declarations.get(nodeKey(file, node));
+            const symbol = id === undefined ? undefined : byId.get(id);
+            if (symbol !== undefined && MEMBER_KINDS.has(symbol.kind)) {
+                const name = writtenName(node.name);
+                if (name !== undefined) {
+                    named.set(symbol.id, name);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        visit(file);
+    }
+    const index = new Map();
+    for (const symbol of held.symbols) {
+        const name = named.get(symbol.id);
+        if (name === undefined) {
+            continue;
+        }
+        const members = index.get(name);
+        if (members === undefined) {
+            index.set(name, [symbol]);
+        }
+        else {
+            members.push(symbol);
+        }
+    }
+    return index;
+}

package/dist/src/references.js

@@ -1,4 +1,4 @@
-import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
 import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
@@ -207,6 +207,7 @@ function sitesOf(file, declarations, fileId) {
     const found = [];
     const links = [];
     const evaluations = [];
+    const decorated = [];
     const writes = new Set();
     const declared = new Set();
     const shorthands = new Map();
@@ -251,12 +252,17 @@ function sitesOf(file, declarations, fileId) {
         const outer = enclosing;
         if (held !== undefined) {
             enclosing = held;
+            for (const modifier of node.modifiers ?? []) {
+                if (isDecorator(modifier)) {
+                    decorated.push({ decorator: modifier, declaration: held });
+                }
+            }
         }
         node.forEachChild(visit);
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return { uses: found, links, evaluations };
+    return { uses: found, links, evaluations, decorated };
 }
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
@@ -336,7 +342,20 @@ export function references(project, held, targetRoot, options) {
         if (test) {
             tests.push(path);
         }
-        const { uses, links, evaluations } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        const { uses, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        // A decorator is written inside the declaration it is attached to and receives it,
+        // so the declaration is used where the decorator is written, whatever the
+        // decorator does with it.
+        for (const { decorator, declaration } of decorated) {
+            found.push({
+                from: declaration,
+                to: declaration,
+                position: renderPosition(file, targetRoot, decorator.getStart()),
+                use: "decorator",
+                resolution: "syntax",
+                test,
+            });
+        }
         // One batch per capped run of the file's name nodes, the re-exports' nodes after
         // the uses and the evaluated modules' specifiers last, each node once: a bare star
         // re-export's specifier is a link and an evaluation both. A shorthand is left out

package/dist/src/reflective-lookup.js

@@ -0,0 +1,96 @@
+/**
+ * The reflective-lookup class: a member is held back, at the lowest confidence, when
+ * a string literal equal to its name is the key of an element access or the property
+ * key of a `Reflect.get`, `Reflect.set` or `Reflect.has` call, because the member is
+ * then read by a name the program computes nowhere the reference pass can follow.
+ *
+ * The evidence is a string beside a lookup rather than a type relation, so the
+ * string reaches every member of that name on any type, static members included,
+ * and every record names the string's own position. A key that is not literal text
+ * holds nothing back: a computed name is the case no exact rule serves. `Reflect` is
+ * the global one only: a local declaration of that name is a different object.
+ */
+import { isCallExpression, isElementAccessExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isPropertyAccessExpression, isStringLiteral, } from "@typescript/native/unstable/ast";
+import { memberNames } from "./member-names.js";
+import { renderPosition } from "./position.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. */
+function literalText(node) {
+    if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+        return node.text;
+    }
+    return undefined;
+}
+/** Every lookup one file writes with a literal key, in source order. */
+function lookupsOf(file) {
+    const found = [];
+    const visit = (node) => {
+        if (isElementAccessExpression(node)) {
+            const name = literalText(node.argumentExpression);
+            if (name !== undefined) {
+                found.push({
+                    key: node.argumentExpression,
+                    name,
+                    callee: `[${JSON.stringify(name)}]`,
+                    reflect: undefined,
+                });
+            }
+        }
+        else if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+            const target = node.expression.expression;
+            const method = node.expression.name;
+            const key = node.arguments[1];
+            const name = literalText(key);
+            if (isIdentifier(target) &&
+                target.text === "Reflect" &&
+                isIdentifier(method) &&
+                REFLECT_KEYED.has(method.text) &&
+                key !== undefined &&
+                name !== undefined) {
+                found.push({ key, name, callee: `Reflect.${method.text}`, reflect: target });
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * The reflective-lookup detector: every member whose name a literal key of a lookup
+ * spells, recorded at the key.
+ */
+export function reflectiveLookup(input) {
+    const { project, held, targetRoot } = input;
+    const files = project.ownSourceFiles();
+    const lookups = files.flatMap(lookupsOf);
+    if (lookups.length === 0) {
+        return [];
+    }
+    // Whether each written `Reflect` is the global one, asked in one batch: a
+    // declaration of that name in one of the project's own files shadows it.
+    const ownFiles = new Set(files.map((file) => file.fileName));
+    const reflects = lookups.flatMap((lookup) => lookup.reflect === undefined ? [] : [lookup.reflect]);
+    const global = new Set();
+    if (reflects.length > 0) {
+        project.symbolsAt(reflects.map((node) => project.handle(node))).forEach((symbol, index) => {
+            const node = reflects[index];
+            const declaredHere = symbol?.declarations.some((declaration) => ownFiles.has(declaration.path));
+            if (node !== undefined && declaredHere === false) {
+                global.add(node);
+            }
+        });
+    }
+    const members = memberNames(files, held);
+    const found = [];
+    for (const lookup of lookups) {
+        if (lookup.reflect !== undefined && !global.has(lookup.reflect)) {
+            continue;
+        }
+        const site = renderPosition(lookup.key.getSourceFile(), targetRoot, lookup.key.getStart());
+        for (const member of members.get(lookup.name) ?? []) {
+            found.push({ id: member.id, detail: `looked up by ${lookup.callee}`, site });
+        }
+    }
+    return found;
+}

package/dist/src/run.js

@@ -1,6 +1,7 @@
-import { runRoots } from "./analysis.js";
+import { runRoots, runSweep } from "./analysis.js";
 import { ConfigError, REPOSITORY_DOCUMENT } from "./config.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
+import { retainedLines } from "./exempt.js";
 import { joinPath, resolvePath } from "./paths.js";
 import { printConfig } from "./print.js";
 import { resolve, resolveMatrix } from "./resolve.js";
@@ -174,6 +175,9 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     if (verb === "print-roots") {
         return printRootsVerb(args.slice(1), out, err, host, openClient);
     }
+    if (verb === "print-retained") {
+        return printRetainedVerb(args.slice(1), out, err, host, openClient);
+    }
     if (verb !== undefined && VERBS.includes(verb)) {
         err.write(`deadset-ts: ${verb} is not implemented\n`);
         return EXIT_USAGE;
@@ -276,6 +280,34 @@ function printRootsVerb(args, out, err, host, openClient) {
         return refuse(error, err);
     }
 }
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+function printRetainedVerb(args, out, err, host, openClient) {
+    let engine;
+    try {
+        const options = readOptions(args);
+        const { config } = resolve(inputsOf(host, options));
+        const scope = scopeOf(host, options);
+        engine = openClient(false);
+        const swept = runSweep(engine, host, scope, config, {
+            marked: [],
+            mode: { production: true },
+        });
+        for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+            out.write(`${line}\n`);
+        }
+        return EXIT_CLEAN;
+    }
+    catch (error) {
+        engine?.close();
+        return refuse(error, err);
+    }
+}
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error, err) {
     if (error instanceof ConfigError) {