@cplieger/deadset-ts 3.5.0 → 3.6.0

package/dist/src/findings/visibility-narrowing.js

@@ -1,2 +1,239 @@
-/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
-export const visibilityNarrowing = () => [];
+import { OUTSIDE } from "../graph.js";
+import { writeOnlyDeclarations } from "./reads-and-writes.js";
+const UNNECESSARY_EXPORT = "DS1101";
+const UNREACHABLE_EXPORT = "DS1103";
+const REDUNDANT_EXPORT_KEYWORD = "DS1104";
+/**
+ * The root kinds by which a consumer importing the package reaches a declaration. A
+ * declaration or a file rooted by any other kind is entered by something that names it
+ * from outside the reference graph: a runtime, a tool, a framework or the configuration.
+ */
+const PUBLISHING = new Set(["manifest-entry", "published-api"]);
+/** The reader's word for each kind of declaration this family reports. */
+const WORDS = {
+    function: "function",
+    class: "class",
+    interface: "interface",
+    type: "type alias",
+    enum: "enum",
+    namespace: "namespace",
+    variable: "variable",
+    "export-alias": "re-export",
+};
+function publishes(kinds) {
+    return [...(kinds ?? [])].some((kind) => PUBLISHING.has(kind));
+}
+function entersByName(kinds) {
+    return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind));
+}
+/**
+ * Folds the run's references into the reach of each declaration.
+ *
+ * A reference reaches the file that holds the declaration that makes it. A reference
+ * from a declaration the inventory does not hold is made by a consumer, and one from a
+ * re-export a manifest export reaches stands for every consumer importing the name it
+ * publishes; either reaches outside the package.
+ */
+function factsOf(graph) {
+    const { symbols, parent } = graph;
+    const fileOf = symbols.map((_symbol, at) => {
+        let file = at;
+        while (file !== OUTSIDE && symbols[file]?.kind !== "file") {
+            file = parent[file] ?? OUTSIDE;
+        }
+        return file;
+    });
+    const rootedBy = symbols.map(() => new Set());
+    for (const root of graph.rooted) {
+        rootedBy[root.at]?.add(root.kind);
+    }
+    const published = symbols.map(() => false);
+    symbols.forEach((_symbol, at) => {
+        const file = fileOf[at] ?? OUTSIDE;
+        if (file !== OUTSIDE && publishes(rootedBy[at])) {
+            published[file] = true;
+        }
+    });
+    const order = ["file", "package", "outside"];
+    const wider = (a, b) => (order.indexOf(a) >= order.indexOf(b) ? a : b);
+    const inGraph = symbols.map(() => 0);
+    const reach = symbols.map(() => "file");
+    graph.out.forEach((edges, from) => {
+        const republished = symbols[from]?.kind === "export-alias" && publishes(rootedBy[from]);
+        for (const edge of edges) {
+            inGraph[edge.to] = (inGraph[edge.to] ?? 0) + 1;
+            const scope = republished
+                ? "outside"
+                : fileOf[from] === fileOf[edge.to]
+                    ? "file"
+                    : "package";
+            reach[edge.to] = wider(reach[edge.to] ?? "file", scope);
+        }
+    });
+    const named = graph.made.map((counts) => counts.production + counts.test);
+    named.forEach((count, at) => {
+        if (count > (inGraph[at] ?? 0)) {
+            reach[at] = "outside";
+        }
+    });
+    return { graph, fileOf, rootedBy, published, named, reach };
+}
+/** Whether one declaration is a declaration its file's export table names. */
+function topLevelExport(facts, at, symbol) {
+    const parent = facts.graph.parent[at] ?? OUTSIDE;
+    return symbol.exported && parent !== OUTSIDE && facts.graph.symbols[parent]?.kind === "file";
+}
+function wordOf(symbol) {
+    return WORDS[symbol.kind] ?? symbol.kind;
+}
+/** The visibility each narrowing code names, which only the narrowing codes carry. */
+const NARROWER = {
+    [REDUNDANT_EXPORT_KEYWORD]: "file",
+    [UNNECESSARY_EXPORT]: "package",
+};
+function findingOf(symbol, code, message) {
+    const { path, line, column } = symbol.position;
+    const narrower = Object.hasOwn(NARROWER, code) ? NARROWER[code] : undefined;
+    const endLine = Math.max(line, symbol.endLine);
+    return {
+        code,
+        position: { path, line, column, endLine },
+        symbol: {
+            ref: symbol.ref,
+            kind: symbol.kind,
+            name: symbol.name,
+            sizeLines: endLine - line + 1,
+        },
+        message,
+        details: narrower === undefined ? {} : { narrowerVisibility: narrower },
+    };
+}
+/**
+ * The narrowing finding about one live declaration, if one holds: an export of a file,
+ * no re-export and none the write-only kind reports, that a reference names and nothing
+ * enters by name. Every reference inside its own file makes it a redundant export
+ * keyword, where no manifest export reaches the file or the world is closed; references
+ * from other files of the package alone make a published one unnecessary when closed.
+ */
+function narrowing(facts, at, symbol, world) {
+    const { closed } = world;
+    const file = facts.fileOf[at] ?? OUTSIDE;
+    if (!topLevelExport(facts, at, symbol) ||
+        world.writeOnly.has(symbol.ref) ||
+        symbol.kind === "export-alias" ||
+        entersByName(facts.rootedBy[at]) ||
+        entersByName(facts.rootedBy[file]) ||
+        (facts.named[at] ?? 0) === 0) {
+        return undefined;
+    }
+    const word = wordOf(symbol);
+    switch (facts.reach[at]) {
+        case "file":
+            if (facts.published[file] === true && !closed) {
+                return undefined;
+            }
+            return findingOf(symbol, REDUNDANT_EXPORT_KEYWORD, `exported ${word} is referenced only inside the file that declares it`);
+        case "package":
+            if (!closed || !publishes(facts.rootedBy[at])) {
+                return undefined;
+            }
+            return findingOf(symbol, UNNECESSARY_EXPORT, `exported ${word} is referenced only inside the package that declares it`);
+        default:
+            return undefined;
+    }
+}
+/**
+ * The unreachable-export finding about one dead declaration, if one holds: an unused
+ * export no code outside the target can import, because the manifest declares
+ * `exports` and no root reaches it. Each arm yields to a more specific kind, so one
+ * declaration is reported once: a test whose every subject is dead, an interface, a
+ * declaration only a test file references, and a deprecated one.
+ */
+function unreachable(facts, at, symbol, candidate, input) {
+    if (!input.boundary.encapsulated ||
+        !topLevelExport(facts, at, symbol) ||
+        (facts.rootedBy[at]?.size ?? 0) > 0 ||
+        candidate.testOfDeadCode ||
+        symbol.kind === "interface" ||
+        (candidate.productionRefs === 0 && candidate.testRefs > 0) ||
+        (candidate.productionRefs === 0 && input.deprecated.has(symbol.id))) {
+        return undefined;
+    }
+    const found = candidate.relation === "reachability"
+        ? "is referenced only from declarations that are themselves dead"
+        : "has no reference in the target";
+    return findingOf(symbol, UNREACHABLE_EXPORT, `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`);
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`.
+ *
+ * A finding about a symbol a declared cross-language edge names is pending instead of
+ * reported, once per side naming it: the edge counts as a reference from outside the
+ * file and the package, and whether it is a use is decided on the side in the other
+ * language.
+ */
+export function narrowings(input) {
+    const { boundary } = input;
+    const facts = factsOf(input.swept.matrix.union);
+    const { declared, loaded } = boundary.consumers;
+    const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+    const world = { closed, writeOnly: writeOnlyDeclarations(input) };
+    const candidates = new Map(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
+    const findings = [];
+    const pending = [];
+    facts.graph.symbols.forEach((symbol, at) => {
+        const candidate = candidates.get(symbol.id);
+        const found = candidate === undefined
+            ? narrowing(facts, at, symbol, world)
+            : unreachable(facts, at, symbol, candidate, input);
+        if (found === undefined) {
+            return;
+        }
+        const named = boundary.edges.filter((side) => side.symbol === symbol.ref);
+        if (named.length === 0) {
+            findings.push(found);
+            return;
+        }
+        for (const side of named) {
+            pending.push({ ...side, finding: found });
+        }
+    });
+    pending.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+    return { findings, pending };
+}
+/**
+ * The declarations the unreachable-export kind reports, whether or not a declared edge
+ * holds the finding pending: the unused-declaration kinds yield each to it.
+ */
+export function unreachableExports(input) {
+    const facts = factsOf(input.swept.matrix.union);
+    const found = new Set();
+    for (const candidate of input.swept.sweep.candidates) {
+        const at = facts.graph.at(candidate.id);
+        const symbol = facts.graph.symbols[at];
+        if (symbol !== undefined && unreachable(facts, at, symbol, candidate, input) !== undefined) {
+            found.add(symbol.id);
+        }
+    }
+    return found;
+}
+/**
+ * The findings of the visibility-narrowing family, `DS1100` to `DS1199`. A finding a
+ * declared edge holds pending belongs in that edge's evaluation, which this analyzer
+ * does not publish yet, so a run that holds one is refused rather than reported
+ * without it.
+ */
+export const visibilityNarrowing = (input) => {
+    const { findings, pending } = narrowings(input);
+    if (pending.length > 0) {
+        throw new Error(`${String(pending.length)} finding(s) a declared edge holds pending, and no edge evaluation is published`);
+    }
+    return findings;
+};

package/dist/src/implementations.js

@@ -0,0 +1,210 @@
+/**
+ * Which classes of the target implement which of its interfaces, and how each writes
+ * every method such an interface declares. A class implements an interface its
+ * `implements` clause names, in any instantiation, or one with a member its instance
+ * type is assignable to, asked only of a class carrying every member the interface
+ * requires and one it declares, and never of a generic side.
+ */
+import { isClassDeclaration, isHeritageClause, isInterfaceDeclaration, isMethodDeclaration, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.js";
+import { nodeKey } from "./inventory.js";
+import { DEFAULT_BATCH_CAP } from "./references.js";
+/** The interfaces, the classes and the `implements` entries of one project's own files. */
+function walk(project, held) {
+    const interfaces = [];
+    const classes = [];
+    const clauses = [];
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            if (isInterfaceDeclaration(node) || isClassDeclaration(node)) {
+                const id = held.declarations.get(nodeKey(file, node));
+                const name = node.name;
+                if (id !== undefined && name !== undefined) {
+                    const declared = { id, nameNode: name, generic: node.typeParameters !== undefined };
+                    if (isInterfaceDeclaration(node)) {
+                        interfaces.push(declared);
+                    }
+                    else {
+                        classes.push(declared);
+                        for (const clause of node.heritageClauses ?? []) {
+                            if (isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword) {
+                                clauses.push(...clause.types.map((entry) => ({ owner: declared, entry })));
+                            }
+                        }
+                    }
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return { interfaces, classes, clauses };
+}
+/** The type at each node, asked in capped batches. */
+function typesAt(project, nodes) {
+    const typeAt = new Map();
+    for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+        const run = nodes.slice(from, from + DEFAULT_BATCH_CAP);
+        project.checker.getTypeAtLocation(run).forEach((type, index) => {
+            const node = run[index];
+            if (type !== undefined && node !== undefined) {
+                typeAt.set(node, type);
+            }
+        });
+    }
+    return typeAt;
+}
+/** Whether one class member is a method whose every written body holds no statement. */
+function emptyImplementation(project, member) {
+    const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+    let bodies = 0;
+    for (const handle of member.declarations) {
+        // A body outside the target is one this analysis cannot read, so it is not empty.
+        if (!own.has(handle.path)) {
+            return false;
+        }
+        const node = project.declarationAt(handle)?.node;
+        if (node === undefined || !isMethodDeclaration(node)) {
+            return false;
+        }
+        if (node.body !== undefined) {
+            if (node.body.statements.length > 0) {
+                return false;
+            }
+            bodies += 1;
+        }
+    }
+    return bodies > 0;
+}
+/** How one project's interfaces are implemented by its classes. */
+export function implementations(project, held) {
+    const classes = new Map();
+    const bodies = new Map();
+    const walked = walk(project, held);
+    if (walked.interfaces.length === 0 || walked.classes.length === 0) {
+        return { classes, bodies };
+    }
+    const checker = project.checker;
+    const typeAt = typesAt(project, [
+        ...walked.interfaces.map((one) => one.nameNode),
+        ...walked.classes.map((one) => one.nameNode),
+        ...walked.clauses.map((clause) => clause.entry),
+    ]);
+    // Two declarations of one interface merge into one type.
+    const byType = new Map();
+    for (const declared of walked.interfaces) {
+        const type = typeAt.get(declared.nameNode);
+        if (type === undefined) {
+            continue;
+        }
+        const merged = byType.get(type.id);
+        if (merged === undefined) {
+            byType.set(type.id, { ids: [declared.id], type, generic: declared.generic });
+        }
+        else {
+            merged.ids.push(declared.id);
+            merged.generic ||= declared.generic;
+        }
+    }
+    const classAt = new Map();
+    for (const owner of walked.classes) {
+        const type = typeAt.get(owner.nameNode);
+        if (type !== undefined) {
+            classAt.set(owner.id, { owner, type });
+        }
+    }
+    const membersOf = (at) => (at.members ??= checker.getPropertiesOfType(at.type));
+    const classMembers = (at) => (at.members ??= new Map(checker.getPropertiesOfType(at.type).map((member) => [member.escapedName, member])));
+    const methodIds = new Set(held.symbols.filter((symbol) => symbol.kind === "interface-method").map((symbol) => symbol.id));
+    const chains = aliasChains(project, held);
+    const record = (at, implementer) => {
+        for (const id of at.ids) {
+            let set = classes.get(id);
+            if (set === undefined) {
+                set = new Set();
+                classes.set(id, set);
+            }
+            set.add(implementer.owner.id);
+        }
+        const written = classMembers(implementer);
+        for (const member of membersOf(at)) {
+            const answering = written.get(member.escapedName);
+            if (answering === undefined) {
+                continue;
+            }
+            const empty = emptyImplementation(project, answering);
+            for (const id of chains.declarationsOf(member)) {
+                if (!methodIds.has(id)) {
+                    continue;
+                }
+                let byClass = bodies.get(id);
+                if (byClass === undefined) {
+                    byClass = new Map();
+                    bodies.set(id, byClass);
+                }
+                byClass.set(implementer.owner.id, empty);
+            }
+        }
+    };
+    const recorded = new Set();
+    const pair = (at, implementer) => {
+        const key = `${String(at.type.id)}:${implementer.owner.id}`;
+        if (!recorded.has(key)) {
+            recorded.add(key);
+            record(at, implementer);
+        }
+    };
+    for (const clause of walked.clauses) {
+        const entry = typeAt.get(clause.entry);
+        const implementer = classAt.get(clause.owner.id);
+        if (entry === undefined || implementer === undefined) {
+            continue;
+        }
+        const at = byType.get(entry.isTypeReference() ? entry.getTarget().id : entry.id);
+        if (at !== undefined) {
+            pair(at, implementer);
+        }
+    }
+    for (const at of byType.values()) {
+        const members = at.generic ? [] : membersOf(at);
+        if (members.length === 0) {
+            continue;
+        }
+        const required = members.filter((member) => (member.flags & SymbolFlags.Optional) === 0);
+        for (const implementer of classAt.values()) {
+            if (implementer.owner.generic) {
+                continue;
+            }
+            const written = classMembers(implementer);
+            if (required.every((member) => written.has(member.escapedName)) &&
+                members.some((member) => written.has(member.escapedName)) &&
+                checker.isTypeAssignableTo(implementer.type, at.type)) {
+                pair(at, implementer);
+            }
+        }
+    }
+    return { classes, bodies };
+}
+/** Every project's answers as one run's, each implementation once. */
+export function mergeImplementations(per) {
+    const classes = new Map();
+    const bodies = new Map();
+    for (const one of per) {
+        for (const [id, held] of one.classes) {
+            const set = classes.get(id) ?? new Set();
+            classes.set(id, set);
+            for (const owner of held) {
+                set.add(owner);
+            }
+        }
+        for (const [id, held] of one.bodies) {
+            const byClass = bodies.get(id) ?? new Map();
+            bodies.set(id, byClass);
+            for (const [owner, empty] of held) {
+                byClass.set(owner, (byClass.get(owner) ?? true) && empty);
+            }
+        }
+    }
+    return { classes, bodies };
+}

package/dist/src/inventory.js

@@ -13,7 +13,7 @@ const MANIFEST = "package.json";
  * One directory is read at most once, because a package holds many files and a
  * manifest read is a filesystem call.
  */
-function packages(host, root) {
+export function packageScope(host, root) {
     const named = new Map();
     const manifestName = (dir) => {
         let text;
@@ -233,7 +233,7 @@ function typeMemberKind(node, inInterface) {
 export function inventory(project, host, targetRoot) {
     const files = project.ownSourceFiles();
     const ownFiles = new Set(files.map((file) => file.fileName));
-    const moduleOf = packages(host, targetRoot);
+    const moduleOf = packageScope(host, targetRoot);
     const building = [];
     const byNode = new Map();
     const exportScopes = [];

package/dist/src/resolve.js

@@ -4,7 +4,7 @@ import { checkDocument, malformed, nestFlags, SCHEMA_ROOT, SEVERITY_SECTION, } f
 /** Names the command-line flags in a refusal, where a document is named by its path. */
 const FLAGS_LABEL = "the command-line flags";
 /** The length of a severity key naming a whole family: the prefix and two digits. */
-const FAMILY_KEY_LENGTH = 4;
+export const FAMILY_KEY_LENGTH = 4;
 const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;
 const CONTRACT_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/u;

package/dist/src/stores.js

@@ -0,0 +1,32 @@
+/**
+ * What a run knows about the stores into its declarations and the reads of them, which
+ * a sweep does not keep: a sweep asks whether anything names a declaration, and a store
+ * names it as surely as a read does.
+ */
+import { isGetAccessorDeclaration, isSetAccessorDeclaration, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+/** The class members one project's own files declare by a getter or a setter. */
+export function accessorsOf(project, held) {
+    const found = [];
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node) => {
+            if (isGetAccessorDeclaration(node) || isSetAccessorDeclaration(node)) {
+                const id = held.declarations.get(nodeKey(file, node));
+                if (id !== undefined) {
+                    found.push(id);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        file.forEachChild(visit);
+    }
+    return found;
+}
+/** The run's stores, from what each configuration contributed, the records and the mode. */
+export function storesOf(per, exempt, mode) {
+    return {
+        references: per.flatMap((one) => one.references.filter((reference) => !mode.production || !reference.test)),
+        accessors: new Set(per.flatMap((one) => one.accessors)),
+        exempt: new Set(exempt.map((record) => record.id)),
+    };
+}

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",