@cplieger/deadset-ts 8.0.0-dev.16 → 8.0.0-dev.18

package/dist/src/references/sources.js

@@ -0,0 +1,450 @@
+/**
+ * The reference sources of the reference pass: each turns one form of site the walk found in a
+ * file into uses, through the file's one batch, into the pass's one sink. A source names the
+ * nodes it needs the batch to answer, and the pass asks them all in capped runs.
+ */
+import { isExportDeclaration, isIdentifier, isImportDeclaration, isStringLiteralLikeNode, } from "@typescript/native/ast";
+import { amdPath, amdPlatform } from "../amd.js";
+import { specifierCandidates } from "../entries/configuration-files.js";
+import { bindingsOf, importedNames } from "../import-bindings.js";
+import { isLiteralText, WORKER_CONSTRUCTORS, } from "../index/sites.js";
+import { nodeKey } from "../inventory.js";
+import { JAVASCRIPT_FILE } from "../javascript-file.js";
+import { dirnamePath, isRelativeSpecifier, queriedModulePath, relativeURLPath, resolvePath, startsRelativePath, } from "../paths.js";
+import { callsPlatform, isPlatformGlobal, startsThread } from "../platform-symbols.js";
+import { isComponentFile } from "../position.js";
+import { UNANSWERED } from "../query.js";
+import { computedLoadsOf } from "../roots/unseen-loads.js";
+import { computedKeyNames, keyedUses } from "../symbol-keys.js";
+import { storedValue } from "./sink.js";
+/** The file of the target a relative specifier written in `file` names, by its source or output name. */
+function fileNamed(file, specifier, fileIdByName) {
+    return specifierCandidates(dirnamePath(file.fileName), specifier)
+        .map((path) => fileIdByName.get(path))
+        .find((id) => id !== undefined);
+}
+/**
+ * The own file a module specifier with a query evaluates ({@link queriedModulePath}): the
+ * checker resolves the whole specifier to whatever module declaration matches it.
+ */
+function queriedFile(file, specifier, fileIdByName) {
+    if (!isLiteralText(specifier)) {
+        return undefined;
+    }
+    const path = queriedModulePath(specifier.text);
+    return path === undefined
+        ? undefined
+        : fileIdByName.get(resolvePath(dirnamePath(file.fileName), path));
+}
+/**
+ * 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.
+ */
+const decorators = {
+    emit({ file, decorated }, _answered, { sink }) {
+        for (const { decorator, declaration } of decorated) {
+            sink.add(file, decorator, declaration, [declaration], "decorator", "syntax");
+        }
+    },
+};
+/** The constructor stores its argument in the member a parameter property declares. */
+const parameterWrites = {
+    emit({ file, parameterWrites: writes }, _answered, { sink }) {
+        for (const { name, from, member } of writes) {
+            sink.add(file, name, from, [member], "write", "syntax");
+        }
+    },
+};
+/**
+ * A re-export references the first declaration its alias chain carries forward that the
+ * inventory declares, one link per re-export, or for a bare star the module it names.
+ */
+const links = {
+    batched: ({ links: found }) => found.map((link) => link.node),
+    emit({ file, links: found }, answered, { sink, chains, named }) {
+        for (const link of found) {
+            const symbol = answered.get(link.node);
+            if (symbol === undefined) {
+                continue;
+            }
+            const carried = symbol === UNANSWERED ? named(link.at) : carriedBy(chains, link, symbol);
+            sink.add(file, link.at, link.from, carried, "read", link.alias ? "alias" : "batch");
+        }
+    },
+};
+/**
+ * The declarations one re-export carries forward: for an alias, the first link along its chain
+ * that the inventory declares, stepping over the links it does not, such as an import the
+ * re-export is written against; for a bare star, the module it names.
+ */
+function carriedBy(chains, link, symbol) {
+    return link.alias
+        ? chains.nextDeclared(symbol).map((target) => ({ ...target, stepped: false }))
+        : chains.declarationsOf(symbol).map((id) => ({ id, stepped: false, guessed: false }));
+}
+/**
+ * Whether one evaluation loads its module: an import form, or a `require`, or an AMD `define`
+ * or `require`, that {@link callsPlatform} names.
+ */
+function loading(evaluation, answered, project) {
+    const { require } = evaluation;
+    return (require === undefined ||
+        callsPlatform(project, evaluation.amd === true ? amdPlatform(require) : "require", require, answered.get(require)));
+}
+/**
+ * Every import of one of the target's modules evaluates that module's file. A required
+ * file the checker names no module for is read whole where the call's value is used: the
+ * value is the file's exports object, which this pass does not follow.
+ */
+const evaluations = {
+    batched: ({ evaluations: found }) => found.flatMap((evaluation) => evaluation.require === undefined
+        ? [evaluation.node]
+        : [
+            evaluation.require,
+            ...(evaluation.require.text === "require" && evaluation.amd !== true
+                ? [evaluation.node]
+                : []),
+        ]),
+    emit({ file, evaluations: found }, answered, pass) {
+        const { project, sink, fileIds, fileIdByName, chains, loadableById, cap, exportsRead } = pass;
+        const loaded = found.filter((one) => loading(one, answered, project));
+        // A script declares no module, so the checker names nothing for a specifier of one;
+        // the compiler's module resolution still names its file.
+        const unnamed = loaded.flatMap(({ node, amd }) => amd !== true &&
+            answered.get(node) === undefined &&
+            isStringLiteralLikeNode(node) &&
+            queriedFile(file, node, fileIdByName) === undefined
+            ? [node]
+            : []);
+        const resolved = project.resolvedFileNames(unnamed);
+        const scripts = new Map(unnamed.map((node, at) => {
+            const name = resolved[at];
+            return [node, name === undefined ? undefined : fileIdByName.get(name)];
+        }));
+        const wholeReads = [];
+        for (const evaluation of loaded) {
+            const queried = queriedFile(file, evaluation.node, fileIdByName);
+            if (queried !== undefined) {
+                sink.add(file, evaluation.node, evaluation.from, [queried], "evaluation", "syntax");
+            }
+            const module = answered.get(evaluation.node);
+            const amd = evaluation.amd === true && isLiteralText(evaluation.node);
+            const amdFile = amd
+                ? fileIdByName.get(amdPath(dirnamePath(file.fileName), evaluation.node.text) ?? "")
+                : undefined;
+            // Node's require resolves a relative specifier the program records no resolution for,
+            // as in a TypeScript file, by its own extension search.
+            const script = amdFile ??
+                scripts.get(evaluation.node) ??
+                (!amd &&
+                    evaluation.require !== undefined &&
+                    module === undefined &&
+                    isLiteralText(evaluation.node) &&
+                    startsRelativePath(evaluation.node.text)
+                    ? fileNamed(file, evaluation.node.text, fileIdByName)
+                    : undefined);
+            if (script === undefined && module === undefined) {
+                possibleLoad(file, evaluation, pass);
+            }
+            if (script !== undefined) {
+                const whole = loadableById.get(script);
+                if (evaluation.whole === true && module === undefined && whole !== undefined) {
+                    wholeReads.push({ evaluation, loaded: whole });
+                }
+                sink.add(file, evaluation.node, evaluation.from, [script], "evaluation", "syntax");
+            }
+            if (module === undefined) {
+                continue;
+            }
+            // A module the checker could not resolve may be any file of the target.
+            const evaluated = module === UNANSWERED
+                ? [...fileIds].map((id) => ({ id, guessed: true }))
+                : chains
+                    .declarationsOf(module)
+                    .flatMap((id) => (fileIds.has(id) ? [id] : []))
+                    .map((id) => ({ id }));
+            sink.add(file, evaluation.node, evaluation.from, evaluated, "evaluation", "batch");
+        }
+        const modules = project.symbolsAt(wholeReads.map((one) => project.handle(one.loaded)), cap);
+        wholeReads.forEach(({ evaluation }, at) => {
+            const module = modules[at];
+            const targets = module === undefined ? [] : exportsRead(module);
+            sink.add(file, evaluation.node, evaluation.from, targets, "read", "batch");
+        });
+    },
+};
+/**
+ * An import of a JavaScript file that a program formed for Node leaves unresolved, asked again
+ * as a bundler resolves it (program.38): the file it names, and each export there the import
+ * binds, a namespace import binding every one, are only possibly loaded.
+ */
+function possibleLoad(file, evaluation, pass) {
+    const { node } = evaluation;
+    const declaration = node.parent;
+    if (!pass.formedForNode ||
+        evaluation.require !== undefined ||
+        !JAVASCRIPT_FILE.test(file.fileName) ||
+        !isLiteralText(node) ||
+        !isRelativeSpecifier(node.text) ||
+        !(isImportDeclaration(declaration) || isExportDeclaration(declaration))) {
+        return;
+    }
+    const loaded = fileNamed(file, node.text, pass.fileIdByName);
+    if (loaded === undefined) {
+        return;
+    }
+    pass.possiblyLoaded.add(loaded);
+    const exported = pass.declaredIn(loaded).filter((one) => one.exported);
+    for (const name of importedNames(declaration)) {
+        for (const one of exported) {
+            if (name === undefined || one.name === name) {
+                pass.possiblyLoaded.add(one.id);
+            }
+        }
+    }
+}
+/** A module URL the platform's `URL` builds names the file a runtime starts as a module. */
+const urls = {
+    batched: ({ urls: found }) => found.flatMap((url) => url.constructor ?? []),
+    emit({ file, urls: found }, answered, { project, sink, fileIdByName }) {
+        for (const url of found) {
+            if (url.constructor !== undefined &&
+                !callsPlatform(project, "URL", url.constructor, answered.get(url.constructor))) {
+                continue;
+            }
+            const path = relativeURLPath(dirnamePath(file.fileName), url.specifier);
+            const loaded = path === undefined ? undefined : fileNamed(file, path, fileIdByName);
+            if (loaded !== undefined) {
+                sink.add(file, url.at, url.from, [loaded], "evaluation", "syntax");
+            }
+        }
+    },
+};
+/**
+ * A worker address names the file a runtime starts (references-ts.2): Node's `Worker` reads
+ * a relative path against the working directory and a path of the module's own directory
+ * against that directory, a browser's an address against the module's URL.
+ */
+const workers = {
+    batched: ({ workers: found }) => found.flatMap((worker) => worker.holder === undefined ? [worker.constructor] : [worker.constructor, worker.holder]),
+    emit({ file, workers: found }, answered, pass) {
+        const { project, sink, fileIds, directories, held } = pass;
+        for (const worker of found) {
+            const symbol = answered.get(worker.constructor);
+            const text = worker.address;
+            let path;
+            if (startsThread(project, symbol, worker.holder && answered.get(worker.holder))) {
+                path = worker.evaluated
+                    ? undefined
+                    : worker.ownDirectory
+                        ? resolvePath(dirnamePath(file.fileName), text)
+                        : startsRelativePath(text)
+                            ? resolvePath(directories.workingDirectoryOf(file.fileName), text)
+                            : undefined;
+            }
+            else if (!worker.ownDirectory &&
+                (WORKER_CONSTRUCTORS.has(worker.constructor.text) ||
+                    worker.constructor.text === "navigator") &&
+                isPlatformGlobal(project, symbol)) {
+                path = relativeURLPath(dirnamePath(file.fileName), text);
+            }
+            const started = (path === undefined ? [] : pass.ownFiles().named(path)).flatMap((one) => {
+                const id = held.declarations.get(nodeKey(one, one));
+                return id !== undefined && fileIds.has(id) ? [id] : [];
+            });
+            sink.add(file, worker.at, worker.from, started, "evaluation", "syntax");
+        }
+    },
+};
+/**
+ * A computed load imports each file it loads where the call is written, reading what the file
+ * exports unless it reads the file as text or a URL; callsPlatform owns which call is a `require`.
+ */
+const loads = {
+    batched: ({ loads: found }) => found.flatMap((load) => [
+        ...(load.require === undefined ? [] : [load.require]),
+        ...(load.asset ? [] : load.files.map((loaded) => loaded.file)),
+    ]),
+    emit({ file, fileId, loads: found }, answered, pass) {
+        const { project, sink, consumer, exportsRead, unseenLoads } = pass;
+        for (const load of found) {
+            if (load.require !== undefined &&
+                !callsPlatform(project, load.amd ? amdPlatform(load.require) : "require", load.require, answered.get(load.require))) {
+                continue;
+            }
+            const position = sink.position(file, load.call);
+            if (!load.resolved && !consumer && !file.isDeclarationFile && !sink.isTest(file)) {
+                unseenLoads.push(position);
+            }
+            for (const loaded of load.files) {
+                sink.add(file, position, load.eager ? fileId : load.from, [loaded.fileId], "evaluation", "syntax");
+                const module = load.asset ? undefined : answered.get(loaded.file);
+                sink.add(file, position, load.from, module === undefined ? [] : exportsRead(module), "read", "batch");
+            }
+        }
+    },
+};
+/** A use of a module namespace object that may read every export of the module reads them all. */
+const wholes = {
+    batched: ({ wholes: found }) => found.map((whole) => whole.specifier),
+    emit({ file, wholes: found }, answered, { sink, exportsRead }) {
+        for (const whole of found) {
+            const module = answered.get(whole.specifier);
+            if (module !== undefined) {
+                sink.add(file, whole.at, whole.from, exportsRead(module), "read", "batch");
+            }
+        }
+    },
+};
+/**
+ * A component file's markup may use any binding its blocks declare at the top level, and any
+ * export of a module a binding's chain reaches, whether a namespace import binds it or a named
+ * or default import of a namespace re-export.
+ */
+const markup = {
+    batched: ({ bindings }) => bindings,
+    emit({ file, fileId, markup: written, bindings }, answered, pass) {
+        if (!written) {
+            return;
+        }
+        const { sink, chains, named, declaredIn } = pass;
+        for (const symbol of declaredIn(fileId)) {
+            sink.add(file, symbol.position, fileId, [symbol.id], "read", "syntax");
+        }
+        for (const binding of bindings) {
+            const symbol = answered.get(binding);
+            if (symbol === undefined) {
+                continue;
+            }
+            const chained = symbol === UNANSWERED ? named(binding) : chains.chainOf(symbol);
+            const targets = chained.flatMap((target) => [
+                target,
+                ...declaredIn(target.id)
+                    .filter((one) => one.exported)
+                    .map((one) => ({ ...target, id: one.id })),
+            ]);
+            sink.add(file, binding, fileId, targets, "read", "batch");
+        }
+    },
+};
+/**
+ * A pattern names a property of the value it destructures, which no name node of the pattern
+ * resolves to: a shorthand's name is the local it binds.
+ */
+const patterns = {
+    emit({ file, reads }, _answered, { sink, held, destructured, targetsOf }) {
+        destructured.resolve(reads).forEach((symbol, index) => {
+            const read = reads[index];
+            if (symbol === undefined || read === undefined) {
+                return;
+            }
+            const targets = symbol === UNANSWERED
+                ? (held.byName.get(read.name) ?? []).map((id) => ({ id, guessed: true }))
+                : targetsOf(symbol).map((target) => ({ ...target, stepped: false }));
+            sink.add(file, read.key, read.from, targets, "read", "destructured");
+        });
+    },
+};
+/** A key a unique symbol types selects the member declared under that symbol. */
+const keyed = {
+    emit({ file, keyed: found }, answered, { project, sink, chains, tables, cap, held }) {
+        const keyNames = computedKeyNames(held.symbols);
+        const resolvedKeys = found.flatMap((access) => {
+            const symbol = isIdentifier(access.key) && keyNames.has(access.key.text)
+                ? answered.get(access.key)
+                : undefined;
+            return typeof symbol === "object" ? [{ access, symbol }] : [];
+        });
+        for (const { access, ids } of keyedUses(project, chains, resolvedKeys, tables, cap)) {
+            for (const use of access.use === "both" ? ["read", "write"] : [access.use]) {
+                sink.add(file, access.access.argumentExpression, access.from, ids, use, "keyed");
+            }
+        }
+    },
+};
+/**
+ * A name a use writes resolves to what it names; a re-export something imports is used and so
+ * is the declaration behind it, so the use names every link of the chain its name stands at the
+ * head of. A shorthand is left out of the batch: its name resolves to the property the literal
+ * declares, which this project's inventory never holds, so its value is asked on its own.
+ */
+const names = {
+    batched: ({ uses }) => uses.filter((site) => site.shorthand === undefined).map((site) => site.node),
+    emit({ file, uses }, answered, pass) {
+        const { project, sink, named, targetsOf, throughAliases } = pass;
+        for (const site of uses) {
+            const symbol = symbolFor(project, site, answered);
+            if (symbol === undefined) {
+                continue;
+            }
+            const direct = site.shorthand !== undefined
+                ? "shorthand"
+                : typeof answered.get(site.node) === "object"
+                    ? "batch"
+                    : "resolved-symbol";
+            const targets = throughAliases(symbol === UNANSWERED ? named(site.node) : targetsOf(symbol));
+            const value = site.use === "write" ? storedValue(site.node) : undefined;
+            sink.add(file, site.node, site.from, targets, site.use, direct, value);
+        }
+    },
+};
+/** The symbol one site resolves to, asking only the accessor the site's form names. */
+function symbolFor(project, site, answered) {
+    if (site.shorthand !== undefined) {
+        return project.shorthandValueAt(project.handle(site.shorthand));
+    }
+    const batched = answered.get(site.node);
+    if (batched === UNANSWERED || typeof batched === "object") {
+        return batched;
+    }
+    return project.resolvedSymbolAt(project.handle(site.node));
+}
+/** Every per-file source, in the order the pass asks their nodes. */
+const REFERENCE_SOURCES = [
+    names,
+    links,
+    evaluations,
+    wholes,
+    urls,
+    workers,
+    markup,
+    loads,
+    decorators,
+    parameterWrites,
+    patterns,
+    keyed,
+];
+/** What the pass reads of one walked file before its batch: its computed loads and its markup bindings. */
+export function prepared(sites, pass, loadable) {
+    const markupFile = isComponentFile(sites.file);
+    return {
+        ...sites,
+        loads: computedLoadsOf(sites.file, sites.loadCalls, loadable, (fileName) => pass.directories.bundlerRootOf(fileName)),
+        markup: markupFile,
+        bindings: markupFile ? bindingsOf(sites.file).map((binding) => binding.name) : [],
+    };
+}
+/**
+ * Runs every source over one walked file: one batch per capped run of the nodes the sources
+ * name, each node once, then each source's uses.
+ */
+export function emitFile(walked, pass) {
+    const { project, cap } = pass;
+    const batching = [
+        ...new Set(REFERENCE_SOURCES.flatMap((source) => [...(source.batched?.(walked, pass) ?? [])])),
+    ];
+    const answered = new Map();
+    for (let from = 0; from < batching.length; from += cap) {
+        const run = batching.slice(from, from + cap);
+        const answers = project.symbolsAt(run.map((node) => project.handle(node)), cap);
+        run.forEach((node, index) => {
+            const symbol = answers[index];
+            if (symbol !== undefined) {
+                answered.set(node, symbol);
+            }
+        });
+    }
+    for (const source of REFERENCE_SOURCES) {
+        source.emit(walked, answered, pass);
+    }
+}