@cplieger/deadset-ts 2.3.0 → 3.1.0

package/dist/src/discover.js

@@ -1,5 +1,5 @@
 import { DiagnosticCategory } from "@typescript/native/unstable/sync";
-import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.js";
 /** Directory names discovery does not descend into. */
 const IGNORED_DIRECTORIES = new Set(["node_modules", ".git"]);
 /** A compiler configuration file discovery recognises under a root. */
@@ -128,24 +128,77 @@ function scopeConfigFiles(host, scope) {
         .map((path) => resolvePath(host.workingDirectory(), path));
 }
 /**
- * Every project one run analyzes, in the order discovery reads them: the paths the
- * scope names, then every compiler configuration under the target root that is not
- * inside an ignored directory, then the configurations each of those references,
- * transitively. Each configuration appears once.
- *
- * A configuration file the compiler cannot read ends the run with the failure code,
- * so a project that would have been analyzed with no type information is never
- * analyzed at all. What a configuration's own contents say is refused once its
- * project is open, by {@link diagnosticErrors} over the three sets a program
- * reports, because a resolution carries no diagnostics.
+ * The name a derived project carries: its configuration file's path below the target
+ * root, or the absolute path of a file outside it.
+ */
+function derivedId(targetRoot, configFile) {
+    return relativePath(targetRoot, configFile) ?? configFile;
+}
+/**
+ * Resolves one compiler configuration file, or ends the run naming it: a project
+ * opened from a configuration the compiler cannot read would be analyzed with no
+ * type information.
+ */
+function parseOrRefuse(engine, configFile, named) {
+    try {
+        engine.parseConfigFile(configFile);
+    }
+    catch (error) {
+        throw new DiscoveryError(`${named} cannot be read as a compiler configuration: ` +
+            (error instanceof Error ? error.message : String(error)), []);
+    }
+}
+/**
+ * The projects a build matrix declares, in the order it lists them. Each entry
+ * names a file below the target root, and an entry naming a file that is absent,
+ * that is a directory, or that the compiler cannot read ends the run naming it.
  *
- * Nothing reads a build output: a project is the files its configuration names, so a
- * package whose sources ship as TypeScript is analyzed as it stands.
+ * A declared project's `references` are not followed, because the entries are the
+ * matrix, and a reference to a configuration the matrix does not name ends the run
+ * naming both: the compiler builds a referenced project's sources into the program
+ * that references it without reporting their diagnostics, so the project the matrix
+ * left out would be analyzed with its errors unread. An entry naming a file an
+ * earlier entry named adds nothing, so the earlier identifier stands.
+ */
+function declaredProjects(engine, host, targetRoot, entries) {
+    const seen = new Set();
+    const projects = [];
+    for (const entry of entries) {
+        const configFile = joinPath(targetRoot, entry.project);
+        const named = `the project ${JSON.stringify(entry.id)} (${configFile})`;
+        const kind = host.kindOf(configFile);
+        if (kind !== "file") {
+            throw new DiscoveryError(kind === "absent"
+                ? `${named} does not exist`
+                : `${named} is a directory, and a project names its compiler configuration file`, []);
+        }
+        if (seen.has(configFile)) {
+            continue;
+        }
+        seen.add(configFile);
+        parseOrRefuse(engine, configFile, named);
+        projects.push({ id: entry.id, configFile });
+    }
+    for (const project of projects) {
+        const unnamed = referencesOf(host, project.configFile).find((path) => !seen.has(path));
+        if (unnamed !== undefined) {
+            throw new DiscoveryError(`the project ${JSON.stringify(project.id)} (${project.configFile}) references ` +
+                `${unnamed}, which the build matrix does not name; a referenced project is built ` +
+                "into the program that references it, so the matrix names it too", []);
+        }
+    }
+    return { projects, configFiles: projects.map((project) => project.configFile), fromScope: [] };
+}
+/**
+ * The projects a run derives where the matrix declares none, in the order discovery
+ * reads them: the paths the scope names, then every compiler configuration under
+ * the target root that is not inside an ignored directory, then the configurations
+ * each of those references, transitively. Each configuration appears once.
  */
-export function discoverProjects(engine, host, scope) {
+function derivedProjects(engine, host, scope) {
     const fromScope = scopeConfigFiles(host, scope);
     const seen = new Set();
-    const configFiles = [];
+    const projects = [];
     const pending = [...fromScope, ...configFilesUnder(host, scope.target.path)];
     while (pending.length > 0) {
         const configFile = pending.shift();
@@ -157,15 +210,36 @@ export function discoverProjects(engine, host, scope) {
             continue;
         }
         seen.add(path);
-        try {
-            engine.parseConfigFile(path);
-        }
-        catch (error) {
-            throw new DiscoveryError(`${path} cannot be read as a compiler configuration: ` +
-                (error instanceof Error ? error.message : String(error)), []);
-        }
-        configFiles.push(path);
+        parseOrRefuse(engine, path, path);
+        projects.push({ id: derivedId(scope.target.path, path), configFile: path });
         pending.push(...referencesOf(host, path));
     }
-    return { configFiles, fromScope };
+    return { projects, configFiles: projects.map((project) => project.configFile), fromScope };
+}
+/**
+ * Every project one run analyzes.
+ *
+ * The project entries of the build matrix, where it holds any, are the projects:
+ * exactly those, in the order the matrix lists them, each named by its declared
+ * identifier, as {@link declaredProjects} reads them. A matrix holding no project
+ * entry, the empty one included, leaves discovery to derive the projects from the
+ * scope and the target tree. A platform entry names a configuration of another
+ * language and plays no part here.
+ *
+ * A configuration file the compiler cannot read ends the run with the failure code,
+ * so a project that would have been analyzed with no type information is never
+ * analyzed at all, whether the matrix declared it or discovery derived it. What a
+ * configuration's own contents say is refused once its project is open, by
+ * {@link diagnosticErrors} over the three sets a program reports, because a
+ * resolution carries no diagnostics.
+ *
+ * Nothing reads a build output: a project is the files its configuration names, so a
+ * package whose sources ship as TypeScript is analyzed as it stands.
+ */
+export function discoverProjects(engine, host, scope, configurations = []) {
+    const declared = configurations.filter((entry) => entry.shape === "project");
+    if (declared.length > 0) {
+        return declaredProjects(engine, host, scope.target.path, declared);
+    }
+    return derivedProjects(engine, host, scope);
 }

package/dist/src/graph.js

@@ -0,0 +1,120 @@
+/**
+ * One project's declarations, the references between them and the roots that seed
+ * reachability, indexed for the sweep. The graph reads no file and asks the compiler
+ * nothing, so a sweep over it is a function of the values it was built from, and the
+ * inventory's order is the order every set a sweep answers reads in.
+ */
+/** The position of a declaration the inventory does not hold. */
+export const OUTSIDE = -1;
+/**
+ * Whether the sweep judges a declaration of each kind. A file is not judged by either
+ * relation: whether a file is built and whether anything imports it are the subjects of
+ * the file kinds, which read the program rather than ask whether anything references the
+ * file. The Contract's finding schema names the kinds that carry no liveness relation,
+ * and a test holds this table to that list.
+ */
+const SWEPT = {
+    file: false,
+    function: true,
+    class: true,
+    interface: true,
+    type: true,
+    enum: true,
+    namespace: true,
+    variable: true,
+    "export-alias": true,
+    method: true,
+    "class-member": true,
+    "interface-method": true,
+    "type-member": true,
+    "enum-member": true,
+    "type-parameter": true,
+};
+/**
+ * Whether a root of each kind names a caller, which holds it live under both relations: a
+ * tool reads the configuration it loads, a runtime runs a test file, a setup file and a
+ * worker, and a configured root asserts a caller. The other kinds only suppose a consumer
+ * that imports what a manifest entry, a binary or an entry file exports, or names a
+ * library's published API, so such a root is live under reachability alone.
+ */
+const NAMES_A_CALLER = {
+    "entry-file": false,
+    "manifest-entry": false,
+    "manifest-binary": false,
+    "published-api": false,
+    configured: true,
+    pattern: true,
+    "test-runner": true,
+    "lint-configuration": true,
+    "mutation-testing": true,
+    "browser-tests": true,
+    worker: true,
+};
+/** Whether the sweep judges a declaration of one kind. */
+export function swept(kind) {
+    return SWEPT[kind];
+}
+/** Whether a root of one kind names a caller rather than supposing one. */
+export function namesACaller(kind) {
+    return NAMES_A_CALLER[kind];
+}
+/**
+ * Indexes one project's inventory, references and roots. `testFiles` are the paths the
+ * reference pass classified as test files, so a declaration one holds is a test
+ * declaration. A reference to a declaration the inventory does not hold is dropped; one
+ * from such a declaration still counts toward its target, because reference counting
+ * asks whether any declaration names the target. A root naming nothing is dropped.
+ */
+export function graphOf(symbols, references, roots, testFiles) {
+    const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
+    const at = (id) => index.get(id) ?? OUTSIDE;
+    const tests = new Set(testFiles);
+    const out = symbols.map(() => []);
+    const made = symbols.map(() => ({ production: 0, test: 0 }));
+    for (const reference of references) {
+        const to = at(reference.to);
+        if (to === OUTSIDE) {
+            continue;
+        }
+        const counts = made[to];
+        if (counts !== undefined) {
+            if (reference.test) {
+                counts.test += 1;
+            }
+            else {
+                counts.production += 1;
+            }
+        }
+        out[at(reference.from)]?.push({
+            to,
+            test: reference.test,
+            evaluation: reference.use === "evaluation",
+        });
+    }
+    const parent = symbols.map((symbol) => at(symbol.parent));
+    const exportsOf = symbols.map(() => []);
+    symbols.forEach((symbol, position) => {
+        const container = parent[position] ?? OUTSIDE;
+        if (symbol.exported && symbols[container]?.kind === "file") {
+            exportsOf[container]?.push(position);
+        }
+    });
+    const rooted = [];
+    for (const root of roots) {
+        const position = at(root.id);
+        if (position !== OUTSIDE) {
+            rooted.push({ at: position, kind: root.kind });
+        }
+    }
+    return {
+        symbols,
+        out,
+        made,
+        parent,
+        test: symbols.map((symbol) => tests.has(symbol.position.path)),
+        subject: symbols.map((symbol) => swept(symbol.kind)),
+        exportsOf,
+        rooted,
+        at,
+    };
+}

package/dist/src/index.js

@@ -1,7 +1,5 @@
 export { run, SETTING_OPTIONS } from "./run.js";
 export { DECLINED_CONVENTIONS } from "./entry-point-gaps.js";
-export { inventory, nodeKey, } from "./inventory.js";
-export { DEFAULT_BATCH_CAP, references, } from "./references.js";
 export { byPosition, positionKey, PositionError, renderPosition, } from "./position.js";
 export { computedComponent, isRef, nameComponent, REF_EXPRESSIONS, renderRef, } from "./ref.js";
 export { CONTRACT_VERSION } from "./version.js";

package/dist/src/matrix.js

@@ -0,0 +1,138 @@
+/**
+ * One run's projects as one matrix: every declaration any project holds, keyed by its
+ * position and carrying the configurations that hold it, swept once per configuration
+ * and intersected, with the dead components computed once over every configuration.
+ */
+import { componentsOf } from "./components.js";
+import { graphOf } from "./graph.js";
+import { byPosition } from "./position.js";
+import { sweep } from "./sweep.js";
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** What makes one reference one reference, whichever configuration made it. */
+function referenceKey(reference) {
+    const { path, line, column } = reference.position;
+    return [reference.from, reference.to, path, String(line), String(column), reference.use].join("\u0000");
+}
+/**
+ * Indexes what the passes answered for each configuration of one run, in the run's order.
+ *
+ * A declaration is keyed across configurations by its identifier, which is its rendered
+ * position and so is the same in every configuration that compiles its file; the fields
+ * of the first configuration that holds it are the ones kept. A declaration one
+ * configuration alone holds is in the union with that one configuration, so it is
+ * judged where it exists rather than skipped.
+ *
+ * One reference written at one position of a file several configurations compile is seen
+ * once per configuration and is one reference, so the union holds it once; two references
+ * one configuration makes at one position are two.
+ */
+export function matrixOf(per) {
+    const symbols = [];
+    const holders = new Map();
+    const references = [];
+    const firstSeen = new Map();
+    per.forEach((one, index) => {
+        for (const symbol of one.symbols) {
+            const held = holders.get(symbol.id);
+            if (held === undefined) {
+                holders.set(symbol.id, [one.configuration]);
+                symbols.push(symbol);
+            }
+            else if (!held.includes(one.configuration)) {
+                held.push(one.configuration);
+            }
+        }
+        for (const reference of one.references) {
+            const key = referenceKey(reference);
+            const seen = firstSeen.get(key);
+            if (seen === undefined) {
+                firstSeen.set(key, index);
+            }
+            else if (seen !== index) {
+                continue;
+            }
+            references.push(reference);
+        }
+    });
+    symbols.sort((a, b) => byPosition(a.position, b.position) || compare(a.ref, b.ref));
+    return {
+        configurations: per.map((one) => one.configuration),
+        graphs: per.map((one) => graphOf(one.symbols, one.references, one.roots, one.testFiles)),
+        union: graphOf(symbols, references, per.flatMap((one) => one.roots), [...new Set(per.flatMap((one) => one.testFiles))]),
+        heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
+    };
+}
+/**
+ * Answers which declarations of the run are dead in every configuration that holds them.
+ *
+ * Liveness is a question about one configuration, because a file another configuration
+ * does not compile makes no reference there and a root it does not hold seeds nothing
+ * there, so each configuration is swept on its own graph under the run's input. A
+ * declaration is a candidate when every configuration holding it judged it one: a
+ * reference under one configuration is a reference, so what one project uses is never
+ * reported, and a configuration that does not hold a declaration says nothing about it.
+ * The candidate's relation is reference counting where every configuration found it so,
+ * and reachability otherwise; its counts are the union's, one per reference.
+ *
+ * The components are computed once, over the union and the intersected dead set, so one
+ * dead component is one entry of the run with one identifier.
+ */
+export function sweepMatrix(matrix, input) {
+    const per = matrix.graphs.map((graph) => sweep(graph, input));
+    const byConfiguration = new Map(matrix.configurations.map((configuration, index) => [
+        configuration,
+        new Map((per[index]?.candidates ?? []).map((candidate) => [candidate.id, candidate])),
+    ]));
+    const union = matrix.union;
+    const dead = union.symbols.map(() => false);
+    const testOfDeadCode = union.symbols.map(() => false);
+    const candidates = [];
+    union.symbols.forEach((symbol, at) => {
+        const held = matrix.heldIn[at] ?? [];
+        const found = held.map((configuration) => byConfiguration.get(configuration)?.get(symbol.id));
+        if (held.length === 0 || found.some((candidate) => candidate === undefined)) {
+            return;
+        }
+        const all = found.filter((candidate) => candidate !== undefined);
+        const admitted = all.every((candidate) => candidate.testOfDeadCode);
+        dead[at] = true;
+        testOfDeadCode[at] = admitted;
+        candidates.push({
+            id: symbol.id,
+            productionRefs: union.made[at]?.production ?? 0,
+            testRefs: union.made[at]?.test ?? 0,
+            relation: all.every((candidate) => candidate.relation === "reference-counting")
+                ? "reference-counting"
+                : "reachability",
+            testOfDeadCode: admitted,
+            configurations: held,
+        });
+    });
+    return {
+        liveUnder: liveAnywhere(union.symbols, per),
+        candidates,
+        components: componentsOf(union, dead, testOfDeadCode),
+    };
+}
+/** The relations in the order a declaration's entry lists them. */
+const RELATIONS = ["reference-counting", "reachability"];
+/**
+ * Per declaration, in site order, every relation that holds it live in at least one
+ * configuration.
+ */
+function liveAnywhere(symbols, per) {
+    const live = new Map();
+    for (const symbol of symbols) {
+        const relations = RELATIONS.filter((relation) => per.some((liveness) => (liveness.liveUnder.get(symbol.id) ?? []).includes(relation)));
+        if (relations.length > 0) {
+            live.set(symbol.id, relations);
+        }
+    }
+    return live;
+}

package/dist/src/print.js

@@ -19,12 +19,9 @@ export function printConfig(config, provenance) {
             min_confidence: config.analysis.minConfidence,
             generated_files: config.analysis.generatedFiles,
             consumer_tests: config.analysis.consumerTests,
-            configurations: config.analysis.configurations.map((entry) => ({
-                id: entry.id,
-                os: entry.os,
-                arch: entry.arch,
-                tags: entry.tags,
-            })),
+            configurations: config.analysis.configurations.map((entry) => entry.shape === "project"
+                ? { id: entry.id, project: entry.project }
+                : { id: entry.id, os: entry.os, arch: entry.arch, tags: entry.tags }),
             matrix: { complete: config.analysis.matrixComplete },
             template_dirs: config.analysis.templateDirs,
             template_delimiters: {