@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.10

package/dist/src/roots.js

@@ -1,24 +1,26 @@
 /**
- * The root set of one project: every declaration the analysis keeps live without a
- * reference, and why.
- *
- * Every root seeds REACHABILITY, and no root counts as a reference. A root of a kind
- * that names a caller is live under reference counting as well, which the sweep
- * decides; the published API only supposes a consumer, so a published export is live
- * under reachability and still a candidate under reference counting.
+ * The root set of one project: every declaration kept live without a reference, and why.
+ * Every root seeds reachability and none counts as a reference; a root of a kind that
+ * names a caller is live under reference counting too, which the sweep decides, so a
+ * published export, which only supposes a consumer, stays a reference-counting candidate.
  */
-import { isExpressionWithTypeArguments, isFunctionLikeDeclaration, isPropertyAccessExpression, isQualifiedName, isTypeQueryNode, isTypeReferenceNode, isPropertyDeclaration, isVariableDeclaration, isVariableStatement, } from "@typescript/native/ast";
+import { isArrowFunction, isAssertionExpression, isExpressionWithTypeArguments, isFunctionLikeDeclaration, isIdentifier, isMethodDeclaration, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAssignment, isReturnStatement, isSatisfiesExpression, isPropertyAccessExpression, isQualifiedName, isTypeQueryNode, isTypeReferenceNode, isPropertyDeclaration, isVariableDeclaration, isVariableStatement, SyntaxKind, } from "@typescript/native/ast";
 import { aliasChains } from "./alias-chain.js";
+import { isGlobalBlock } from "./augmentations.js";
 import { filesNamedBy, outsideChain, relativeSpecifiers, } from "./configuration-files.js";
 import { conventionEntries } from "./conventions.js";
 import { entryPoints } from "./entry-points.js";
-import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
-import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
+import { ancestors, dirnamePath, relativePath, resolvePath } from "./paths.js";
 import { byPosition } from "./position.js";
 import { UNANSWERED } from "./query.js";
 import { sourceFilesOf } from "./source-files.js";
 import { typeQueryAliases } from "./type-query-alias.js";
+import { bytewise } from "./text/compare.js";
+import { holdsManifest } from "./fs/manifest.js";
+import { globExpression } from "./text/glob.js";
+import { spelledFiles } from "./text/named-files.js";
+import { commandDirectories, workflowCommands } from "./workflow-steps.js";
 /** Whether one declaration is written below the directory of a published workspace member. */
 function inPublishedMember(held, id, root, members) {
     const path = held.symbols.find((symbol) => symbol.id === id)?.position.path;
@@ -46,13 +48,8 @@ const OUTPUT_EXTENSION = /\.(?:d\.ts|d\.mts|d\.cts|js|mjs|cjs|jsx)$/u;
 const SOURCE_EXTENSION = /\.(?:d\.)?[cm]?[jt]sx?$/u;
 /** Whether no `package.json` sits between one file and the manifest's directory, which holds it. */
 function ofPackage(host, dir, file) {
-    for (let at = dirnamePath(file); at !== dir; at = dirnamePath(at)) {
-        if (relativePath(dir, at) === undefined ||
-            host.kindOf(joinPath(at, "package.json")) === "file") {
-            return false;
-        }
-    }
-    return true;
+    const between = ancestors(dirnamePath(file), dir);
+    return between.length > 0 && !between.slice(0, -1).some((at) => holdsManifest(host, at));
 }
 /**
  * The rooted files one manifest target reads back to by name: its path below the
@@ -162,13 +159,6 @@ export function matchRef(pattern, ref) {
     }
     return matchGlob(Array.from(pattern), Array.from(ref));
 }
-/** 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;
-}
 /** The members of one declaration, indexed by the container that holds them. */
 function childrenOf(held) {
     const byParent = new Map();
@@ -184,15 +174,47 @@ function childrenOf(held) {
     return byParent;
 }
 /**
- * The roots one project holds, and every configured string that named nothing in it.
- *
- * A file a manifest member, an entry-file pattern or a tool's configuration names
- * is a root with everything its module exports: each name of the module's export
- * table, and where a name is a re-export, every link of the chain to the declaration
- * it carries, so a re-exported declaration is a root of the file that publishes it.
- * In a library, what a published file exports is rooted by the published API alone.
- * A file a runtime executes without reading its exports, a test file or a worker, is
- * a root by itself.
+ * Per package, the own files its command strings name as plain text, but those a root enters
+ * with all they export: a command can use no more of such a file than the root keeps live. A
+ * manifest's are its entries' whole command strings, and the target root's package has the
+ * workflow steps, git hooks and makefile recipes beside its own, with the directories its
+ * workflow steps and lefthook commands run in, where a `.` names that directory's index file.
+ */
+function scriptHolds(entries, files, entered, host, targetRoot) {
+    const rooted = new Set(entered.filter((one) => one.exports && one.names === undefined).map((one) => one.file.fileName));
+    const spelled = [...files.byName.values()]
+        .filter((file) => !rooted.has(file.fileName))
+        .map((file) => ({ file, paths: [file.fileName, ...files.writtenAs(file)] }));
+    const cwd = host.workingDirectory();
+    const commands = new Map([
+        [
+            resolvePath(cwd, targetRoot),
+            [...workflowCommands(host, targetRoot), ...commandDirectories(host, targetRoot)],
+        ],
+    ]);
+    for (const entry of entries) {
+        if (entry.command !== undefined) {
+            const dir = resolvePath(cwd, entry.dir);
+            commands.set(dir, [...(commands.get(dir) ?? []), entry.command]);
+        }
+    }
+    const held = [];
+    for (const [dir, texts] of commands) {
+        const named = spelledFiles(texts.join("\n"), dir, spelled);
+        if (named.length > 0) {
+            const paths = named.map((file) => relativePath(targetRoot, file.fileName) ?? file.fileName);
+            held.push({ dir, files: paths });
+        }
+    }
+    return held;
+}
+/**
+ * The roots one project holds, and every configured string that named nothing in it. A
+ * file a manifest member, an entry-file pattern or a tool's configuration names is a root
+ * with each name of its export table and every link of a re-export chain to the
+ * declaration it carries; in a library, the published API alone roots what a published
+ * file exports. A file a runtime executes without reading its exports, a test file or a
+ * worker, is a root by itself.
  */
 export function roots(project, held, targetRoot, options) {
     const files = sourceFilesOf(project, targetRoot);
@@ -227,7 +249,7 @@ export function roots(project, held, targetRoot, options) {
                 (options.publishedAPI || options.publishedMembers?.has(entry.dir) === true),
         })),
     ];
-    const scripted = entries.flatMap(({ entry }) => entry.role === "script" ? files.named(entry.path) : []);
+    const scripted = entries.flatMap(({ entry }) => entry.role === "script" && entry.command === undefined ? files.named(entry.path) : []);
     const readBackTo = [
         ...scripted,
         ...points.filter((point) => READ_BACK_RULES.has(point.rule)).map((point) => point.file),
@@ -260,6 +282,10 @@ export function roots(project, held, targetRoot, options) {
             published.push(...entryFiles(entry));
         }
     }
+    if (options.publishedAPI) {
+        // A library's bundle hands what its entry exports to every program that loads it.
+        published.push(...points.filter((point) => point.rule === "bundler-entry").map((point) => point.file));
+    }
     const publishedNames = new Set(published.map((file) => file.fileName));
     const patterned = [];
     for (const pattern of options.entryFiles) {
@@ -273,6 +299,9 @@ export function roots(project, held, targetRoot, options) {
     const unmapped = [];
     const mapped = patterned.map(({ file }) => file);
     for (const { entry } of entries) {
+        if (entry.command !== undefined) {
+            continue;
+        }
         const named = entryFiles(entry);
         if (named.length === 0 && entry.role !== "script") {
             unmapped.push(entry);
@@ -295,6 +324,8 @@ export function roots(project, held, targetRoot, options) {
     for (const point of points) {
         enter(point.file, point.rule, point.source, point.exports, point.names);
     }
+    const heldScripts = scriptHolds(entries.map(({ entry }) => entry), files, entered, options.host, targetRoot);
+    const heldFiles = [...new Set(heldScripts.flatMap((one) => one.files))].flatMap((path) => files.byPath.get(path) ?? []);
     for (const file of files.byPath.values()) {
         for (const alias of typeQueryAliases(file)) {
             const source = alias.type.getText().replace(/\s+/gu, " ");
@@ -309,6 +340,7 @@ export function roots(project, held, targetRoot, options) {
     const { tables: exportsOf, named, answered, } = exportTables(project, held, [
         ...entered.filter((entry) => entry.exports).map((entry) => entry.file),
         ...published,
+        ...heldFiles,
     ]);
     for (const entry of entered) {
         const id = fileIds.get(entry.file.fileName);
@@ -339,13 +371,22 @@ export function roots(project, held, targetRoot, options) {
         const left = sites.get(a.id);
         const right = sites.get(b.id);
         const site = left === undefined || right === undefined ? 0 : byPosition(left, right);
-        return site || compare(a.kind, b.kind) || compare(a.source, b.source);
+        return site || bytewise(a.kind, b.kind) || bytewise(a.source, b.source);
     });
     return {
         liveUnderReachability: ordered,
         unmatched,
-        unanswered: answered ? api.guessed : held.symbols.map((symbol) => symbol.id),
+        unanswered: [
+            ...(answered ? api.guessed : held.symbols.map((symbol) => symbol.id)),
+            // A command runs a held file and may read any export of it, so the file, which reaches its
+            // top level, and its exports are held; a declaration neither reaches is still dead.
+            ...heldFiles.flatMap((file) => {
+                const id = fileIds.get(file.fileName);
+                return [...(id === undefined ? [] : [id]), ...(exportsOf.get(file.fileName) ?? [])];
+            }),
+        ],
         unmappedEntries,
+        heldScripts,
     };
 }
 /**
@@ -436,12 +477,12 @@ function releaseTagged(held, files) {
 /** The kinds of container whose export table, not its members' visibility, says what it publishes. */
 const EXPORTING_CONTAINERS = new Set(["file", "namespace"]);
 /**
- * Every declaration a consumer of the library can name: what the published files export,
- * and below each the members a consumer writes, a namespace's exported ones and any other
- * declaration's public and protected ones. A declaration a published one's type names is
- * published too, and so is an exported declaration a release tag marks. A type name the
- * checker leaves unanswered publishes every declaration spelled as it is, as `guessed`. A
- * published file is not itself published.
+ * Every declaration a consumer of the library can name, a published file itself excluded:
+ * what the published files export, with a namespace's exported members and any other
+ * declaration's public and protected ones; a declaration a published one's type names; an
+ * exported declaration a release tag marks; each declaration a `declare global` block holds
+ * in a published file or one holding a published declaration; and, as `guessed`, each
+ * declaration spelled as a type name the checker leaves unanswered.
  */
 function publishedAPI(project, published, exportsOf, held, byPath, tagged) {
     const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
@@ -467,46 +508,80 @@ function publishedAPI(project, published, exportsOf, held, byPath, tagged) {
             reach(id);
         }
     }
-    while (pending.length > 0) {
-        const round = [];
-        for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
-            round.push(next);
-            const exporting = EXPORTING_CONTAINERS.has(byId.get(next)?.kind ?? "");
-            for (const member of children.get(next) ?? []) {
-                const reachable = exporting
-                    ? member.exported
-                    : member.visibility !== "private" && member.visibility !== "private-name";
-                if (member.kind !== "type-parameter" && reachable) {
+    const files = new Set(held.symbols.filter((one) => one.kind === "file").map((one) => one.id));
+    const blocks = held.symbols.filter((one) => isGlobalBlock(one, held, files));
+    const fileOf = (id) => {
+        let at = byId.get(id);
+        while (at !== undefined && at.kind !== "file") {
+            at = byId.get(at.parent);
+        }
+        return at?.id;
+    };
+    const publishedFiles = published.flatMap((file) => held.declarations.get(nodeKey(file, file)) ?? []);
+    const globalsReached = () => {
+        const typed = new Set([...publishedFiles, ...[...reached].flatMap((id) => fileOf(id) ?? [])]);
+        const before = pending.length;
+        for (const block of blocks.filter((one) => typed.has(one.parent))) {
+            reach(block.id);
+            for (const member of children.get(block.id) ?? []) {
+                if (member.kind !== "type-parameter") {
                     reach(member.id);
                 }
             }
         }
-        const named = round.flatMap((id) => {
-            const symbol = byId.get(id);
-            return symbol === undefined || symbol.kind === "file" ? [] : nodes.typeNamesOf(symbol);
-        });
-        for (const symbol of inferredTypeSymbols(project, round.flatMap((id) => {
-            const symbol = byId.get(id);
-            return symbol === undefined ? [] : nodes.nodesOf(symbol);
-        }))) {
-            for (const target of chains.chainOf(symbol)) {
-                reach(target.id);
-            }
-        }
-        project.symbolsAt(named.map((node) => project.handle(node))).forEach((symbol, index) => {
-            if (symbol === UNANSWERED) {
-                for (const id of held.byName.get(named[index]?.getText() ?? "") ?? []) {
-                    guessed.add(id);
-                    reach(id);
+        return pending.length > before;
+    };
+    do {
+        while (pending.length > 0) {
+            const round = [];
+            for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+                round.push(next);
+                const exporting = EXPORTING_CONTAINERS.has(byId.get(next)?.kind ?? "");
+                for (const member of children.get(next) ?? []) {
+                    const reachable = exporting
+                        ? member.exported
+                        : member.visibility !== "private" && member.visibility !== "private-name";
+                    if (member.kind !== "type-parameter" && reachable) {
+                        reach(member.id);
+                    }
                 }
             }
-            else if (symbol !== undefined) {
+            const named = round.flatMap((id) => {
+                const symbol = byId.get(id);
+                return symbol === undefined || symbol.kind === "file" ? [] : nodes.typeNamesOf(symbol);
+            });
+            const inferred = inferredTypeSymbols(project, round.flatMap((id) => {
+                const symbol = byId.get(id);
+                return symbol === undefined ? [] : nodes.nodesOf(symbol);
+            }));
+            for (const symbol of inferred.types) {
                 for (const target of chains.chainOf(symbol)) {
                     reach(target.id);
                 }
             }
-        });
-    }
+            for (const symbol of inferred.members) {
+                for (const target of chains.chainOf(symbol)) {
+                    const member = byId.get(target.id);
+                    if (member?.visibility === "public" || member?.visibility === "protected") {
+                        reach(target.id);
+                    }
+                }
+            }
+            project.symbolsAt(named.map((node) => project.handle(node))).forEach((symbol, index) => {
+                if (symbol === UNANSWERED) {
+                    for (const id of held.byName.get(named[index]?.getText() ?? "") ?? []) {
+                        guessed.add(id);
+                        reach(id);
+                    }
+                }
+                else if (symbol !== undefined) {
+                    for (const target of chains.chainOf(symbol)) {
+                        reach(target.id);
+                    }
+                }
+            });
+        }
+    } while (globalsReached());
     return { ids: [...reached], guessed: [...guessed] };
 }
 /** The type names declarations of the inventory write, each file walked once, when first asked. */
@@ -544,11 +619,101 @@ function declarationNodes(held, byPath) {
 /** How deep the type arguments and constituents of an inferred type are followed. */
 const INFERRED_DEPTH = 4;
 /**
- * The declarations of the types the compiler infers where a declaration writes none: the
- * type of a variable or a property with no annotation, and the result of a function or a
- * method with no result annotation, each with the types its type arguments and its union
- * or intersection constituents name, to a fixed depth. A question the checker leaves
- * unanswered names nothing.
+ * The values one function body returns, each through the type assertions around it: the
+ * value a caller receives carries the operand's type whatever type the assertion or the
+ * signature names. A nested function's returns are its own.
+ */
+function returnedValues(body) {
+    const found = [];
+    const add = (value) => {
+        for (let at = value; at !== undefined;) {
+            found.push(at);
+            at =
+                isAssertionExpression(at) || isSatisfiesExpression(at) || isParenthesizedExpression(at)
+                    ? at.expression
+                    : undefined;
+        }
+    };
+    if (!isFunctionLikeDeclaration(body.parent) || body.parent.body !== body) {
+        return found;
+    }
+    if (isArrowFunction(body.parent) && body.kind !== SyntaxKind.Block) {
+        add(body);
+        return found;
+    }
+    const visit = (node) => {
+        if (isFunctionLikeDeclaration(node)) {
+            return;
+        }
+        if (isReturnStatement(node) && node.expression !== undefined) {
+            add(node.expression);
+        }
+        node.forEachChild(visit);
+    };
+    body.forEachChild(visit);
+    return found;
+}
+/** The object literal one returned value is, written there or as the initializer of a variable `body` declares. */
+function returnedLiteral(value, body) {
+    if (isObjectLiteralExpression(value)) {
+        return value;
+    }
+    if (!isIdentifier(value)) {
+        return undefined;
+    }
+    let found;
+    const visit = (node) => {
+        if (isVariableDeclaration(node) &&
+            isIdentifier(node.name) &&
+            node.name.text === value.text &&
+            node.initializer !== undefined) {
+            let at = node.initializer;
+            while (isAssertionExpression(at) ||
+                isSatisfiesExpression(at) ||
+                isParenthesizedExpression(at)) {
+                at = at.expression;
+            }
+            found = isObjectLiteralExpression(at) ? at : found;
+        }
+        if (!isFunctionLikeDeclaration(node)) {
+            node.forEachChild(visit);
+        }
+    };
+    body.forEachChild(visit);
+    return found;
+}
+/**
+ * The values one function body returns, and those each method of an object literal it
+ * returns returns, to a fixed depth: a caller holding the literal calls its methods, and
+ * receives what they return.
+ */
+function returnedThroughLiterals(body, depth = 0) {
+    const values = returnedValues(body);
+    if (depth >= INFERRED_DEPTH) {
+        return values;
+    }
+    const found = [...values];
+    for (const value of values) {
+        for (const property of returnedLiteral(value, body)?.properties ?? []) {
+            const fn = isMethodDeclaration(property)
+                ? property
+                : isPropertyAssignment(property) && isFunctionLikeDeclaration(property.initializer)
+                    ? property.initializer
+                    : undefined;
+            if (fn?.body !== undefined) {
+                found.push(...returnedThroughLiterals(fn.body, depth + 1));
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The declarations of the types the compiler infers where a declaration writes none, and
+ * of the values a function returns: the type of a variable or a property with no
+ * annotation, the result of a function or a method with no result annotation, and the type
+ * of each value its body returns, each with the types its type arguments and its union or
+ * intersection constituents name, to a fixed depth; and as `members` the properties of each
+ * returned value's type. A question the checker leaves unanswered names nothing.
  */
 function inferredTypeSymbols(project, declarations) {
     const { queries } = project;
@@ -557,12 +722,24 @@ function inferredTypeSymbols(project, declarations) {
         !isFunctionLikeDeclaration(node.initializer ?? node)
         ? [node.name]
         : []);
+    const returned = declarations.flatMap((node) => {
+        const signature = isFunctionLikeDeclaration(node)
+            ? node
+            : isVariableDeclaration(node) &&
+                node.initializer !== undefined &&
+                isFunctionLikeDeclaration(node.initializer)
+                ? node.initializer
+                : undefined;
+        return signature?.body === undefined ? [] : returnedThroughLiterals(signature.body);
+    });
     const types = [];
-    queries.typesAt(valued).forEach((type) => {
+    const returnedTypes = [];
+    queries.typesAt([...valued, ...returned]).forEach((type, at) => {
         if (type !== UNANSWERED && type !== undefined) {
-            types.push(type);
+            (at < valued.length ? types : returnedTypes).push(type);
         }
     });
+    types.push(...returnedTypes);
     for (const node of declarations) {
         const signature = isFunctionLikeDeclaration(node)
             ? node
@@ -604,7 +781,19 @@ function inferredTypeSymbols(project, declarations) {
     types.forEach((type) => {
         visit(type, 0);
     });
-    return [...found.values()];
+    // A returned value carries each property of its type, one an anonymous type declares or
+    // an intersection merges included, which no type name reaches.
+    const members = new Map();
+    for (const type of returnedTypes) {
+        const parts = queries.constituents(type);
+        for (const one of [type, ...(parts === UNANSWERED ? [] : parts)]) {
+            const properties = queries.propertiesOf(one);
+            for (const property of properties === UNANSWERED ? [] : properties) {
+                members.set(property.id, property);
+            }
+        }
+    }
+    return { types: [...found.values()], members: [...members.values()] };
 }
 /**
  * The names of types one declaration's own syntax writes: in a type reference, a
@@ -659,13 +848,10 @@ function configured(held, patterns, add) {
     return unmatched;
 }
 /**
- * Every configured string that named no declaration in ANY project of the run, in
- * configuration order and each once.
- *
- * A finding about a configured root is about the configuration and not about a
- * declaration, so there is one per run: a string that names a declaration of one
- * project has named something, and the projects it named nothing in are not a
- * finding. A run with no project names nothing with any of them.
+ * Every configured string that named no declaration in any project of the run, in
+ * configuration order and each once. The finding is about the configuration, so a string
+ * naming a declaration of one project has named something, and a run with no project
+ * names nothing with any of them.
  */
 export function unmatchedEverywhere(patterns, perProject) {
     return [...new Set(patterns)].filter((pattern) => perProject.every((project) => project.unmatched.includes(pattern)));