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

package/dist/src/roots/published-reach.js

@@ -0,0 +1,412 @@
+/**
+ * The published reach of a library: what a consumer outside the target can name, from the
+ * files a published manifest entry or a bundle hands it and the declarations a release tag
+ * marks, through the types each published declaration names.
+ */
+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 { nodeKey } from "../inventory.js";
+import { UNANSWERED } from "../query.js";
+/** A release tag of a documentation comment: `@` and its name, between white space or the ends. */
+const RELEASE_TAG = /(?:^|\s)@(?:public|beta|alpha)(?=\s|$)/u;
+/**
+ * Whether the documentation comment of the statement that starts at `start`, the last
+ * `/** *\/` comment before it with only white space between the two, holds a release tag.
+ */
+function releaseTagIn(text, from, start) {
+    const leading = text.slice(from, start);
+    const open = leading.lastIndexOf("/**");
+    const close = open < 0 ? -1 : leading.indexOf("*/", open + 3);
+    if (close < 0 || leading.slice(close + 2).trim() !== "") {
+        return false;
+    }
+    return RELEASE_TAG.test(leading.slice(open + 3, close));
+}
+/** The exported top-level declarations of the program's files a release tag marks. */
+export function releaseTagged(held, files) {
+    const exported = new Set(held.symbols.filter((symbol) => symbol.exported).map((one) => one.id));
+    const found = [];
+    for (const file of files.byPath.values()) {
+        for (const statement of file.statements) {
+            if (!releaseTagIn(file.text, statement.pos, statement.getStart())) {
+                continue;
+            }
+            const nodes = isVariableStatement(statement)
+                ? statement.declarationList.declarations
+                : [statement];
+            for (const node of nodes) {
+                const id = held.declarations.get(nodeKey(file, node));
+                if (id !== undefined && exported.has(id)) {
+                    found.push(id);
+                }
+            }
+        }
+    }
+    return found;
+}
+/** 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, 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.
+ */
+export function publishedAPI(project, published, exportsOf, held, byPath, tagged) {
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    const children = childrenOf(held);
+    const nodes = declarationNodes(held, byPath);
+    const chains = aliasChains(project, held);
+    const reached = new Set();
+    const entered = new Set();
+    const guessed = new Set();
+    const pending = [];
+    const reach = (id) => {
+        const file = byId.get(id)?.kind === "file";
+        if (!(file ? entered : reached).has(id)) {
+            (file ? entered : reached).add(id);
+            pending.push(id);
+        }
+    };
+    for (const id of tagged) {
+        reach(id);
+    }
+    for (const file of published) {
+        for (const id of exportsOf.get(file.fileName) ?? []) {
+            reach(id);
+        }
+    }
+    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);
+                }
+            }
+        }
+        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);
+                    }
+                }
+            }
+            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. */
+function declarationNodes(held, byPath) {
+    const walked = new Map();
+    const nodesIn = (path) => {
+        const known = walked.get(path);
+        if (known !== undefined) {
+            return known;
+        }
+        const found = { byId: new Map(), nodes: new Set() };
+        const file = byPath.get(path);
+        if (file !== undefined) {
+            const visit = (node) => {
+                const id = held.declarations.get(nodeKey(file, node));
+                if (id !== undefined) {
+                    found.nodes.add(node);
+                    found.byId.set(id, [...(found.byId.get(id) ?? []), node]);
+                }
+                node.forEachChild(visit);
+            };
+            visit(file);
+        }
+        walked.set(path, found);
+        return found;
+    };
+    return {
+        typeNamesOf: (symbol) => {
+            const { byId, nodes } = nodesIn(symbol.position.path);
+            return (byId.get(symbol.id) ?? []).flatMap((declaration) => typeNamesOf(declaration, (nested) => nodes.has(nested)));
+        },
+        nodesOf: (symbol) => nodesIn(symbol.position.path).byId.get(symbol.id) ?? [],
+    };
+}
+/** How deep the type arguments and constituents of an inferred type are followed. */
+const INFERRED_DEPTH = 4;
+/**
+ * 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;
+    const valued = declarations.flatMap((node) => (isVariableDeclaration(node) || isPropertyDeclaration(node)) &&
+        node.type === undefined &&
+        !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 = [];
+    const returnedTypes = [];
+    queries.typesAt([...valued, ...returned]).forEach((type, at) => {
+        if (type !== UNANSWERED && type !== undefined) {
+            (at < valued.length ? types : returnedTypes).push(type);
+        }
+    });
+    types.push(...returnedTypes);
+    for (const node of declarations) {
+        const signature = isFunctionLikeDeclaration(node)
+            ? node
+            : isVariableDeclaration(node) &&
+                node.type === undefined &&
+                node.initializer !== undefined &&
+                isFunctionLikeDeclaration(node.initializer)
+                ? node.initializer
+                : undefined;
+        if (signature === undefined || signature.type !== undefined || signature.body === undefined) {
+            continue;
+        }
+        const typed = queries.signatureOf(signature);
+        const result = typed === UNANSWERED || typed === undefined ? undefined : queries.returnTypeOf(typed);
+        if (result !== UNANSWERED && result !== undefined) {
+            types.push(result);
+        }
+    }
+    const found = new Map();
+    const seen = new Set();
+    const visit = (type, depth) => {
+        if (depth > INFERRED_DEPTH || seen.has(type)) {
+            return;
+        }
+        seen.add(type);
+        const symbol = queries.symbolOfType(type);
+        if (symbol !== UNANSWERED && symbol !== undefined) {
+            found.set(symbol.id, symbol);
+        }
+        const parts = queries.constituents(type);
+        const args = queries.typeArguments(type);
+        for (const next of [
+            ...(parts === UNANSWERED || (parts.length === 1 && parts[0] === type) ? [] : parts),
+            ...(args === UNANSWERED ? [] : args),
+        ]) {
+            visit(next, depth + 1);
+        }
+    };
+    types.forEach((type) => {
+        visit(type, 0);
+    });
+    // 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
+ * heritage clause or a type query. A function body is not read, and neither is a
+ * declaration nested in this one that `readAlone` says is read on its own.
+ */
+export function typeNamesOf(declaration, readAlone) {
+    const found = [];
+    const visit = (node) => {
+        if (node !== declaration && readAlone(node)) {
+            return;
+        }
+        if (isTypeReferenceNode(node)) {
+            found.push(isQualifiedName(node.typeName) ? node.typeName.right : node.typeName);
+        }
+        else if (isExpressionWithTypeArguments(node)) {
+            found.push(isPropertyAccessExpression(node.expression) ? node.expression.name : node.expression);
+        }
+        else if (isTypeQueryNode(node)) {
+            found.push(isQualifiedName(node.exprName) ? node.exprName.right : node.exprName);
+        }
+        const body = isFunctionLikeDeclaration(node) ? node.body : undefined;
+        node.forEachChild((child) => {
+            if (child !== body) {
+                visit(child);
+            }
+        });
+    };
+    visit(declaration);
+    return found;
+}
+/** The members of one declaration, indexed by the container that holds them. */
+function childrenOf(held) {
+    const byParent = new Map();
+    for (const symbol of held.symbols) {
+        const siblings = byParent.get(symbol.parent);
+        if (siblings === undefined) {
+            byParent.set(symbol.parent, [symbol]);
+        }
+        else {
+            siblings.push(symbol);
+        }
+    }
+    return byParent;
+}