@cplieger/deadset-ts 3.4.0 → 3.6.0

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,199 @@
-/** The findings of the reads-and-writes family, `DS1300` to `DS1399`. */
-export const readsAndWrites = () => [];
+import { positionKey } from "../position.js";
+import { findingComponents, RANK, reachabilityClasses, severityOf, } from "./completion.js";
+/**
+ * Each code's severity where the configuration sets none, as the issue-kind vocabulary
+ * states it.
+ */
+export const DEFAULT_SEVERITY = {
+    DS1301: "deny",
+    DS1302: "deny",
+    DS1303: "deny",
+};
+/** The containers whose type parameters `DS1303` reports: a function and a class method. */
+const SIGNATURES = new Set(["function", "method"]);
+/** The severity the configuration gives one code of the family. */
+function severityIn(input, code) {
+    return severityOf(input.config, code, DEFAULT_SEVERITY[code]);
+}
+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])),
+        componentOf: findingComponents(input.swept),
+        classOf: reachabilityClasses(input.swept),
+    };
+}
+/** 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 about one declaration, every member the family decides filled in. */
+function findingAbout(run, symbol, code, message, facts) {
+    const position = positionOf(symbol);
+    const reachabilityClass = run.classOf(symbol.id);
+    const component = run.componentOf(symbol.id);
+    return {
+        code,
+        position,
+        symbol: {
+            ref: symbol.ref,
+            kind: symbol.kind,
+            name: symbol.name,
+            sizeLines: position.endLine - position.line + 1,
+        },
+        message,
+        reachabilityClass,
+        confidence: reachabilityClass,
+        ...(facts.livenessRelation === undefined ? {} : { livenessRelation: facts.livenessRelation }),
+        testOnly: facts.testOnly,
+        ...(component === undefined ? {} : { component }),
+        configurations: facts.configurations,
+        severity: severityIn(run.input, code),
+        details: facts.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, production: 0, test: 0 };
+            uses.set(reference.to, held);
+        }
+        if (reference.test) {
+            held.test += 1;
+        }
+        else {
+            held.production += 1;
+        }
+        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 = [];
+    matrix.union.symbols.forEach((symbol, at) => {
+        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)) {
+            return;
+        }
+        const writes = held.writes.length === 1 ? "once" : `at ${String(held.writes.length)} positions`;
+        const word = symbol.kind === "variable" ? "variable" : "member";
+        found.push(findingAbout(run, symbol, "DS1301", `${word} ${symbol.name} is written ${writes} and never read`, {
+            testOnly: held.production === 0 && held.test > 0,
+            configurations: matrix.heldIn[at] ?? [],
+            details: { 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 [[candidate, 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(([candidate, symbol]) => findingAbout(run, symbol, "DS1302", `enum member ${symbol.name} is named nowhere`, {
+        livenessRelation: candidate.relation,
+        testOnly: false,
+        configurations: candidate.configurations,
+        details: {},
+    }));
+}
+/**
+ * `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(([candidate, symbol]) => findingAbout(run, symbol, "DS1303", `type parameter ${symbol.name} is named in neither its signature nor its body`, {
+        livenessRelation: candidate.relation,
+        testOnly: false,
+        configurations: candidate.configurations,
+        details: {},
+    }));
+}
+/**
+ * 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));
+}
+/** Each code's rule, in code order. */
+const RULES = [
+    ["DS1301", writeOnlySymbols],
+    ["DS1302", unusedEnumMembers],
+    ["DS1303", unusedTypeParameters],
+];
+/**
+ * The findings of the reads-and-writes family, `DS1300` to `DS1399`, each code's in site
+ * order. A code the configuration sets to `allow` reports nothing, and a finding whose
+ * confidence is below the configured minimum is withheld.
+ */
+export const readsAndWrites = (input) => {
+    const run = indexed(input);
+    const least = RANK[input.config.analysis.minConfidence];
+    return RULES.flatMap(([code, rule]) => severityIn(input, code) === "allow"
+        ? []
+        : rule(run).filter((finding) => RANK[finding.confidence] >= least));
+};

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

@@ -1,2 +1,183 @@
+import { capped, findingComponents, reachabilityClasses, reportable, severityOf, } from "./completion.js";
+import { unreachableExports } from "./visibility-narrowing.js";
+/** The codes of the unused-declarations family, each by its row of the vocabulary. */
+export const UNUSED_DECLARATION_KINDS = new Map([
+    ["DS1001", { defaultSeverity: "deny", maxClass: "certain" }],
+    ["DS1002", { defaultSeverity: "deny", maxClass: "certain" }],
+    ["DS1003", { defaultSeverity: "deny", maxClass: "certain" }],
+    ["DS1004", { defaultSeverity: "deny", maxClass: "certain" }],
+    ["DS1005", { defaultSeverity: "deny", maxClass: "certain" }],
+    ["DS1006", { defaultSeverity: "deny", maxClass: "certain" }],
+]);
+/** 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`, completed and
+ * with what the dials withhold left out.
+ */
+export function unusedDeclarationFindings(input) {
+    const { config, swept } = input;
+    const union = swept.matrix.union;
+    const dead = new Set(swept.sweep.candidates.map((candidate) => candidate.id));
+    const classOf = reachabilityClasses(swept);
+    const componentOf = findingComponents(swept);
+    const unreachable = unreachableExports(input);
+    const found = [];
+    for (const candidate of 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);
+        const row = code === undefined ? undefined : UNUSED_DECLARATION_KINDS.get(code);
+        if (code === undefined || row === undefined) {
+            continue;
+        }
+        const component = componentOf(symbol.id);
+        if (component === undefined) {
+            throw new Error(`${symbol.id} is reported dead and falls in no dead component`);
+        }
+        const endLine = Math.max(symbol.position.line, symbol.endLine);
+        const reachabilityClass = classOf(symbol.id);
+        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),
+            reachabilityClass,
+            confidence: capped(reachabilityClass, row.maxClass),
+            livenessRelation: candidate.relation,
+            testOnly: candidate.productionRefs === 0 && candidate.testRefs > 0,
+            component,
+            configurations: candidate.configurations,
+            severity: severityOf(config, code, row.defaultSeverity),
+            details: {},
+        });
+    }
+    return reportable(found, config.analysis.minConfidence);
+}
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations = () => [];
+export const unusedDeclarations = unusedDeclarationFindings;