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

package/dist/src/exposure.js

@@ -0,0 +1,400 @@
+/**
+ * Which types of the target each of its declarations hands to code outside the package:
+ * the types each declaration a reference from outside reaches names, as written or as the
+ * checker reads it, as the precondition of `DS1501` in the Contract's kinds reads that
+ * reach.
+ */
+import { SignatureKind, SymbolFlags, } from "@typescript/native/sync";
+import { isArrowFunction, isAsExpression, isBindingElement, isCallSignatureDeclaration, isClassExpression, isConstructorTypeNode, isConstructSignatureDeclaration, isDecorator, isEnumMember, isFunctionExpression, isFunctionTypeNode, isGetAccessorDeclaration, isIdentifier, isMethodDeclaration, isMethodSignatureDeclaration, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAssignment, isPropertyDeclaration, isPropertySignatureDeclaration, isSatisfiesExpression, isSetAccessorDeclaration, isSpreadAssignment, isTypeAssertion, isTypeReferenceNode, } from "@typescript/native/ast";
+import { aliasChains } from "./alias-chain.js";
+import { OUTSIDE } from "./liveness/graph.js";
+import { nodeKey } from "./inventory.js";
+import { isAnswered } from "./query.js";
+import { typeNamesOf } from "./roots/published-reach.js";
+/** The declarations whose values a reference holds without naming them. */
+const TYPES = new Set(["class", "interface", "type", "enum"]);
+/** The symbol flags of a type the source spells as a literal, whose members are its own. */
+const LITERAL = SymbolFlags.TypeLiteral | SymbolFlags.ObjectLiteral;
+/** The members a type's definition names other types through, where exported. */
+const MEMBERS = new Set([
+    "method",
+    "class-member",
+    "interface-method",
+    "type-member",
+]);
+/** The declarations of a module or a namespace whose signature or type hands values on. */
+const CARRYING = new Set(["function", "variable", ...TYPES]);
+/** The containers whose own declarations a reference from outside can reach. */
+const SCOPES = new Set(["file", "namespace"]);
+/** What a project whose carriers no rule reads carries: nothing. */
+export const NO_CARRIERS = { named: new Map(), unread: new Set() };
+/** Whether a member is named from outside its type: neither `private` nor a private name. */
+function exportedMember(symbol) {
+    return symbol.visibility === "public" || symbol.visibility === "protected";
+}
+/**
+ * The declarations of one project that carry values out: a function, a variable or a type
+ * a module or a namespace declares, and an exported member of a class, an interface or a
+ * type. Neither is filtered by its export: only a declaration the reach meets passes it
+ * on, and an unexported type an exported function returns passes it to what it names.
+ */
+function carrying(held) {
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    return held.symbols.filter((symbol) => {
+        const parent = byId.get(symbol.parent);
+        if (MEMBERS.has(symbol.kind)) {
+            return parent !== undefined && TYPES.has(parent.kind) && exportedMember(symbol);
+        }
+        return CARRYING.has(symbol.kind) && parent !== undefined && SCOPES.has(parent.kind);
+    });
+}
+/** The node a declaration's symbol is resolved at: its name, or itself where it has none. */
+function nameNode(node) {
+    return node.name ?? node;
+}
+/** Whether a value expression is one whose type the declaration output prints as written. */
+function printedAsWritten(node) {
+    return (isParenthesizedExpression(node) ||
+        isAsExpression(node) ||
+        isTypeAssertion(node) ||
+        isSatisfiesExpression(node) ||
+        isObjectLiteralExpression(node) ||
+        isArrowFunction(node) ||
+        isFunctionExpression(node) ||
+        isClassExpression(node));
+}
+/** Whether a type node is the `const` of a const assertion, which names no type. */
+function isConstName(node) {
+    return isTypeReferenceNode(node) && isIdentifier(node.typeName) && node.typeName.text === "const";
+}
+/**
+ * Whether the declaration output prints a type or a member it meets by this declaration's
+ * written types: a function type's, a signature's, a member's, or an expression's that
+ * {@link printedAsWritten} holds. A type literal or a mapped type it prints from the
+ * checker's members, so only each member's own declaration is read.
+ */
+function reused(node) {
+    return (isFunctionTypeNode(node) ||
+        isConstructorTypeNode(node) ||
+        isPropertySignatureDeclaration(node) ||
+        isMethodSignatureDeclaration(node) ||
+        isCallSignatureDeclaration(node) ||
+        isConstructSignatureDeclaration(node) ||
+        isPropertyAssignment(node) ||
+        isPropertyDeclaration(node) ||
+        isMethodDeclaration(node) ||
+        isGetAccessorDeclaration(node) ||
+        isSetAccessorDeclaration(node) ||
+        printedAsWritten(node));
+}
+/**
+ * Whether the declaration output leaves out the types one node of a declaration writes.
+ * It prints an initializer only where its declaration has no annotation, and then as the
+ * checker types it, except through what {@link printedAsWritten} holds: an assertion's
+ * type in place of its operand, a function's or a class's signatures, an object literal's
+ * properties, and the operand of a `satisfies`. A decorator and an enum member's or a
+ * binding element's initializer are not printed.
+ */
+function unprinted(node) {
+    const parent = node.parent;
+    if (parent === undefined) {
+        return false;
+    }
+    if (isDecorator(node)) {
+        return true;
+    }
+    const held = parent;
+    if (held.initializer === node) {
+        return (isEnumMember(parent) ||
+            isBindingElement(parent) ||
+            held.type !== undefined ||
+            !printedAsWritten(node));
+    }
+    if (isAsExpression(parent) || isTypeAssertion(parent)) {
+        return isConstName(parent.type)
+            ? node === parent.type || !printedAsWritten(node)
+            : node === parent.expression;
+    }
+    if (isSatisfiesExpression(parent)) {
+        return node === parent.type || !printedAsWritten(node);
+    }
+    if (isParenthesizedExpression(parent) || isSpreadAssignment(parent)) {
+        return !printedAsWritten(node);
+    }
+    return false;
+}
+/**
+ * The declarations of the target each declaration of one project carries: those it names
+ * as written, and those its type names as the checker reads it, so an inferred result names
+ * its type as an annotation does. The walk reads a type's constituents, type arguments,
+ * alias arguments, `partsOf`, literal members and index signatures, and each signature's
+ * parameters, result and `signaturePartsOf`. A type of the target ends the walk, since its
+ * own definition is read as its own.
+ */
+export function carriersOf(project, held) {
+    const { queries } = project;
+    const chains = aliasChains(project, held);
+    const kinds = new Map(held.symbols.map((symbol) => [symbol.id, symbol.kind]));
+    const parents = new Map(held.symbols.map((symbol) => [symbol.id, symbol.parent]));
+    const wanted = new Set(carrying(held).map((symbol) => symbol.id));
+    const declared = [];
+    // A nested carrier and any other member of a type are read on that member, not on the
+    // declaration that holds it; a type parameter is part of its declaration.
+    const readAloneIn = (file) => (nested) => {
+        const id = held.declarations.get(nodeKey(file, nested));
+        const kind = id === undefined ? undefined : kinds.get(id);
+        return (unprinted(nested) ||
+            (id !== undefined &&
+                kind !== "type-parameter" &&
+                (wanted.has(id) || TYPES.has(kinds.get(parents.get(id) ?? "") ?? "file"))));
+    };
+    for (const file of project.ownSourceFiles()) {
+        const readAlone = readAloneIn(file);
+        const visit = (node) => {
+            const id = held.declarations.get(nodeKey(file, node));
+            if (id !== undefined && wanted.has(id)) {
+                declared.push({
+                    id,
+                    handle: project.handle(nameNode(node)),
+                    written: typeNamesOf(node, readAlone).map((name) => project.handle(name)),
+                });
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    const unread = new Set();
+    let reading = "";
+    const answer = (found, otherwise) => {
+        if (isAnswered(found)) {
+            return found;
+        }
+        unread.add(reading);
+        return otherwise;
+    };
+    const typesOf = (symbol) => chains.declarationsOf(symbol).filter((id) => TYPES.has(kinds.get(id) ?? "file"));
+    // The declaration output prints an anonymous type or a literal's member by its own
+    // declaration's written types where it has them, which name an alias the checker erases,
+    // so the walk of one declaration keeps the target's own declarations of those it meets.
+    const own = project.ownPaths();
+    let meeting = new Map();
+    const meet = (symbol) => {
+        for (const handle of symbol.declarations) {
+            if (own.has(handle.path)) {
+                meeting.set(`${handle.path}#${String(handle.index)}`, handle);
+            }
+        }
+    };
+    const signatures = (type, into, seen) => {
+        for (const kind of [SignatureKind.Call, SignatureKind.Construct]) {
+            for (const signature of answer(queries.signaturesOf(type, kind), [])) {
+                signature.parameters.forEach((_parameter, index) => {
+                    walk(answer(queries.parameterType(signature, index), undefined), into, seen);
+                });
+                walk(answer(queries.returnTypeOf(signature), undefined), into, seen);
+                for (const part of answer(queries.signaturePartsOf(signature), [])) {
+                    walk(part, into, seen);
+                }
+            }
+        }
+    };
+    // The parts of a type that spell other types, not counting the type itself.
+    const structure = (type, into, seen) => {
+        for (const part of answer(queries.constituents(type), [])) {
+            if (part.id !== type.id) {
+                walk(part, into, seen);
+            }
+        }
+        for (const argument of answer(queries.typeArguments(type), [])) {
+            walk(argument, into, seen);
+        }
+        for (const part of answer(queries.partsOf(type), [])) {
+            walk(part, into, seen);
+        }
+        const symbol = answer(queries.symbolOfType(type), undefined);
+        if (symbol !== undefined && (symbol.flags & LITERAL) !== 0) {
+            for (const property of answer(queries.propertiesOf(type), [])) {
+                meet(property);
+                walk(answer(queries.typeOfSymbol(property), undefined), into, seen);
+            }
+            for (const info of answer(queries.indexInfosOf(type), [])) {
+                walk(info.valueType, into, seen);
+            }
+        }
+        signatures(type, into, seen);
+    };
+    const walk = (type, into, seen) => {
+        if (type === undefined || seen.has(type.id)) {
+            return;
+        }
+        seen.add(type.id);
+        const alias = answer(queries.aliasSymbolOf(type), undefined);
+        if (alias !== undefined) {
+            for (const id of typesOf(alias)) {
+                into.add(id);
+            }
+            for (const argument of answer(queries.aliasArgumentsOf(type), [])) {
+                walk(argument, into, seen);
+            }
+            if (typesOf(alias).length > 0) {
+                return;
+            }
+        }
+        const symbol = answer(queries.symbolOfType(type), undefined);
+        const named = symbol === undefined ? [] : typesOf(symbol);
+        if (named.length > 0) {
+            for (const id of named) {
+                into.add(id);
+            }
+            for (const argument of answer(queries.typeArguments(type), [])) {
+                walk(argument, into, seen);
+            }
+            return;
+        }
+        if (symbol !== undefined) {
+            meet(symbol);
+        }
+        structure(type, into, seen);
+    };
+    // What one declaration's checker type names, by its kind.
+    const definition = (symbol, kind, into) => {
+        const seen = new Set();
+        // A class's or an interface's own definition: its properties are members, which carry
+        // on their own, so only its bases, signatures and index signatures are read here.
+        const own = (type) => {
+            for (const info of answer(queries.indexInfosOf(type), [])) {
+                walk(info.valueType, into, seen);
+            }
+            signatures(type, into, seen);
+        };
+        if (kind === "class" || kind === "interface") {
+            const instance = answer(queries.declaredTypeOf(symbol), undefined);
+            const statics = kind === "class" ? answer(queries.typeOfSymbol(symbol), undefined) : undefined;
+            const sides = [instance, statics].filter((side) => side !== undefined);
+            for (const side of sides) {
+                seen.add(side.id);
+            }
+            for (const base of instance === undefined ? [] : answer(queries.baseTypes(instance), [])) {
+                walk(base, into, seen);
+            }
+            sides.forEach(own);
+        }
+        else if (kind === "type") {
+            const aliased = answer(queries.declaredTypeOf(symbol), undefined);
+            if (aliased !== undefined) {
+                seen.add(aliased.id);
+                structure(aliased, into, seen);
+            }
+        }
+        else if (kind !== "enum") {
+            walk(answer(queries.typeOfSymbol(symbol), undefined), into, seen);
+        }
+    };
+    const symbols = project.symbolsAt(declared.map((one) => one.handle));
+    const spelled = project.symbolsAt(declared.flatMap((one) => one.written));
+    const reached = [];
+    const add = (answered, into) => {
+        const name = answer(answered, undefined);
+        for (const target of name === undefined ? [] : chains.chainOf(name)) {
+            if (TYPES.has(kinds.get(target.id) ?? "file")) {
+                into.add(target.id);
+            }
+        }
+    };
+    let from = 0;
+    declared.forEach(({ id, written }, index) => {
+        reading = id;
+        const into = new Set();
+        for (const answered of spelled.slice(from, from + written.length)) {
+            add(answered, into);
+        }
+        from += written.length;
+        meeting = new Map();
+        const symbol = answer(symbols[index], undefined);
+        if (symbol !== undefined) {
+            definition(symbol, kinds.get(id), into);
+        }
+        reached.push({ id, into, met: [...meeting.values()] });
+    });
+    const namesAt = new Map();
+    const writtenAt = (handle) => {
+        const key = `${handle.path}#${String(handle.index)}`;
+        let names = namesAt.get(key);
+        if (names === undefined) {
+            const node = project.declarationAt(handle)?.node;
+            names =
+                node === undefined || !reused(node)
+                    ? []
+                    : typeNamesOf(node, readAloneIn(node.getSourceFile())).map((name) => project.handle(name));
+            namesAt.set(key, names);
+        }
+        return names;
+    };
+    const metNames = reached.map((one) => one.met.flatMap(writtenAt));
+    const metSpelled = project.symbolsAt(metNames.flat());
+    const named = new Map();
+    from = 0;
+    reached.forEach(({ id, into }, index) => {
+        reading = id;
+        const count = metNames[index]?.length ?? 0;
+        for (const answered of metSpelled.slice(from, from + count)) {
+            add(answered, into);
+        }
+        from += count;
+        into.delete(id);
+        named.set(id, [...into]);
+    });
+    return { named, unread };
+}
+/**
+ * The types whose values a reference from outside the package reaches through the
+ * package's own declarations, or every type where such a reference reaches a declaration
+ * whose surface the checker left unread. `outside` flags each declaration of the graph a
+ * reference from outside names; each passes the reach on to what it carries, a type to
+ * each member it exports, a namespace to each declaration it exports and a member to its
+ * type, until no declaration joins.
+ */
+export function exposedTypes(graph, outside, carriers) {
+    const { symbols, parent } = graph;
+    const members = symbols.map(() => []);
+    symbols.forEach((symbol, at) => {
+        const container = parent[at] ?? OUTSIDE;
+        const holder = symbols[container];
+        if (holder !== undefined &&
+            ((TYPES.has(holder.kind) && MEMBERS.has(symbol.kind) && exportedMember(symbol)) ||
+                (holder.kind === "namespace" && symbol.exported))) {
+            members[container]?.push(at);
+        }
+    });
+    const reached = symbols.map((_symbol, at) => outside[at] === true);
+    const queue = reached.flatMap((one, at) => (one ? [at] : []));
+    const join = (at) => {
+        if (at !== OUTSIDE && reached[at] !== true) {
+            reached[at] = true;
+            queue.push(at);
+        }
+    };
+    for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
+        const symbol = symbols[at];
+        if (symbol === undefined) {
+            continue;
+        }
+        if (carriers?.unread.has(symbol.id) === true) {
+            return "every";
+        }
+        for (const id of carriers?.named.get(symbol.id) ?? []) {
+            join(graph.at(id));
+        }
+        for (const member of members[at] ?? []) {
+            join(member);
+        }
+        if (MEMBERS.has(symbol.kind)) {
+            join(parent[at] ?? OUTSIDE);
+        }
+    }
+    return new Set(symbols.flatMap((symbol, at) => reached[at] === true && TYPES.has(symbol.kind) ? [symbol.id] : []));
+}
+/** Whether code outside the package holds values of a type through the package's declarations. */
+export function exposes(exposed, symbol) {
+    return TYPES.has(symbol.kind) && (exposed === "every" || exposed.has(symbol.id));
+}

package/dist/src/extensions.js

@@ -0,0 +1,37 @@
+/** The extension lists the analysis reads files by, each written once. */
+/**
+ * The extensions tried, in order, after a path written without one: a relative specifier
+ * of a configuration file (`roots.5`) and a path a command runs or loads (`roots.13`).
+ */
+export const APPENDED_EXTENSIONS = [
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+];
+/** The extensions of a module a tool runs or loads as its configuration (`roots.2`). */
+export const MODULE_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts"];
+/** The extensions of a file a build writes from a source file. */
+export const OUTPUT_EXTENSIONS = [
+    ".js",
+    ".mjs",
+    ".cjs",
+    ".jsx",
+    ".d.ts",
+    ".d.mts",
+    ".d.cts",
+];
+/** One list as a glob's brace list, its dots dropped: `{js,mjs}`. */
+export function braced(extensions) {
+    return `{${extensions.map((one) => one.slice(1)).join(",")}}`;
+}
+/** The extension of one list a name ends with, the longest where several do. */
+export function extensionOf(name, extensions) {
+    return extensions
+        .filter((one) => name.endsWith(one))
+        .reduce((longest, one) => (one.length > (longest?.length ?? 0) ? one : longest), undefined);
+}

package/dist/src/facts.js

@@ -0,0 +1,38 @@
+/**
+ * The facts document `--facts` writes, `bindings.1` and `bindings.2`: the run's generated
+ * files under the one decision the generated-file class reads, and the binding identities
+ * they publish. No binding state is computed, so it states `evaluated: false` (`bindings.10`).
+ */
+import { FACTS_VERSION } from "./contract/contract.generated.js";
+import { LANGUAGE, PRODUCT } from "./product.js";
+import { bytewise } from "./text/compare.js";
+/** The facts document of one run, as the text written to the path `--facts` names. */
+export function factsDocument(version, generated, bindings) {
+    const document = {
+        facts_version: FACTS_VERSION,
+        analyzer: { name: PRODUCT, version },
+        language: LANGUAGE,
+        evaluated: false,
+        generated: [...generated]
+            .sort(([a], [b]) => bytewise(a, b))
+            .map(([path, fact]) => ({
+            path,
+            line: fact.line,
+            evidence: fact.evidence,
+            detail: fact.detail,
+            ...(fact.generator === undefined
+                ? {}
+                : {
+                    generator: {
+                        row: fact.generator.row,
+                        ...(fact.generator.version === undefined
+                            ? {}
+                            : { version: fact.generator.version }),
+                    },
+                    schema_files: fact.generator.schemaFiles,
+                }),
+        })),
+        bindings,
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}

package/dist/src/failure.js

@@ -0,0 +1,36 @@
+import { FAILURE_CLASSES, FAILURE_PREFIXES } from "./contract/contract.generated.js";
+import { PRODUCT } from "./product.js";
+/** The failure as a class line of the error stream, opened by its group's prefix. */
+export function failureLine(failure) {
+    return `${FAILURE_PREFIXES[FAILURE_CLASSES[failure.failureClass]]}${failure.failureClass}: ${failure.detail}`;
+}
+/**
+ * The lines of the error stream that name the failures: the first one's class line, the run's
+ * only one, then each further failure as its class and detail with no group prefix.
+ */
+export function failureLines([first, ...further]) {
+    return [failureLine(first), ...further.map((one) => `${one.failureClass}: ${one.detail}`)];
+}
+/**
+ * A run the analysis cannot answer. It ends the run with the failure code and no finding
+ * list, printing the compiler's located errors and then the failures' lines.
+ */
+export class FailureExit extends Error {
+    failures;
+    /** The compiler's errors behind the failures, in the order it reported them. */
+    diagnostics;
+    constructor(failures, diagnostics = []) {
+        super(failureLines(failures).join("\n"));
+        this.name = "FailureExit";
+        this.failures = failures;
+        this.diagnostics = diagnostics;
+    }
+}
+/** A failure exit of one failure. */
+export function failureExit(failureClass, detail, diagnostics = []) {
+    return new FailureExit([{ failureClass, detail }], diagnostics);
+}
+/** A fault of this analyzer itself, `fault` saying what it cannot do. */
+export function productFault(fault) {
+    return failureExit("product-fault", `${PRODUCT} ${fault}: reinstall ${PRODUCT}, and report the fault to its maintainers if a reinstalled ${PRODUCT} fails the same way`);
+}

package/dist/src/file-facts.js

@@ -3,10 +3,10 @@
  * file below the target root, whether or not a project includes it, and the files a
  * program holds by inclusion rather than by an import.
  */
-import { IGNORED_DIRECTORIES } from "./discover.js";
-import { packageScope } from "./inventory.js";
+import { packageScope } from "./load/package-scope.js";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
 import { renderRef } from "./ref.js";
+import { filesBelow } from "./fs/tree.js";
 /** A file name the compiler reads as a source file. */
 const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
 /** A file name the compiler reads as a declaration file, which no build emits code from. */
@@ -30,30 +30,7 @@ function lastLine(text) {
  * that cannot be read is skipped, as discovery skips it.
  */
 export function sourcePaths(host, targetRoot) {
-    const found = [];
-    const pending = [""];
-    for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
-        let entries;
-        try {
-            entries = host.readDirectory(joinPath(targetRoot, dir));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
-            if (entry.directory) {
-                if (!IGNORED_DIRECTORIES.has(entry.name)) {
-                    pending.push(path);
-                }
-                continue;
-            }
-            if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name)) {
-                found.push(path);
-            }
-        }
-    }
-    return found.sort((a, b) => (a < b ? -1 : 1));
+    return filesBelow(host, targetRoot, (name) => SOURCE_FILE.test(name) && !DECLARATION_FILE.test(name));
 }
 /**
  * Every source file below the target root, in path order. A file that cannot be read is