@cplieger/deadset-ts 3.5.0 → 3.6.0

package/dist/src/deprecation.js

@@ -0,0 +1,83 @@
+/**
+ * Which declarations of one project carry the deprecation marker, the documentation tag
+ * the TypeScript tools recognize, as the checker reports a symbol's tags: gathered from
+ * every declaration of the symbol, so overloads, an accessor pair and a merged
+ * declaration share them. A declaration list's documentation covers every name it
+ * declares, and the checker attaches it to the first name alone, so the later names read
+ * the list's own tags from the tree.
+ */
+import { isVariableStatement, SyntaxKind } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The tag the TypeScript tools recognize as marking a declaration deprecated. */
+const DEPRECATED_TAG = "deprecated";
+/** Whether one node's own documentation carries the deprecation tag. */
+function documentedDeprecated(node) {
+    const docs = node.jsDoc ?? [];
+    return docs.some((doc) => (doc.tags ?? []).some((tag) => tag.kind === SyntaxKind.JSDocDeprecatedTag));
+}
+/** The node a declaration's symbol is resolved at: its name, or itself where it has none. */
+function nameNode(node) {
+    return node.name ?? node;
+}
+/**
+ * The identifiers of every declaration of one project that carries the deprecation
+ * marker, in the inventory's order.
+ *
+ * The checker is asked only for a symbol with a declaration in a file whose tree holds
+ * the tag, so a project whose files hold none costs no round trip, and one that does
+ * costs one batch per file and one request per symbol that could carry the tag.
+ */
+export function deprecatedDeclarations(project, held) {
+    const marked = new Set();
+    const markedPaths = new Set();
+    const declared = [];
+    for (const file of project.ownSourceFiles()) {
+        const named = [];
+        const visit = (node) => {
+            if (documentedDeprecated(node)) {
+                markedPaths.add(file.path);
+                if (isVariableStatement(node)) {
+                    for (const declaration of node.declarationList.declarations) {
+                        const id = held.declarations.get(nodeKey(file, declaration));
+                        if (id !== undefined) {
+                            marked.add(id);
+                        }
+                    }
+                }
+            }
+            const id = held.declarations.get(nodeKey(file, node));
+            if (id !== undefined && node !== file) {
+                named.push({ id, handle: project.handle(nameNode(node)) });
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+        declared.push(named);
+    }
+    if (markedPaths.size > 0) {
+        const asked = new Map();
+        const carriesTag = (symbol) => {
+            const known = asked.get(symbol.id);
+            if (known !== undefined) {
+                return known;
+            }
+            const carries = symbol.declarations.some((declaration) => markedPaths.has(declaration.path)) &&
+                symbol.getJsDocTags(project.checker).some((tag) => tag.name === DEPRECATED_TAG);
+            asked.set(symbol.id, carries);
+            return carries;
+        };
+        for (const named of declared) {
+            for (let start = 0; start < named.length; start += DEFAULT_BATCH_CAP) {
+                const batch = named.slice(start, start + DEFAULT_BATCH_CAP);
+                project.symbolsAt(batch.map((one) => one.handle)).forEach((symbol, at) => {
+                    const one = batch[at];
+                    if (symbol !== undefined && one !== undefined && carriesTag(symbol)) {
+                        marked.add(one.id);
+                    }
+                });
+            }
+        }
+    }
+    return held.symbols.filter((symbol) => marked.has(symbol.id)).map((symbol) => symbol.id);
+}

package/dist/src/discover.js

@@ -1,7 +1,7 @@
 import { DiagnosticCategory } from "@typescript/native/unstable/sync";
 import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.js";
 /** Directory names discovery does not descend into. */
-const IGNORED_DIRECTORIES = new Set(["node_modules", ".git"]);
+export const IGNORED_DIRECTORIES = new Set(["node_modules", ".git"]);
 /** A compiler configuration file discovery recognises under a root. */
 const CONFIG_FILE = /^tsconfig.*\.json$/u;
 /**

package/dist/src/enum-group.js

@@ -0,0 +1,217 @@
+/**
+ * The enum-group class: every member of an `enum` declaration is held back when a value
+ * of the enum arrives by conversion rather than by a member's name. The conversions are
+ * a type assertion from a number or a string, an element access on the enum object
+ * keyed by anything but literal text, and a decoded value typed as the enum: an `any`
+ * or `unknown` expression asserted to it, or bound to a variable or returned from a
+ * function it annotates, where a number counts too. An enum's own value converts nothing.
+ */
+import { isArrowFunction, isAsExpression, isElementAccessExpression, isEnumDeclaration, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isIdentifier, isMethodDeclaration, isNoSubstitutionTemplateLiteral, isParenthesizedExpression, isParenthesizedTypeNode, isPropertyAccessExpression, isReturnStatement, isStringLiteral, isVariableDeclaration, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { TypeFlags } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.js";
+import { nodeKey } from "./inventory.js";
+import { renderPosition } from "./position.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The operand types a conversion produces an enum value from. */
+const NUMBER = TypeFlags.NumberLike;
+const STRING = TypeFlags.StringLike;
+const DECODED = TypeFlags.Any | TypeFlags.Unknown;
+/** 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;
+}
+/**
+ * The name node a type node names its declaration by: the identifier of a type
+ * reference, the right side of a qualified one, through parentheses. A type that is no
+ * reference names no declaration.
+ */
+function typeName(type) {
+    let held = type;
+    while (held !== undefined && isParenthesizedTypeNode(held)) {
+        held = held.type;
+    }
+    if (held?.kind !== SyntaxKind.TypeReference) {
+        return undefined;
+    }
+    const name = held.typeName;
+    if (name.kind === SyntaxKind.QualifiedName) {
+        return name.right;
+    }
+    return name;
+}
+/** The name node an expression names an object by: an identifier, or a property access's name. */
+function objectName(expression) {
+    const held = unparenthesized(expression);
+    if (isIdentifier(held)) {
+        return held;
+    }
+    return isPropertyAccessExpression(held) ? held.name : undefined;
+}
+/** The return type annotation of the function a return statement leaves, where it has one. */
+function returnTypeOf(statement) {
+    for (let at = statement.parent; at.kind !== SyntaxKind.SourceFile; at = at.parent) {
+        if (isFunctionDeclaration(at) ||
+            isMethodDeclaration(at) ||
+            isFunctionExpression(at) ||
+            isArrowFunction(at) ||
+            isGetAccessorDeclaration(at)) {
+            return at.type;
+        }
+    }
+    return undefined;
+}
+/** Every site of one file that may produce a value of a type it names, in source order. */
+function sitesOf(file) {
+    const found = [];
+    const annotated = (type, value, at) => {
+        const name = typeName(type);
+        if (name !== undefined && value !== undefined) {
+            found.push({ form: "annotation", name, operand: value, at });
+        }
+    };
+    const visit = (node) => {
+        if (isAsExpression(node) || node.kind === SyntaxKind.TypeAssertionExpression) {
+            const assertion = node;
+            const name = typeName(assertion.type);
+            if (name !== undefined) {
+                found.push({ form: "assertion", name, operand: assertion.expression, at: node });
+            }
+        }
+        else if (isElementAccessExpression(node)) {
+            const key = node.argumentExpression;
+            const name = objectName(node.expression);
+            if (name !== undefined && !isStringLiteral(key) && !isNoSubstitutionTemplateLiteral(key)) {
+                found.push({ form: "lookup", name, operand: undefined, at: node });
+            }
+        }
+        else if (isVariableDeclaration(node)) {
+            annotated(node.type, node.initializer, node.initializer ?? node);
+        }
+        else if (isReturnStatement(node) && node.expression !== undefined) {
+            annotated(returnTypeOf(node), node.expression, node.expression);
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * The parts of one type that are not values of an enum: its constituents where it is a
+ * union, and itself otherwise. An enum's own value, or one of its members, is a value the
+ * source names, whichever number or string it also is.
+ */
+function partsOf(type) {
+    const parts = type.isUnionType() ? type.getTypes() : [type];
+    return parts.filter((part) => (part.flags & TypeFlags.EnumLike) === 0);
+}
+/**
+ * The detail one site records about the enum it produces, or undefined where the
+ * operand's type converts nothing: a number, or a string an assertion converts, is
+ * converted, a value of type `any` or `unknown` is decoded, and a value of an enum is one
+ * the source names.
+ */
+function detailOf(site, enumName, operand) {
+    if (site.form === "lookup") {
+        return `looked up by an element access on ${enumName}`;
+    }
+    if (operand === undefined) {
+        return undefined;
+    }
+    const parts = partsOf(operand);
+    if (parts.some((part) => (part.flags & NUMBER) !== 0)) {
+        return "converted from number";
+    }
+    if (parts.some((part) => (part.flags & STRING) !== 0)) {
+        return site.form === "assertion" ? "converted from string" : undefined;
+    }
+    if (parts.some((part) => (part.flags & DECODED) !== 0)) {
+        return `decoded as ${enumName}`;
+    }
+    return undefined;
+}
+/**
+ * The enum-group detector: every member of each enum declaration of the target that a
+ * conversion produces a value of, recorded at each conversion.
+ */
+export function enumGroup(input) {
+    const { project, held, targetRoot } = input;
+    const files = project.ownSourceFiles();
+    // The enums of the target, by the identifier of their declaration, with their names.
+    const enums = new Map();
+    for (const file of files) {
+        const visit = (node) => {
+            if (isEnumDeclaration(node)) {
+                const id = held.declarations.get(nodeKey(file, node));
+                if (id !== undefined) {
+                    enums.set(id, node.name.getText());
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    if (enums.size === 0) {
+        return [];
+    }
+    const sites = files.flatMap(sitesOf);
+    const named = new Map();
+    const chains = aliasChains(project, held);
+    for (let from = 0; from < sites.length; from += DEFAULT_BATCH_CAP) {
+        const run = sites.slice(from, from + DEFAULT_BATCH_CAP);
+        project.symbolsAt(run.map((site) => project.handle(site.name))).forEach((symbol, index) => {
+            const site = run[index];
+            if (symbol === undefined || site === undefined) {
+                return;
+            }
+            const target = chains.chainOf(symbol).find((link) => enums.has(link.id));
+            if (target !== undefined) {
+                named.set(site, target.id);
+            }
+        });
+    }
+    const typed = sites.filter((site) => named.has(site) && site.operand !== undefined);
+    const operandType = new Map();
+    for (let from = 0; from < typed.length; from += DEFAULT_BATCH_CAP) {
+        const run = typed.slice(from, from + DEFAULT_BATCH_CAP);
+        project.checker
+            .getTypeAtLocation(run.map((site) => site.operand ?? site.at))
+            .forEach((type, index) => {
+            const site = run[index];
+            if (type !== undefined && site !== undefined) {
+                operandType.set(site, type);
+            }
+        });
+    }
+    const members = new Map();
+    for (const symbol of held.symbols) {
+        if (symbol.kind === "enum-member" && enums.has(symbol.parent)) {
+            const listed = members.get(symbol.parent);
+            if (listed === undefined) {
+                members.set(symbol.parent, [symbol.id]);
+            }
+            else {
+                listed.push(symbol.id);
+            }
+        }
+    }
+    const found = [];
+    for (const site of sites) {
+        const enumId = named.get(site);
+        if (enumId === undefined) {
+            continue;
+        }
+        const detail = detailOf(site, enums.get(enumId) ?? "", operandType.get(site));
+        if (detail === undefined) {
+            continue;
+        }
+        const position = renderPosition(site.at.getSourceFile(), targetRoot, site.at.getStart());
+        for (const id of members.get(enumId) ?? []) {
+            found.push({ id, detail, site: position });
+        }
+    }
+    return found;
+}

package/dist/src/file-facts.js

@@ -0,0 +1,101 @@
+/**
+ * What the file kinds read about the target's files beside the sweep: every source
+ * 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 { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
+import { renderRef } from "./ref.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. */
+const DECLARATION_FILE = /\.d\.(?:[^./]+\.)?[mc]?ts$/u;
+/** A line break as the compiler counts lines. */
+const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/gu;
+/** The line of the last character of one text, counted from one; an empty text is one line. */
+function lastLine(text) {
+    const last = Math.max(text.length - 1, 0);
+    let line = 1;
+    for (const found of text.matchAll(LINE_BREAK)) {
+        if (found.index + found[0].length > last) {
+            break;
+        }
+        line += 1;
+    }
+    return line;
+}
+/**
+ * Every source file below the target root, in path order. A directory that cannot be
+ * read is skipped, as discovery skips it, and a file that cannot be read is skipped
+ * with it: a tree the analysis may not enter holds no file it can report.
+ */
+export function sourceTree(host, targetRoot) {
+    const scopeOf = packageScope(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)) {
+                continue;
+            }
+            let text;
+            try {
+                text = host.readFile(joinPath(targetRoot, path));
+            }
+            catch {
+                continue;
+            }
+            found.push({
+                path,
+                ref: renderRef(scopeOf(path), { of: "module" }),
+                endLine: lastLine(text),
+            });
+        }
+    }
+    return found.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+/** Whether one file changes what the program sees by being included in it. */
+function actsByInclusion(file) {
+    return (file.referencedFiles.length > 0 ||
+        file.typeReferenceDirectives.length > 0 ||
+        file.libReferenceDirectives.length > 0 ||
+        file.moduleAugmentations.length > 0 ||
+        file.ambientModuleNames.length > 0);
+}
+/**
+ * The paths below the target root of one project's own files the program holds by
+ * inclusion, in the order the program holds them, each once.
+ */
+export function heldByInclusion(project, targetRoot) {
+    const held = new Set();
+    const add = (fileName) => {
+        const path = relativePath(targetRoot, fileName);
+        if (path !== undefined) {
+            held.add(path);
+        }
+    };
+    for (const file of project.ownSourceFiles()) {
+        if (actsByInclusion(file)) {
+            add(file.fileName);
+        }
+        for (const reference of file.referencedFiles) {
+            add(resolvePath(dirnamePath(file.fileName), reference.fileName));
+        }
+    }
+    return [...held];
+}

package/dist/src/findings/boundary.js

@@ -0,0 +1 @@
+export {};

package/dist/src/findings/completion.js

@@ -0,0 +1,99 @@
+/**
+ * What a finding about a declaration carries beyond what its emitter decides, read from
+ * the run: the reachability class and the confidence, the relation that decided the
+ * subject, the dead component it falls in, the configurations it holds in, and the
+ * severity the configuration gives its code. The dials withhold what they name and
+ * every finding that falls with a root they withhold.
+ */
+import { componentId } from "../components.js";
+import { FAMILY_KEY_LENGTH } from "../resolve.js";
+/** The classes ranked by the claim each makes, the strongest highest. */
+export const RANK = { certain: 3, probable: 2, possible: 1 };
+/** The weaker of two classes, which is a class capped by a ceiling. */
+export function capped(found, ceiling) {
+    return RANK[found] <= RANK[ceiling] ? found : ceiling;
+}
+/**
+ * The severity the configuration gives one code: the key naming the code, else the key
+ * naming its family, else the code's default.
+ */
+export function severityOf(config, code, fallback) {
+    return (config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback);
+}
+/**
+ * The reachability class of one declaration of the run. A declaration of a library's
+ * published API has callers outside the target, and the run loads no consumer that
+ * would name them, so it is `possible`; every other declaration has every reference
+ * in the loaded program, a private member and a `#private` name among them, and is
+ * `certain`.
+ */
+export function reachabilityClasses(swept) {
+    const union = swept.matrix.union;
+    const published = new Set(union.rooted
+        .filter((root) => root.kind === "published-api")
+        .map((root) => union.symbols[root.at]?.id));
+    return (id) => (published.has(id) ? "possible" : "certain");
+}
+/** The component each dead declaration of the run falls in, and none for a live one. */
+export function findingComponents(swept) {
+    const held = new Map();
+    for (const component of swept.sweep.components) {
+        for (const member of component.members) {
+            held.set(member, component);
+        }
+    }
+    return (id) => {
+        const component = held.get(id);
+        return component === undefined
+            ? undefined
+            : {
+                id: component.id,
+                root: component.roots.includes(id),
+                symbolCount: component.members.length,
+                deletableLines: component.deletableLines,
+            };
+    };
+}
+/**
+ * Every finding of the run, each with its component, in the order given: the dead
+ * component its subject falls in. A subject in none, a live declaration, a file no
+ * program builds or a manifest row, falls with nothing and is given a component of its
+ * own, numbered past the run's computed components in the order the findings come, so
+ * no two families mint one identifier.
+ */
+export function placed(swept, findings) {
+    const componentOf = findingComponents(swept);
+    const ids = new Map(swept.matrix.union.symbols.map((symbol) => [symbol.ref, symbol.id]));
+    let minted = swept.sweep.components.length;
+    return findings.map((finding) => {
+        const id = ids.get(finding.symbol.ref);
+        const component = id === undefined ? undefined : componentOf(id);
+        if (component !== undefined) {
+            return { ...finding, component };
+        }
+        minted += 1;
+        return {
+            ...finding,
+            component: {
+                id: componentId(minted),
+                root: true,
+                symbolCount: 1,
+                deletableLines: finding.symbol.sizeLines,
+            },
+        };
+    });
+}
+/**
+ * The findings no dial withholds. A finding at `allow` or below the minimum confidence
+ * is withheld, and so is every finding of the component of a root the dials withhold,
+ * because a symbol that falls with a root is dead only through it and its deletion
+ * does not compile while the root stays. A withheld finding that is no root withholds
+ * itself alone.
+ */
+export function reportable(findings, minConfidence) {
+    const dialed = (finding) => finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+    const components = new Set(findings
+        .filter((finding) => finding.component.root && dialed(finding))
+        .map((finding) => finding.component.id));
+    return findings.filter((finding) => !dialed(finding) && !components.has(finding.component.id));
+}

package/dist/src/findings/dependencies-and-module-machinery.js

@@ -1,2 +1,66 @@
+import { renderRef } from "../ref.js";
+import { severityOf } from "./completion.js";
+const UNUSED_DEPENDENCY = "DS1601";
+/** The severity the kind ships at, which the configuration's keys override. */
+const UNUSED_DEPENDENCY_SEVERITY = "deny";
+const MESSAGES = {
+    dependency: "no import in the target needs the declared dependency",
+    "dev-dependency": "no import in the target needs the declared development dependency",
+    "peer-dependency": "no import in the target needs the declared peer dependency",
+};
+/**
+ * The dependencies the target needs: every package the projects' uses name, every
+ * declared dependency that ships a command, which a script, a workflow or a shell
+ * runs outside anything the analysis reads, and every peer a needed package
+ * requires, which the target satisfies by declaring it.
+ */
+function neededBy(dependencies) {
+    const needed = new Set(dependencies.needed);
+    for (const [name, installed] of dependencies.installed) {
+        if (installed.command) {
+            needed.add(name);
+        }
+    }
+    const pending = [...needed];
+    for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
+        for (const peer of dependencies.installed.get(name)?.peers ?? []) {
+            if (!needed.has(peer)) {
+                needed.add(peer);
+                pending.push(peer);
+            }
+        }
+    }
+    return needed;
+}
+/**
+ * A dependency, development dependency or peer dependency of the target's manifest
+ * that the target does not need, at the position of its key. Nothing is reported at
+ * `allow`. Every subject is a manifest entry, which is `certain` whatever the
+ * consumers, so no minimum confidence withholds one.
+ */
+function unusedDependencies(config, dependencies) {
+    if (severityOf(config, UNUSED_DEPENDENCY, UNUSED_DEPENDENCY_SEVERITY) === "allow") {
+        return [];
+    }
+    const needed = neededBy(dependencies);
+    return dependencies.declared
+        .filter((dependency) => !needed.has(dependency.name))
+        .map((dependency) => ({
+        code: UNUSED_DEPENDENCY,
+        position: dependency.position,
+        symbol: {
+            ref: renderRef(dependencies.manifest, {
+                of: "dependency",
+                name: dependency.name,
+                section: dependency.section,
+            }),
+            kind: "dependency",
+            name: dependency.name,
+            sizeLines: 1,
+        },
+        message: MESSAGES[dependency.section],
+        details: { dependencyClass: dependency.section },
+    }));
+}
 /** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
-export const dependenciesAndModuleMachinery = () => [];
+export const dependenciesAndModuleMachinery = ({ config, dependencies }) => unusedDependencies(config, dependencies);

package/dist/src/findings/emitters.js

@@ -1,4 +1,5 @@
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.js";
+import { placed } from "./completion.js";
 import { interfaces } from "./interfaces.js";
 import { intraFunction } from "./intra-function.js";
 import { nonCodeArtifacts } from "./non-code-artifacts.js";
@@ -17,3 +18,10 @@ export const EMITTERS = new Map([
     ["self-check", selfCheck],
     ["intra-function", intraFunction],
 ]);
+/**
+ * Every finding of the run, each family's in table order, each placed in its component
+ * by the one step that numbers the components minted for subjects that fall with none.
+ */
+export function findingsOf(input) {
+    return placed(input.swept, [...EMITTERS.values()].flatMap((emit) => emit(input)));
+}