@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.1

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

@@ -43,41 +43,25 @@ function fileNeverBuilt({ config, swept, files }) {
         .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, a loaded consumer's file included. An import is such a
- * reference, so an import from any file reaches what it names, whatever reaches the
- * importing file.
+ * The paths of the files a reference from a live declaration of another file reaches, a
+ * loaded consumer's file included, a root names, or a declared edge names a declaration in,
+ * and of every file a reference written anywhere reaches. 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. A
+ * reference from a file's top level counts once the file is kept.
  */
-function reachedFromOutside(union) {
-    const reached = new Set();
+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(files.heldByInclusion);
+    const referenced = new Set();
     for (const edge of union.consumed) {
         const to = union.symbols[edge.to];
         if (to !== undefined) {
-            reached.add(to.position.path);
+            kept.add(to.position.path);
         }
     }
-    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) {
@@ -89,14 +73,63 @@ function keptFiles({ swept, files, boundary }) {
             kept.add(symbol.position.path);
         }
     }
-    return kept;
+    const fromTopLevel = new Map();
+    const pending = [];
+    const keep = (path) => {
+        if (!kept.has(path)) {
+            kept.add(path);
+            pending.push(path);
+        }
+    };
+    union.out.forEach((edges, from) => {
+        const source = union.symbols[from];
+        if (source === undefined) {
+            return;
+        }
+        for (const edge of edges) {
+            const to = union.symbols[edge.to]?.position.path;
+            if (to === undefined || to === source.position.path) {
+                continue;
+            }
+            referenced.add(to);
+            if (source.kind === FILE_SUBJECT) {
+                fromTopLevel.set(source.position.path, [
+                    ...(fromTopLevel.get(source.position.path) ?? []),
+                    to,
+                ]);
+            }
+            else if (!dead.has(source.id)) {
+                pending.push(to);
+            }
+        }
+    });
+    pending.push(...kept);
+    for (let path = pending.pop(); path !== undefined; path = pending.pop()) {
+        kept.add(path);
+        for (const to of fromTopLevel.get(path) ?? []) {
+            keep(to);
+        }
+        fromTopLevel.delete(path);
+    }
+    return { kept, referenced };
 }
-/** Every file of the run that no import reaches and no root or edge names. */
+/**
+ * Every file of the run that no reference from live code reaches and no root or edge
+ * names. A file only dead code imports is found dead under reachability alone.
+ */
 function fileNeverImported(input) {
-    const kept = keptFiles(input);
+    const { kept, referenced } = 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"));
+        .map((symbol) => {
+        const file = { path: symbol.position.path, ref: symbol.ref, endLine: symbol.endLine };
+        return referenced.has(symbol.position.path)
+            ? {
+                ...fileFinding(FILE_NEVER_IMPORTED, file, "only code that is itself dead imports this file, and no root names it or a declaration in it"),
+                unreachableOnly: true,
+            }
+            : fileFinding(FILE_NEVER_IMPORTED, file, "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 = (input) => [

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

@@ -162,7 +162,27 @@ function brandMembers(input) {
 /** The kinds of member a brand is: a data member of a type or of a class. */
 const BRANDS = new Set(["type-member", "class-member"]);
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations = (input) => familyFindings(input, false);
+export const unusedDeclarations = (input) => [
+    ...familyFindings(input, false),
+    ...unusedImports(input),
+];
+/**
+ * The import bindings their file never reads, under the unexported code. A generated
+ * file's are the generator's to remove unless the run includes generated files.
+ */
+function unusedImports(input) {
+    const generated = input.config.analysis.generatedFiles === "include" ? undefined : input.files.generated;
+    return input.intraFunction.imports.flatMap((binding) => binding.used || generated?.has(binding.position.path) === true
+        ? []
+        : [
+            {
+                code: "DS1002",
+                position: binding.position,
+                symbol: { ref: binding.ref, kind: "import", name: binding.name, sizeLines: 1 },
+                message: `import binding ${binding.name} is never read in its file`,
+            },
+        ]);
+}
 /**
  * The finding each member of a dead container would carry were its container live: what
  * a record on such a member is matched against, since the report carries the container's

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

@@ -1,5 +1,6 @@
 import { OUTSIDE } from "../graph.js";
 import { declarationKey } from "../ref.js";
+import { runnerCalls } from "../sweep.js";
 import { writeOnlyDeclarations } from "./reads-and-writes.js";
 const UNNECESSARY_EXPORT = "DS1101";
 const UNREACHABLE_EXPORT = "DS1103";
@@ -24,8 +25,22 @@ const WORDS = {
 function publishes(kinds) {
     return [...(kinds ?? [])].some((kind) => PUBLISHING.has(kind));
 }
+/**
+ * The root kinds that name a file without entering it by its exports: a configuration
+ * string or a script token runs the file, and no tool reads a name it exports.
+ */
+const RUN_ONLY = new Set(["configuration-string", "script"]);
+/** Whether a root makes its file an entry file, or its declaration an entry, which a tool may read by name. */
 function entersByName(kinds) {
-    return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind));
+    return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind) && !RUN_ONLY.has(kind));
+}
+/**
+ * Whether the roots of a declaration's file enter it by name: a test runner's root
+ * enters only an export the runner calls, so another export of a test file is judged.
+ */
+function fileEntersByName(kinds, symbol) {
+    const entering = [...(kinds ?? [])].filter((kind) => !PUBLISHING.has(kind) && !RUN_ONLY.has(kind));
+    return (entering.some((kind) => kind !== "test-runner") || (entering.length > 0 && runnerCalls(symbol)));
 }
 /**
  * Folds the run's references into the reach of each declaration.
@@ -123,7 +138,7 @@ function narrowing(facts, at, symbol, world) {
         world.writeOnly.has(declarationKey(symbol.ref, symbol.position.path)) ||
         symbol.kind === "export-alias" ||
         entersByName(facts.rootedBy[at]) ||
-        entersByName(facts.rootedBy[file]) ||
+        fileEntersByName(facts.rootedBy[file], symbol) ||
         (facts.named[at] ?? 0) === 0) {
         return undefined;
     }
@@ -185,7 +200,11 @@ export function narrowings(input) {
             return;
         }
         const candidate = candidates.get(symbol.id);
-        const found = candidate === undefined
+        // A declaration of test code, a test file's or test-support code's, that only test code
+        // references is a candidate, live in the run that counts test references.
+        const live = candidate === undefined ||
+            (facts.graph.test[at] === true && !candidate.unreferencedTest && !candidate.testOfDeadCode);
+        const found = candidate === undefined || live
             ? narrowing(facts, at, symbol, world)
             : unreachable(facts, at, symbol, candidate, input);
         if (found !== undefined) {

package/dist/src/generated-file.js

@@ -8,6 +8,12 @@
 const HEADER_LINE = /^\/\/ Code generated .* DO NOT EDIT\.$/u;
 /** The documentation tag `@generated` as a word of a comment. */
 const GENERATED_TAG = /(?<![\w@$])@generated(?![\w$-])/u;
+/** A first comment naming the tool that wrote the file. */
+const GENERATED_BY = /^\/\/ Generated by \S/u;
+/** The word a generator's notice holds, beside one of {@link KEEP_OUT}. */
+const GENERATED_WORD = /\bgenerated\b/iu;
+/** The phrases a generator's notice asks a reader not to edit the file by. */
+const KEEP_OUT = /\b(?:do not edit|will be overwritten|should not make any changes)\b/iu;
 /** The comments before a text's first token, a leading hashbang line skipped. */
 function leadingComments(text) {
     const comments = [];
@@ -48,6 +54,11 @@ export function generatedByComment(text) {
     if (comments.some((one) => GENERATED_TAG.test(one))) {
         return "generated by the @generated tag its leading comments hold";
     }
+    const notice = comments.join("\n");
+    if (GENERATED_BY.test(comments[0] ?? "") ||
+        (GENERATED_WORD.test(notice) && KEEP_OUT.test(notice))) {
+        return "generated by the notice its leading comments hold";
+    }
     return undefined;
 }
 /**

package/dist/src/git-ignore.js

@@ -0,0 +1,86 @@
+/**
+ * Which files the `.gitignore` files of a tree ignore, read as git reads them:
+ * https://git-scm.com/docs/gitignore#_pattern_format
+ */
+import { globExpression } from "./glob.js";
+import { dirnamePath, joinPath, relativePath } from "./paths.js";
+/** The rules one `.gitignore` text writes, in order. */
+function rulesOf(text) {
+    const rules = [];
+    for (const raw of text.split(/\r?\n/u)) {
+        let line = raw.replace(/(?<!\\)\s+$/u, "");
+        if (line === "" || line.startsWith("#")) {
+            continue;
+        }
+        const negated = line.startsWith("!");
+        line = negated || line.startsWith("\\") ? line.slice(1) : line;
+        const directoryOnly = line.endsWith("/");
+        line = line.replace(/\/+$/u, "");
+        if (line === "") {
+            continue;
+        }
+        // A separator at the start or in the middle anchors the pattern to the file's
+        // directory; with none, the pattern matches at any depth below it.
+        const anchored = line.includes("/");
+        const pattern = line.replace(/^\//u, "");
+        rules.push({
+            negated,
+            directoryOnly,
+            expression: globExpression(anchored ? pattern : `**/${pattern}`),
+        });
+    }
+    return rules;
+}
+/**
+ * Whether the `.gitignore` files at and below `root` ignore one absolute path. A path
+ * outside `root` is not ignored, and a file below an ignored directory stays ignored
+ * whatever a later pattern says, as git cannot re-include it.
+ */
+export function gitIgnored(host, root) {
+    const read = new Map();
+    const rulesAt = (dir) => {
+        let rules = read.get(dir);
+        if (rules === undefined) {
+            try {
+                rules = rulesOf(host.readFile(joinPath(dir, ".gitignore")));
+            }
+            catch {
+                rules = [];
+            }
+            read.set(dir, rules);
+        }
+        return rules;
+    };
+    /** Whether the rules of `root` and of each directory down to one path's own decide it ignored. */
+    const decided = (path, directory) => {
+        const dirs = [];
+        for (let at = dirnamePath(path); relativePath(root, at) !== undefined; at = dirnamePath(at)) {
+            dirs.unshift(at);
+        }
+        dirs.unshift(root);
+        let ignored = false;
+        for (const dir of dirs) {
+            const below = relativePath(dir, path);
+            for (const rule of below === undefined ? [] : rulesAt(dir)) {
+                if ((directory || !rule.directoryOnly) && rule.expression.test(below ?? "")) {
+                    ignored = !rule.negated;
+                }
+            }
+        }
+        return ignored;
+    };
+    return (path) => {
+        const below = relativePath(root, path);
+        if (below === undefined) {
+            return false;
+        }
+        const parts = below.split("/");
+        for (let count = 1; count <= parts.length; count += 1) {
+            const at = joinPath(root, parts.slice(0, count).join("/"));
+            if (decided(at, count < parts.length)) {
+                return true;
+            }
+        }
+        return false;
+    };
+}

package/dist/src/graph.js

@@ -56,6 +56,8 @@ const NAMES_A_CALLER = {
     worker: true,
     "html-entry": true,
     "workflow-step": true,
+    "computed-import": true,
+    "document-import": true,
 };
 /** Whether the sweep judges a declaration of one kind. */
 export function swept(kind) {
@@ -72,7 +74,7 @@ export function namesACaller(kind) {
  * 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, supportFiles = []) {
+export function graphOf(symbols, references, roots, testFiles, supportFiles = [], ambient = new Set()) {
     const supports = new Set(supportFiles);
     const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
     const at = (id) => index.get(id) ?? OUTSIDE;
@@ -123,6 +125,7 @@ export function graphOf(symbols, references, roots, testFiles, supportFiles = []
         parent,
         test: symbols.map((symbol) => tests.has(symbol.position.path)),
         support: symbols.map((symbol) => supports.has(symbol.position.path)),
+        ambient: symbols.map((symbol) => ambient.has(symbol.id)),
         subject: symbols.map((symbol) => swept(symbol.kind)),
         exportsOf,
         rooted,

package/dist/src/import-bindings.js

@@ -0,0 +1,97 @@
+/**
+ * The import bindings of one file: the names its import declarations bind, which only
+ * the file itself can read.
+ */
+import { isExportSpecifier, isExternalModuleReference, isIdentifier, isImportDeclaration, isImportEqualsDeclaration, isJsxElement, isJsxFragment, isJsxSelfClosingElement, isNamespaceImport, SyntaxKind, } from "@typescript/native/ast";
+/** The extensions of the files whose import bindings are judged: no markup can read them. */
+const JUDGED = /\.(?:[mc]?ts|tsx|[mc]?js|jsx)$/u;
+/** The compiler's `jsx` settings whose emit calls no factory the file must hold. */
+const AUTOMATIC_RUNTIME = new Set([4, 5, "react-jsx", "react-jsxdev"]);
+/** A doc comment, where a JavaScript file names the types it imports. */
+const DOC_COMMENT = /\/\*\*[\s\S]*?\*\//gu;
+/** The parts of a doc comment the compiler resolves names in: a `{…}` type or link, a `@see` target. */
+const DOC_REFERENCE = /\{[^{}]*\}|@see\s+[A-Za-z_$][\w$.]*/gu;
+/** The factory a pragma comment names: `@jsx h` or `@jsxFrag Fragment`. */
+const PRAGMA = /@jsx(?:Frag)?\s+([A-Za-z_$][\w$]*)/gu;
+/**
+ * The names one file's import declarations bind: the default, named and namespace names of
+ * an `import` declaration, and the name of an `import x = require()` declaration that is
+ * not exported. None is judged in a declaration file or a component file.
+ */
+export function importBindings(file) {
+    if (file.isDeclarationFile || !JUDGED.test(file.fileName)) {
+        return [];
+    }
+    const found = [];
+    for (const statement of file.statements) {
+        if (isImportDeclaration(statement)) {
+            const clause = statement.importClause;
+            if (clause?.name !== undefined) {
+                found.push(clause.name);
+            }
+            const named = clause?.namedBindings;
+            if (named !== undefined && isNamespaceImport(named)) {
+                found.push(named.name);
+            }
+            else if (named !== undefined) {
+                for (const element of named.elements) {
+                    found.push(element.name);
+                }
+            }
+        }
+        else if (isImportEqualsDeclaration(statement) &&
+            isExternalModuleReference(statement.moduleReference) &&
+            isIdentifier(statement.name) &&
+            !(statement.modifiers ?? []).some((modifier) => modifier.kind === SyntaxKind.ExportKeyword)) {
+            found.push(statement.name);
+        }
+    }
+    return found;
+}
+/** Whether one identifier names a binding in a local export, which reads it whatever it resolves to. */
+export function exportsLocally(use) {
+    return isExportSpecifier(use.parent);
+}
+/**
+ * The names a file reads without an identifier the program resolves: each name a type, a
+ * link or a `@see` tag of its doc comments spells, and, where it writes JSX the compiler
+ * turns into factory calls, the factories the configuration or a pragma names.
+ */
+export function implicitReads(file, options) {
+    const names = new Set();
+    for (const comment of file.text.match(DOC_COMMENT) ?? []) {
+        for (const reference of comment.match(DOC_REFERENCE) ?? []) {
+            for (const word of reference.match(/[A-Za-z_$][\w$]*/gu) ?? []) {
+                names.add(word);
+            }
+        }
+    }
+    if (AUTOMATIC_RUNTIME.has(options.jsx) || !writesJsx(file)) {
+        return names;
+    }
+    for (const factory of [options.jsxFactory, options.jsxFragmentFactory]) {
+        names.add(typeof factory === "string" ? (factory.split(".")[0] ?? factory) : "React");
+    }
+    for (const match of file.text.matchAll(PRAGMA)) {
+        if (match[1] !== undefined) {
+            names.add(match[1]);
+        }
+    }
+    return names;
+}
+/** Whether a file holds a JSX element or fragment. */
+function writesJsx(file) {
+    let found = false;
+    const visit = (node) => {
+        if (found) {
+            return;
+        }
+        if (isJsxElement(node) || isJsxSelfClosingElement(node) || isJsxFragment(node)) {
+            found = true;
+            return;
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}