@cplieger/deadset-ts 3.5.0 → 3.7.0

package/dist/src/findings/interfaces.js

@@ -1,2 +1,95 @@
-/** The findings of the interfaces family, `DS1200` to `DS1299`. */
-export const interfaces = () => [];
+import { byPosition } from "../position.js";
+const UNUSED_INTERFACE = "DS1201";
+const UNCALLED_INTERFACE_METHOD = "DS1203";
+/** What each finding says, by what the sweep found about the subject's references. */
+const UNUSED_MESSAGE = "nothing in the target names the interface as a type";
+const UNUSED_DEAD_MESSAGE = "the interface is named as a type only from declarations that are themselves dead";
+const UNUSED_TEST_MESSAGE = "the interface is named as a type only from test files";
+const UNCALLED_MESSAGE = "no call site invokes or selects the method through the interface";
+/** Where one declaration is written, as a finding carries it. */
+function positionOf(symbol) {
+    return { ...symbol.position, endLine: Math.max(symbol.position.line, symbol.endLine) };
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** One run's declarations and candidates, indexed for the two kinds. */
+function indexed(input) {
+    const union = input.swept.matrix.union;
+    const symbols = new Map(union.symbols.map((symbol) => [symbol.id, symbol]));
+    const candidates = new Map(input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
+    const symbolOf = (id) => symbols.get(id);
+    return {
+        symbolOf,
+        inTest: (id) => union.test[union.at(id)] === true,
+        candidateOf: (id) => candidates.get(id),
+        implementationsOf: (id) => [...(input.implementations.classes.get(id) ?? [])]
+            .map(symbolOf)
+            .filter((symbol) => symbol !== undefined)
+            .map((symbol) => ({ ref: symbol.ref, name: symbol.name, position: positionOf(symbol) }))
+            .sort((a, b) => byPosition(a.position, b.position) || compare(a.ref, b.ref)),
+    };
+}
+/** The finding one code makes about one declaration. */
+function findingOf(code, symbol, message, implementations) {
+    const position = positionOf(symbol);
+    return {
+        code,
+        position,
+        symbol: {
+            ref: symbol.ref,
+            kind: symbol.kind,
+            name: symbol.name,
+            sizeLines: position.endLine - position.line + 1,
+        },
+        message,
+        details: { implementations },
+    };
+}
+/**
+ * The findings of the interfaces family, `DS1200` to `DS1299`: `DS1201`, a dead
+ * interface, whose members fall with it unreported; and `DS1203`, a method of a live
+ * interface no reference names, unless it is a marker, a method whose every
+ * implementation has an empty body. A test file's declaration is neither kind's
+ * subject, because a production sweep counts none of the references it can have.
+ */
+export const interfaces = (input) => {
+    const run = indexed(input);
+    const found = [];
+    for (const candidate of input.swept.sweep.candidates) {
+        const symbol = run.symbolOf(candidate.id);
+        if (symbol === undefined || run.inTest(candidate.id)) {
+            continue;
+        }
+        if (symbol.kind === "interface") {
+            found.push(findingOf(UNUSED_INTERFACE, symbol, unusedMessage(candidate), run.implementationsOf(candidate.id)));
+            continue;
+        }
+        if (symbol.kind !== "interface-method" ||
+            candidate.productionRefs + candidate.testRefs > 0 ||
+            run.candidateOf(symbol.parent) !== undefined ||
+            marker(input, candidate.id)) {
+            continue;
+        }
+        found.push(findingOf(UNCALLED_INTERFACE_METHOD, symbol, UNCALLED_MESSAGE, run.implementationsOf(symbol.parent)));
+    }
+    return found;
+};
+/** What one unused interface's finding says, by the references the sweep counted. */
+function unusedMessage(candidate) {
+    if (candidate.relation === "reachability") {
+        return UNUSED_DEAD_MESSAGE;
+    }
+    return candidate.testRefs > 0 && candidate.productionRefs === 0
+        ? UNUSED_TEST_MESSAGE
+        : UNUSED_MESSAGE;
+}
+/** Whether one interface method has implementations and every one has an empty body. */
+function marker(input, method) {
+    const bodies = [...(input.implementations.bodies.get(method)?.values() ?? [])];
+    return bodies.length > 0 && bodies.every((empty) => empty);
+}

package/dist/src/findings/non-code-artifacts.js

@@ -1,2 +1,98 @@
+const FILE_NEVER_BUILT = "DS1501";
+const FILE_NEVER_IMPORTED = "DS1502";
+/** The subject kind of a finding about a source file, from the finding schema's vocabulary. */
+const FILE_SUBJECT = "file";
+/** A file's subject starts at its first character. */
+const FILE_START = 1;
+/**
+ * Whether the configuration declares the run's matrix complete. The declaration is
+ * about the projects the configuration lists, so a configuration declaring
+ * completeness and listing no project declares it of a matrix the run derived, and a
+ * derived matrix is never complete.
+ */
+function completeMatrix(config) {
+    return (config.analysis.matrixComplete &&
+        config.analysis.configurations.some((entry) => entry.shape === "project"));
+}
+/** One finding about a whole file. */
+function fileFinding(code, file, message) {
+    return {
+        code,
+        position: { path: file.path, line: FILE_START, column: FILE_START, endLine: file.endLine },
+        symbol: { ref: file.ref, kind: FILE_SUBJECT, name: file.path, sizeLines: file.endLine },
+        message,
+    };
+}
+/**
+ * Every source file below the target root that no project of the matrix includes,
+ * under a matrix the configuration declares complete: that declaration says the listed
+ * projects are every one the target builds, so a file none of them includes is built
+ * by nothing. Under a derived matrix nothing is reported, because a project the
+ * derivation did not find is no evidence that nothing builds the file.
+ */
+function fileNeverBuilt({ config, swept, files }) {
+    if (!completeMatrix(config)) {
+        return [];
+    }
+    const built = new Set(swept.matrix.union.symbols
+        .filter((symbol) => symbol.kind === FILE_SUBJECT)
+        .map((symbol) => symbol.position.path));
+    const message = `no project of the build matrix includes this file (${swept.matrix.configurations.join(", ")})`;
+    return files.tree
+        .filter((file) => !built.has(file.path))
+        .map((file) => fileFinding(FILE_NEVER_BUILT, file, message));
+}
+/**
+ * The paths of every file a reference written in another file reaches, naming the
+ * file or a declaration in it. An import is such a reference, so an import from any
+ * file reaches what it names, whatever reaches the importing file.
+ */
+function reachedFromOutside(union) {
+    const reached = new Set();
+    union.out.forEach((edges, from) => {
+        const fromPath = union.symbols[from]?.position.path;
+        for (const edge of edges) {
+            const to = union.symbols[edge.to];
+            if (to !== undefined && to.position.path !== fromPath) {
+                reached.add(to.position.path);
+            }
+        }
+    });
+    return reached;
+}
+/**
+ * The paths of the files an import reaches, a root names, or a declared edge names a
+ * declaration in. A file holding a declaration the sweep judged live is kept whatever
+ * held it live, and so is a file a program holds by inclusion, which acts on every
+ * file of the program without an import naming it.
+ */
+function keptFiles({ swept, files, boundary }) {
+    const union = swept.matrix.union;
+    const edgeNamed = new Set(boundary.edges.map((side) => side.symbol));
+    const dead = new Set(swept.sweep.candidates.map((candidate) => candidate.id));
+    const kept = new Set([...reachedFromOutside(union), ...files.heldByInclusion]);
+    for (const root of union.rooted) {
+        const named = union.symbols[root.at];
+        if (named !== undefined) {
+            kept.add(named.position.path);
+        }
+    }
+    for (const symbol of union.symbols) {
+        if ((symbol.kind !== FILE_SUBJECT && !dead.has(symbol.id)) || edgeNamed.has(symbol.ref)) {
+            kept.add(symbol.position.path);
+        }
+    }
+    return kept;
+}
+/** Every file of the run that no import reaches and no root or edge names. */
+function fileNeverImported(input) {
+    const kept = keptFiles(input);
+    return input.swept.matrix.union.symbols
+        .filter((symbol) => symbol.kind === FILE_SUBJECT && !kept.has(symbol.position.path))
+        .map((symbol) => fileFinding(FILE_NEVER_IMPORTED, { path: symbol.position.path, ref: symbol.ref, endLine: symbol.endLine }, "no import reaches this file and no root names it or a declaration in it"));
+}
 /** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
-export const nonCodeArtifacts = () => [];
+export const nonCodeArtifacts = (input) => [
+    ...fileNeverBuilt(input),
+    ...fileNeverImported(input),
+];

package/dist/src/findings/reads-and-writes.js

@@ -1,2 +1,146 @@
-/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
-export const readsAndWrites = () => [];
+import { positionKey } from "../position.js";
+/** The containers whose type parameters `DS1303` reports: a function and a class method. */
+const SIGNATURES = new Set(["function", "method"]);
+function indexed(input) {
+    const { matrix, sweep } = input.swept;
+    return {
+        input,
+        symbols: new Map(matrix.union.symbols.map((symbol) => [symbol.id, symbol])),
+        candidates: new Map(sweep.candidates.map((candidate) => [candidate.id, candidate])),
+    };
+}
+/** Where one declaration is, as a finding states it. */
+function positionOf(symbol) {
+    return {
+        path: symbol.position.path,
+        line: symbol.position.line,
+        column: symbol.position.column,
+        endLine: Math.max(symbol.position.line, symbol.endLine),
+    };
+}
+/** The finding one code makes about one declaration. */
+function findingAbout(symbol, code, message, details) {
+    const position = positionOf(symbol);
+    return {
+        code,
+        position,
+        symbol: {
+            ref: symbol.ref,
+            kind: symbol.kind,
+            name: symbol.name,
+            sizeLines: position.endLine - position.line + 1,
+        },
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+}
+/**
+ * Whether one declaration is a subject of the write-only kind: a module-level variable,
+ * or a class member that is state rather than code. A getter or a setter is code, so a
+ * store into one runs it.
+ */
+function writable(run, symbol) {
+    if (symbol.kind === "variable") {
+        return true;
+    }
+    return symbol.kind === "class-member" && !run.input.stores.accessors.has(symbol.id);
+}
+/**
+ * `DS1301`: a module-level variable or a class member the counted references store into
+ * and never read, named with every position written.
+ *
+ * The subject is a live declaration: a store is a reference, so the sweep holds a
+ * written one live and its candidates are never this kind's. Every reference that is
+ * not a store reads, and so does an exemption record naming the declaration.
+ */
+function writeOnlySymbols(run) {
+    const { stores } = run.input;
+    const { matrix } = run.input.swept;
+    const uses = new Map();
+    for (const reference of stores.references) {
+        let held = uses.get(reference.to);
+        if (held === undefined) {
+            held = { writes: [], reads: 0 };
+            uses.set(reference.to, held);
+        }
+        if (reference.use !== "write") {
+            held.reads += 1;
+            continue;
+        }
+        const at = reference.position;
+        const key = positionKey(at);
+        if (!held.writes.some((written) => positionKey(written) === key)) {
+            held.writes.push({ path: at.path, line: at.line, column: at.column, endLine: at.line });
+        }
+    }
+    const found = [];
+    for (const symbol of matrix.union.symbols) {
+        const held = uses.get(symbol.id);
+        if (held === undefined ||
+            held.writes.length === 0 ||
+            held.reads > 0 ||
+            !writable(run, symbol) ||
+            stores.exempt.has(symbol.id) ||
+            run.candidates.has(symbol.id)) {
+            continue;
+        }
+        const writes = held.writes.length === 1 ? "once" : `at ${String(held.writes.length)} positions`;
+        const word = symbol.kind === "variable" ? "variable" : "member";
+        found.push(findingAbout(symbol, "DS1301", `${word} ${symbol.name} is written ${writes} and never read`, {
+            writePositions: held.writes,
+        }));
+    }
+    return found;
+}
+/**
+ * The candidates no reference of any file names whose container is not itself dead, of
+ * one kind. A reference from a test file alone leaves a candidate to the test-only kind,
+ * and a member of a dead container falls with it and is reported inside its component.
+ */
+function unnamed(run, kind) {
+    return run.input.swept.sweep.candidates.flatMap((candidate) => {
+        const symbol = run.symbols.get(candidate.id);
+        if (symbol?.kind !== kind ||
+            candidate.productionRefs > 0 ||
+            candidate.testRefs > 0 ||
+            run.candidates.has(symbol.parent)) {
+            return [];
+        }
+        return [symbol];
+    });
+}
+/**
+ * `DS1302`: a member of an enum declaration that nothing names. A member an enum-group
+ * record holds back is no candidate, so a member a conversion can produce never reaches
+ * this kind.
+ */
+function unusedEnumMembers(run) {
+    return unnamed(run, "enum-member").map((symbol) => findingAbout(symbol, "DS1302", `enum member ${symbol.name} is named nowhere`));
+}
+/**
+ * `DS1303`: a type parameter of a function or a class method that neither the
+ * declaration's signature nor its body names. A type parameter of a class, an interface,
+ * a type alias or a method signature belongs to a type declaration and is never
+ * reported, because a phantom parameter makes two instantiations distinct types.
+ */
+function unusedTypeParameters(run) {
+    return unnamed(run, "type-parameter")
+        .filter((symbol) => SIGNATURES.has(run.symbols.get(symbol.parent)?.kind ?? ""))
+        .map((symbol) => findingAbout(symbol, "DS1303", `type parameter ${symbol.name} is named in neither its signature nor its body`));
+}
+/**
+ * The references of the declarations the write-only kind reports, whatever the
+ * severity: a narrowing kind yields each to it, since deleting the declaration
+ * supersedes narrowing it.
+ */
+export function writeOnlyDeclarations(input) {
+    return new Set(writeOnlySymbols(indexed(input)).map((finding) => finding.symbol.ref));
+}
+/**
+ * The findings of the reads-and-writes family, `DS1300` to `DS1399`, in code order and
+ * each code's in site order.
+ */
+export const readsAndWrites = (input) => {
+    const run = indexed(input);
+    return [...writeOnlySymbols(run), ...unusedEnumMembers(run), ...unusedTypeParameters(run)];
+};

package/dist/src/findings/unused-declarations.js

@@ -1,2 +1,151 @@
+import { unreachableExports } from "./visibility-narrowing.js";
+/** The kinds of declaration that are members of a class, an interface, a type or an enum. */
+const MEMBERS = new Set([
+    "method",
+    "class-member",
+    "type-member",
+    "enum-member",
+]);
+/**
+ * The kinds of declaration no code of this family reports: an interface and a method an
+ * interface declares are the interface kinds' subjects, and a type parameter is the
+ * subject of the unused-type-parameter kind or of none.
+ */
+const NOT_THIS_FAMILY = new Set([
+    "file",
+    "interface",
+    "interface-method",
+    "type-parameter",
+]);
+/** The reader's word for each kind of declaration a finding of the family names. */
+const WORDS = {
+    file: "file",
+    function: "function",
+    class: "class",
+    interface: "interface",
+    type: "type alias",
+    enum: "enum",
+    namespace: "namespace",
+    variable: "variable",
+    "export-alias": "re-export",
+    method: "method",
+    "class-member": "class member",
+    "interface-method": "interface method",
+    "type-member": "type member",
+    "enum-member": "enum member",
+    "type-parameter": "type parameter",
+};
+/** What the test-of-dead-code kind says, which states the rule it applies. */
+const TEST_OF_DEAD_CODE = "every target symbol this test references is reported dead";
+/**
+ * The code one candidate is reported under, or none, each symbol once under the most
+ * specific code: a test of dead code first; no other test-file declaration, member of a
+ * dead container or enum member nothing names; then deprecation, a test reference, and
+ * the unreferenced codes, an unimportable unused export being the unreachable kind's.
+ */
+function codeOf(judged) {
+    const { candidate, symbol } = judged;
+    if (candidate.testOfDeadCode) {
+        return "DS1005";
+    }
+    if (judged.test || judged.containerDead || NOT_THIS_FAMILY.has(symbol.kind)) {
+        return undefined;
+    }
+    const referenced = candidate.productionRefs + candidate.testRefs > 0;
+    if (symbol.kind === "enum-member" && !referenced) {
+        return undefined;
+    }
+    if (candidate.productionRefs === 0 && judged.deprecated) {
+        return "DS1006";
+    }
+    if (candidate.productionRefs === 0 && candidate.testRefs > 0) {
+        return "DS1004";
+    }
+    if (MEMBERS.has(symbol.kind)) {
+        return "DS1003";
+    }
+    if (!symbol.exported) {
+        return "DS1002";
+    }
+    return judged.unreachable ? undefined : "DS1001";
+}
+/** The visibility a member's message names, where it narrows the member's reach. */
+function visibilityWord(symbol) {
+    switch (symbol.visibility) {
+        case "private":
+        case "private-name":
+            return "private ";
+        case "protected":
+            return "protected ";
+        case "public":
+            return "";
+    }
+}
+/**
+ * What one finding says: what the subject is, and what the analysis found about its
+ * references. A candidate reachability found has references, each from a declaration
+ * that is itself dead, so saying it has none would be false.
+ */
+function messageOf(code, judged) {
+    const { candidate, symbol } = judged;
+    const word = WORDS[symbol.kind];
+    switch (code) {
+        case "DS1005":
+            return TEST_OF_DEAD_CODE;
+        case "DS1006":
+            return `deprecated ${word} has no production reference`;
+        case "DS1004":
+            return `${word} is referenced only from test files and never from production code`;
+    }
+    const subject = code === "DS1003"
+        ? `${visibilityWord(symbol)}${word}`
+        : symbol.kind === "export-alias"
+            ? word
+            : `${symbol.exported ? "exported" : "unexported"} ${word}`;
+    if (candidate.relation === "reachability") {
+        return `${subject} is referenced only from declarations that are themselves dead`;
+    }
+    if (code === "DS1001") {
+        return `${subject} has no reference in the target and none from any loaded consumer`;
+    }
+    return `${subject} has no reference in the target`;
+}
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations = () => [];
+export const unusedDeclarations = (input) => {
+    const union = input.swept.matrix.union;
+    const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
+    const unreachable = unreachableExports(input);
+    const found = [];
+    for (const candidate of input.swept.sweep.candidates) {
+        const at = union.at(candidate.id);
+        const symbol = union.symbols[at];
+        if (symbol === undefined) {
+            continue;
+        }
+        const judged = {
+            candidate,
+            symbol,
+            test: union.test[at] === true,
+            containerDead: dead.has(symbol.parent),
+            deprecated: input.deprecated.has(symbol.id),
+            unreachable: unreachable.has(symbol.id),
+        };
+        const code = codeOf(judged);
+        if (code === undefined) {
+            continue;
+        }
+        const endLine = Math.max(symbol.position.line, symbol.endLine);
+        found.push({
+            code,
+            position: { ...symbol.position, endLine },
+            symbol: {
+                ref: symbol.ref,
+                kind: symbol.kind,
+                name: symbol.name,
+                sizeLines: endLine - symbol.position.line + 1,
+            },
+            message: messageOf(code, judged),
+        });
+    }
+    return found;
+};