@cplieger/deadset-ts 1.1.0 → 2.0.0

package/dist/src/references.js

@@ -0,0 +1,420 @@
+import { isArrayLiteralExpression, isBinaryExpression, isDeleteExpression, isElementAccessExpression, isForInStatement, isForOfStatement, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { byPosition, renderPosition } from "./position.js";
+/**
+ * The batch cap a run takes when the configuration names none. It bounds the size of
+ * one answer rather than the work: the median file is one batch at this cap and the
+ * largest production file a handful.
+ */
+export const DEFAULT_BATCH_CAP = 4096;
+/**
+ * The operators whose left side one assignment stores into. A compound assignment is
+ * among them: it reads its target only to write the result back, so nothing else
+ * receives what it read, and a declaration whose every other reference is one of these
+ * carries no information out of itself.
+ */
+const ASSIGNMENTS = new Set([
+    SyntaxKind.EqualsToken,
+    SyntaxKind.PlusEqualsToken,
+    SyntaxKind.MinusEqualsToken,
+    SyntaxKind.AsteriskEqualsToken,
+    SyntaxKind.AsteriskAsteriskEqualsToken,
+    SyntaxKind.SlashEqualsToken,
+    SyntaxKind.PercentEqualsToken,
+    SyntaxKind.LessThanLessThanEqualsToken,
+    SyntaxKind.GreaterThanGreaterThanEqualsToken,
+    SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken,
+    SyntaxKind.AmpersandEqualsToken,
+    SyntaxKind.BarEqualsToken,
+    SyntaxKind.BarBarEqualsToken,
+    SyntaxKind.AmpersandAmpersandEqualsToken,
+    SyntaxKind.QuestionQuestionEqualsToken,
+    SyntaxKind.CaretEqualsToken,
+]);
+/**
+ * The declaration forms that name something declared elsewhere. Each is a link rather
+ * than a declaration of what it names, so a reference through one names the next link
+ * and, at the end of the chain, the declaration itself: a re-export something imports
+ * is used, and so is the declaration behind it.
+ */
+const ALIASES = new Set([
+    SyntaxKind.ImportClause,
+    SyntaxKind.ImportEqualsDeclaration,
+    SyntaxKind.ImportSpecifier,
+    SyntaxKind.NamespaceImport,
+    SyntaxKind.ExportAssignment,
+    SyntaxKind.ExportSpecifier,
+    SyntaxKind.NamespaceExport,
+]);
+/** Whether one node is an identifier or a private name, the two forms a name takes. */
+function isName(node) {
+    return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
+}
+/** The expression one node is, through however many parentheses are written around it. */
+function unparenthesized(node) {
+    let held = node;
+    while (isParenthesizedExpression(held)) {
+        held = held.expression;
+    }
+    return held;
+}
+/**
+ * Records the name one store writes into.
+ *
+ * A property access writes the member it names. An element access writes the collection
+ * it stores into, because a collection a module only ever stores into holds nothing
+ * anything reads, and the key is no declaration of the target. A destructuring target
+ * writes each name it binds, through the spreads and the nested patterns it binds them
+ * in.
+ */
+function markWrite(target, writes) {
+    const held = unparenthesized(target);
+    if (isName(held)) {
+        writes.add(held.pos);
+        return;
+    }
+    if (isPropertyAccessExpression(held)) {
+        if (isName(held.name)) {
+            writes.add(held.name.pos);
+        }
+        return;
+    }
+    if (isElementAccessExpression(held)) {
+        markWrite(held.expression, writes);
+        return;
+    }
+    if (isArrayLiteralExpression(held)) {
+        for (const element of held.elements) {
+            markWrite(element, writes);
+        }
+        return;
+    }
+    if (isObjectLiteralExpression(held)) {
+        for (const property of held.properties) {
+            if (isPropertyAssignment(property)) {
+                markWrite(property.initializer, writes);
+                continue;
+            }
+            if (isShorthandPropertyAssignment(property)) {
+                markWrite(property.name, writes);
+                continue;
+            }
+            if (isSpreadAssignment(property)) {
+                markWrite(property.expression, writes);
+            }
+        }
+        return;
+    }
+    if (isSpreadElement(held)) {
+        markWrite(held.expression, writes);
+    }
+}
+/**
+ * Records every store one node performs: an assignment, a compound assignment, an
+ * increment or a decrement, a `delete`, and an iteration that assigns to a name declared
+ * elsewhere. An iteration that declares its own name stores into nothing the inventory
+ * holds.
+ */
+function markStores(node, writes) {
+    if (isBinaryExpression(node)) {
+        if (ASSIGNMENTS.has(node.operatorToken.kind)) {
+            markWrite(node.left, writes);
+        }
+        return;
+    }
+    if (isPrefixUnaryExpression(node) || isPostfixUnaryExpression(node)) {
+        if (node.operator === SyntaxKind.PlusPlusToken ||
+            node.operator === SyntaxKind.MinusMinusToken) {
+            markWrite(node.operand, writes);
+        }
+        return;
+    }
+    if (isDeleteExpression(node)) {
+        markWrite(node.expression, writes);
+        return;
+    }
+    if (isForInStatement(node) || isForOfStatement(node)) {
+        if (node.initializer.kind !== SyntaxKind.VariableDeclarationList) {
+            markWrite(node.initializer, writes);
+        }
+    }
+}
+/**
+ * Every name node one file holds that is a use rather than a declaration, in source
+ * order, each with the declaration that encloses it and the use it makes.
+ *
+ * One walk answers all three, because the three facts are positional and a second walk
+ * would have to agree with this one about which nodes are names. A name that is the
+ * declared name of the declaration it belongs to is left out: it is where that
+ * declaration is written rather than a use of it, which is what makes a declaration
+ * referenced only from its own site an unreferenced declaration.
+ */
+function sitesOf(file, declarations, fileId) {
+    const found = [];
+    const writes = new Set();
+    const declared = new Set();
+    const shorthands = new Map();
+    let enclosing = fileId;
+    const markNames = (node) => {
+        if (isShorthandPropertyAssignment(node)) {
+            shorthands.set(node.name.pos, node);
+            return;
+        }
+        // A property access carries the member it names where a declaration carries its
+        // declared name, and it is the one form of the grammar that does.
+        if (isPropertyAccessExpression(node)) {
+            return;
+        }
+        const named = node;
+        for (const name of [named.name, named.propertyName]) {
+            if (name !== undefined && isName(name)) {
+                declared.add(name.pos);
+            }
+        }
+    };
+    const visit = (node) => {
+        if (isName(node)) {
+            if (!declared.has(node.pos)) {
+                found.push({
+                    node,
+                    shorthand: shorthands.get(node.pos),
+                    from: enclosing,
+                    use: writes.has(node.pos) ? "write" : "read",
+                });
+            }
+            return;
+        }
+        markNames(node);
+        markStores(node, writes);
+        const held = declarations.get(nodeKey(file, node));
+        const outer = enclosing;
+        if (held !== undefined) {
+            enclosing = held;
+        }
+        node.forEachChild(visit);
+        enclosing = outer;
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * One literal run of a pattern, with every character the expression syntax claims
+ * escaped.
+ *
+ * The set is the syntax characters and the solidus, and it is closed: an escape of any
+ * other character is refused outright by the expression syntax under the unicode flag,
+ * so escaping a hyphen, which needs none outside a character class, would refuse every
+ * pattern that names a hyphenated path.
+ */
+function quoted(text) {
+    return text.replaceAll(/[.*+?^${}()|[\]\\/]/gu, (character) => `\\${character}`);
+}
+/**
+ * The expression one glob pattern denotes. `**` spans path separators while `*` and `?`
+ * do not, a brace list is an alternation of its members, and every other character
+ * stands for itself.
+ */
+function expressionOf(pattern) {
+    let source = "^";
+    let at = 0;
+    while (at < pattern.length) {
+        const rest = pattern.slice(at);
+        if (rest.startsWith("**/")) {
+            source += "(?:[^/]*/)*";
+            at += 3;
+            continue;
+        }
+        if (rest.startsWith("**")) {
+            source += ".*";
+            at += 2;
+            continue;
+        }
+        const character = pattern[at] ?? "";
+        at += 1;
+        if (character === "*") {
+            source += "[^/]*";
+            continue;
+        }
+        if (character === "?") {
+            source += "[^/]";
+            continue;
+        }
+        if (character === "{") {
+            const close = pattern.indexOf("}", at);
+            if (close < 0) {
+                source += "\\{";
+                continue;
+            }
+            source += `(?:${pattern.slice(at, close).split(",").map(quoted).join("|")})`;
+            at = close + 1;
+            continue;
+        }
+        source += quoted(character);
+    }
+    return new RegExp(`${source}$`, "u");
+}
+/**
+ * The name one test-file rule takes. A rule's name is a word list the report's own
+ * vocabulary spells, which cannot carry a pattern, so a rule is named by the place of
+ * its pattern in the configured list.
+ */
+function patternRule(index) {
+    return `test-file-pattern-${String(index + 1)}`;
+}
+/** Two strings ordered bytewise, which is the order every set of a run is read in. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * Every reference one project's own files make to the project's own declarations, in
+ * position order, and the test-file rules that classified those files.
+ *
+ * `held` is the inventory of the same project, whose declaration map is what a resolved
+ * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
+ * against, which is the root the inventory was read against.
+ *
+ * The order is by the referencing position, then by the declaration named, the
+ * declaration referencing it and the use. That is a total order because one name
+ * references one declaration once from one declaration, while a chain of aliases reaches
+ * several declarations at one position.
+ */
+export function references(project, held, targetRoot, options) {
+    const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
+    const declarations = held.declarations;
+    const patterns = options.testFiles.map(expressionOf);
+    const matched = options.testFiles.map(() => 0);
+    const found = [];
+    const reached = new Map();
+    let batched = 0;
+    let fileBatches = 0;
+    let residueFallbacks = 0;
+    let shorthandLookups = 0;
+    let aliasSteps = 0;
+    const files = project.ownSourceFiles();
+    const ownFiles = new Set(files.map((file) => file.fileName));
+    /** The identifier of the declaration one node of this program is, where it is one. */
+    const declaredAt = (node) => declarations.get(nodeKey(node.getSourceFile(), node));
+    /**
+     * The declarations one symbol names: the declaration it is, and every link of the
+     * alias chain it stands at the head of. A re-export something imports is used and so
+     * is the declaration behind it, so both are named; a link this project does not
+     * declare is stepped over rather than recorded.
+     *
+     * A declaration handle carries the file it is in and the syntax it is written as, so
+     * both questions the walk asks of a declaration are answered before it is resolved: a
+     * declaration outside the project's own files belongs to another program and is never
+     * read, which is what keeps the pass from fetching a library file to discover that the
+     * inventory does not hold what is in it.
+     */
+    const targetsOf = (symbol) => {
+        const cached = reached.get(symbol.id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const targets = [];
+        const walked = new Set();
+        let at = symbol;
+        let stepped = false;
+        while (at !== undefined && !walked.has(at.id)) {
+            walked.add(at.id);
+            let alias = false;
+            for (const handle of at.declarations) {
+                alias = alias || ALIASES.has(handle.kind);
+                if (!ownFiles.has(handle.path)) {
+                    continue;
+                }
+                const node = project.declarationAt(handle)?.node;
+                const id = node === undefined ? undefined : declaredAt(node);
+                if (id !== undefined && !targets.some((target) => target.id === id)) {
+                    targets.push({ id, stepped });
+                }
+            }
+            if (!alias) {
+                break;
+            }
+            at = project.aliasStepOf(at);
+            aliasSteps += 1;
+            stepped = true;
+        }
+        reached.set(symbol.id, targets);
+        return targets;
+    };
+    /** The symbol one site resolves to, asking only the accessor the site's form names. */
+    const symbolFor = (site, answered) => {
+        if (site.shorthand !== undefined) {
+            shorthandLookups += 1;
+            return project.shorthandValueAt(project.handle(site.shorthand));
+        }
+        const batched = answered.get(site.node.pos);
+        if (batched !== undefined) {
+            return batched;
+        }
+        residueFallbacks += 1;
+        return project.resolvedSymbolAt(project.handle(site.node));
+    };
+    for (const file of files) {
+        const path = renderPosition(file, targetRoot, 0).path;
+        let test = false;
+        patterns.forEach((pattern, index) => {
+            if (pattern.test(path)) {
+                matched[index] = (matched[index] ?? 0) + 1;
+                test = true;
+            }
+        });
+        const sites = sitesOf(file, declarations, declaredAt(file) ?? "");
+        // One batch per capped run of the file's name nodes. A shorthand is left out of
+        // the batch: its name resolves to the property the literal declares, so the batch's
+        // answer for it would name something this project's inventory never holds.
+        const batching = sites.filter((site) => site.shorthand === undefined);
+        const answered = new Map();
+        batched += batching.length;
+        for (let from = 0; from < batching.length; from += cap) {
+            const run = batching.slice(from, from + cap);
+            const answers = project.symbolsAt(run.map((site) => project.handle(site.node)));
+            fileBatches += 1;
+            run.forEach((site, index) => {
+                const symbol = answers[index];
+                if (symbol !== undefined) {
+                    answered.set(site.node.pos, symbol);
+                }
+            });
+        }
+        for (const site of sites) {
+            const direct = site.shorthand !== undefined
+                ? "shorthand"
+                : answered.has(site.node.pos)
+                    ? "batch"
+                    : "resolved-symbol";
+            const symbol = symbolFor(site, answered);
+            if (symbol === undefined) {
+                continue;
+            }
+            const position = renderPosition(file, targetRoot, site.node.getStart());
+            for (const target of targetsOf(symbol)) {
+                found.push({
+                    from: site.from,
+                    to: target.id,
+                    position,
+                    use: site.use,
+                    resolution: target.stepped ? "alias" : direct,
+                    test,
+                });
+            }
+        }
+    }
+    found.sort((a, b) => byPosition(a.position, b.position) ||
+        compare(a.to, b.to) ||
+        compare(a.from, b.from) ||
+        compare(a.use, b.use));
+    return {
+        configFile: project.configFile,
+        references: found,
+        testFileRules: options.testFiles
+            .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
+            .sort((a, b) => compare(a.rule, b.rule)),
+        cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps },
+    };
+}