@cplieger/deadset-ts 2.2.0 → 2.3.0

package/dist/src/entry-points.js

@@ -0,0 +1,385 @@
+/**
+ * The files a tool or the platform enters without any import naming them: the
+ * configuration files the test runner, the linter, the mutation tester and the
+ * browser-test runner load by their file name, the test files the runner executes,
+ * and a worker a call addresses by a string literal.
+ *
+ * Each rule is read from the program and nothing else: a file name the tool
+ * itself looks for, a literal written in a configuration file, or a literal
+ * argument of a call the checker resolves to the platform's own declaration. A
+ * value that is not a literal is not evaluated and not guessed, so a file it would
+ * have named is entered by nothing here.
+ */
+import { isArrayLiteralExpression, isAsExpression, isCallExpression, isExportAssignment, isIdentifier, isMetaProperty, isNewExpression, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isSatisfiesExpression, isStringLiteral, } from "@typescript/native/unstable/ast";
+import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { globExpression } from "./glob.js";
+import { dirnamePath, relativePath, resolvePath } from "./paths.js";
+/** The extensions the test runner and the browser-test runner load a configuration from. */
+const MODULE_EXTENSIONS = ["js", "mjs", "cjs", "ts", "mts", "cts"];
+/** The extensions the linter's flat configuration and the mutation tester's are loaded from. */
+const SCRIPT_EXTENSIONS = ["js", "mjs", "cjs"];
+const CONVENTIONS = [
+    {
+        rule: "test-runner",
+        stems: ["vitest.config", "vitest.workspace", "vitest.projects"],
+        extensions: MODULE_EXTENSIONS,
+        testRunner: true,
+    },
+    {
+        rule: "lint-configuration",
+        stems: ["eslint.config"],
+        extensions: MODULE_EXTENSIONS,
+        testRunner: false,
+    },
+    {
+        rule: "mutation-testing",
+        stems: ["stryker.config", "stryker.conf", ".stryker.config", ".stryker.conf"],
+        extensions: SCRIPT_EXTENSIONS,
+        testRunner: false,
+    },
+    {
+        rule: "mutation-testing",
+        stems: ["vitest.stryker.config"],
+        extensions: MODULE_EXTENSIONS,
+        testRunner: true,
+    },
+    {
+        rule: "browser-tests",
+        stems: ["playwright.config"],
+        extensions: MODULE_EXTENSIONS,
+        testRunner: false,
+    },
+];
+/** The browser-test runner's own test-file pattern, which holds where a configuration names none. */
+const BROWSER_TEST_MATCH = "**/*.{spec,test}.{js,ts,jsx,tsx,cjs,cts,cjsx,ctsx,mjs,mts,mjsx,mtsx}";
+/** The members of a test-runner configuration's `test` object that name setup files. */
+const SETUP_MEMBERS = ["setupFiles", "globalSetup"];
+/** A member that moves the directory every path of a test-runner configuration is read from. */
+const ROOT_MEMBER = "root";
+/** The prefixes a literal is relative with, in a module specifier and a URL reference alike. */
+const RELATIVE_PREFIXES = ["./", "../"];
+/** The constructors whose first argument addresses a worker script. */
+const WORKER_CONSTRUCTORS = new Set(["Worker", "SharedWorker"]);
+/** The file's name, the last segment of its path. */
+function basename(path) {
+    return path.slice(path.lastIndexOf("/") + 1);
+}
+/** The convention one file name is, with the spelling a root reports it by. */
+function conventionOf(name) {
+    for (const convention of CONVENTIONS) {
+        for (const stem of convention.stems) {
+            if (convention.extensions.some((ext) => name === `${stem}.${ext}`)) {
+                return { convention, spelled: `${stem}.*` };
+            }
+        }
+    }
+    return undefined;
+}
+/** The text a string literal or a template with no substitution denotes. */
+function literalOf(node) {
+    if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+        return node.text;
+    }
+    return undefined;
+}
+/** The expression a wrapper that changes no value holds: parentheses and type assertions. */
+function unwrapped(node) {
+    let at = node;
+    while (isParenthesizedExpression(at) || isAsExpression(at) || isSatisfiesExpression(at)) {
+        at = at.expression;
+    }
+    return at;
+}
+/**
+ * The object literals one configuration file's default export is written as: the
+ * literal itself, or each literal argument of the call it is, at any depth of calls.
+ * A default export written as anything else, a name or a computation, yields none,
+ * because its value is not in the file's text.
+ */
+function configObjects(file) {
+    const found = [];
+    const collect = (node) => {
+        const at = unwrapped(node);
+        if (isObjectLiteralExpression(at)) {
+            found.push(at);
+            return;
+        }
+        if (isCallExpression(at)) {
+            for (const argument of at.arguments) {
+                collect(argument);
+            }
+        }
+    };
+    for (const statement of file.statements) {
+        if (isExportAssignment(statement) && !statement.isExportEquals) {
+            collect(statement.expression);
+        }
+    }
+    return found;
+}
+/**
+ * The value one member of an object literal is written with, when it is written as
+ * `name: value`, and undefined where the literal writes no such member.
+ */
+function memberOf(object, name) {
+    if (!isObjectLiteralExpression(object)) {
+        return undefined;
+    }
+    for (const property of object.properties) {
+        if (isPropertyAssignment(property) &&
+            isIdentifier(property.name) &&
+            property.name.text === name) {
+            return property.initializer;
+        }
+    }
+    return undefined;
+}
+/**
+ * The strings one member holds, when it is written as a literal or an array of
+ * literals. `undefined` is a value the text does not state.
+ */
+function literalsOf(value) {
+    const at = unwrapped(value);
+    const single = literalOf(at);
+    if (single !== undefined) {
+        return [single];
+    }
+    if (!isArrayLiteralExpression(at)) {
+        return undefined;
+    }
+    const found = [];
+    for (const element of at.elements) {
+        const text = literalOf(unwrapped(element));
+        if (text === undefined) {
+            return undefined;
+        }
+        found.push(text);
+    }
+    return found;
+}
+/** Whether a literal is relative in the sense a module specifier and a URL reference share. */
+function isRelative(text) {
+    return RELATIVE_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+/** A URL reference with its query and its fragment removed, which name no part of the file. */
+function pathPart(text) {
+    const cut = text.search(/[?#]/u);
+    return cut < 0 ? text : text.slice(0, cut);
+}
+/** The own files one relative literal names, read against a directory. */
+function filesNamed(files, dir, text) {
+    if (!isRelative(text)) {
+        return [];
+    }
+    return files.named(resolvePath(dir, pathPart(text)));
+}
+/**
+ * The setup files one test-runner configuration names: every literal under
+ * `test.setupFiles` and `test.globalSetup`, read against the configuration's own
+ * directory. A configuration that moves its root names them against a directory its
+ * text may not state, so none is read from it.
+ */
+function setupFilesOf(file, files) {
+    const objects = configObjects(file);
+    const tests = objects
+        .map((object) => memberOf(object, "test"))
+        .filter((value) => value !== undefined)
+        .map(unwrapped);
+    if ([...objects, ...tests].some((object) => memberOf(object, ROOT_MEMBER) !== undefined)) {
+        return [];
+    }
+    const dir = dirnamePath(file.fileName);
+    const found = [];
+    for (const test of tests) {
+        for (const name of SETUP_MEMBERS) {
+            const value = memberOf(test, name);
+            for (const text of value === undefined ? [] : (literalsOf(value) ?? [])) {
+                for (const named of filesNamed(files, dir, text)) {
+                    found.push({ file: named, rule: "test-runner", source: text, exports: false });
+                }
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The test files one browser-test configuration names: every own file below its
+ * test directory that its test-file pattern matches. The directory is the literal
+ * `testDir` reads against the configuration's directory, or that directory where no
+ * object of the configuration writes one; the pattern is the literal `testMatch`, or
+ * the runner's own where none is written. A member whose value is not a literal
+ * leaves the set unknown, and an unknown set enters nothing.
+ */
+function browserTestsOf(file, files) {
+    const objects = configObjects(file);
+    if (objects.length === 0) {
+        return [];
+    }
+    let testDir = ".";
+    let patterns = [BROWSER_TEST_MATCH];
+    for (const object of objects) {
+        const dir = memberOf(object, "testDir");
+        if (dir !== undefined) {
+            testDir = literalOf(unwrapped(dir));
+        }
+        const match = memberOf(object, "testMatch");
+        if (match !== undefined) {
+            patterns = literalsOf(match);
+        }
+    }
+    if (testDir === undefined || patterns === undefined) {
+        return [];
+    }
+    const under = resolvePath(dirnamePath(file.fileName), testDir);
+    const found = [];
+    for (const pattern of patterns) {
+        const expression = globExpression(pattern);
+        for (const candidate of files.byName.values()) {
+            const below = relativePath(under, candidate.fileName);
+            if (below !== undefined && expression.test(below)) {
+                found.push({ file: candidate, rule: "browser-tests", source: pattern, exports: false });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * The address one worker argument writes: a relative literal, or a `URL` built from
+ * a literal against `import.meta.url`. Any other argument is computed and addresses
+ * nothing the text states.
+ */
+function workerAddress(argument) {
+    if (argument === undefined) {
+        return undefined;
+    }
+    const at = unwrapped(argument);
+    const literal = literalOf(at);
+    if (literal !== undefined) {
+        return { literal, names: [] };
+    }
+    if (!isNewExpression(at) || !isIdentifier(at.expression) || at.expression.text !== "URL") {
+        return undefined;
+    }
+    const [reference, base] = at.arguments ?? [];
+    const text = literalOf(reference === undefined ? undefined : unwrapped(reference));
+    if (text === undefined || base === undefined) {
+        return undefined;
+    }
+    const meta = unwrapped(base);
+    if (!isPropertyAccessExpression(meta) ||
+        !isMetaProperty(meta.expression) ||
+        !isIdentifier(meta.name) ||
+        meta.name.text !== "url") {
+        return undefined;
+    }
+    return { literal: text, names: [at.expression] };
+}
+/**
+ * Every call one file writes that addresses a worker: `new Worker(...)`,
+ * `new SharedWorker(...)` and `navigator.serviceWorker.register(...)`, each with an
+ * address its text states.
+ */
+function workerSitesOf(file) {
+    const found = [];
+    const visit = (node) => {
+        if (isNewExpression(node) &&
+            isIdentifier(node.expression) &&
+            WORKER_CONSTRUCTORS.has(node.expression.text)) {
+            const address = workerAddress(node.arguments?.[0]);
+            if (address !== undefined) {
+                found.push({
+                    literal: address.literal,
+                    platformNames: [node.expression, ...address.names],
+                });
+            }
+        }
+        if (isCallExpression(node)) {
+            const callee = node.expression;
+            if (isPropertyAccessExpression(callee) &&
+                isIdentifier(callee.name) &&
+                callee.name.text === "register" &&
+                isPropertyAccessExpression(callee.expression) &&
+                isIdentifier(callee.expression.name) &&
+                callee.expression.name.text === "serviceWorker" &&
+                isIdentifier(callee.expression.expression) &&
+                callee.expression.expression.text === "navigator") {
+                const address = workerAddress(node.arguments[0]);
+                if (address !== undefined) {
+                    found.push({
+                        literal: address.literal,
+                        platformNames: [callee.expression.expression, ...address.names],
+                    });
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * The workers one file addresses. A call's names must resolve to the platform's own
+ * declarations, which no file of the target declares and no import brings in; a
+ * name the target binds itself is the target's own constructor or object, which
+ * addresses no worker this rule knows. One batch per file that writes such a call.
+ */
+function workersOf(project, file, files) {
+    const sites = workerSitesOf(file);
+    if (sites.length === 0) {
+        return [];
+    }
+    const names = sites.flatMap((site) => site.platformNames);
+    const symbols = project.symbolsAt(names.map((name) => project.handle(name)));
+    const platform = new Set();
+    names.forEach((name, index) => {
+        const symbol = symbols[index];
+        if (symbol !== undefined &&
+            (symbol.flags & SymbolFlags.Alias) === 0 &&
+            symbol.declarations.length > 0 &&
+            symbol.declarations.every((handle) => !files.byName.has(handle.path))) {
+            platform.add(name);
+        }
+    });
+    const dir = dirnamePath(file.fileName);
+    const found = [];
+    for (const site of sites) {
+        if (!site.platformNames.every((name) => platform.has(name))) {
+            continue;
+        }
+        for (const named of filesNamed(files, dir, site.literal)) {
+            found.push({ file: named, rule: "worker", source: site.literal, exports: false });
+        }
+    }
+    return found;
+}
+/**
+ * Every file of one project the lifted rules enter, in no particular order and
+ * possibly more than once: a file two rules enter appears once per rule.
+ *
+ * `testFiles` is the configuration's test-file patterns, matched against each
+ * file's path below the target root; a file one of them matches is a test file the
+ * runner executes.
+ */
+export function entryPoints(project, files, testFiles) {
+    const found = [];
+    const tests = testFiles.map((pattern) => ({ pattern, expression: globExpression(pattern) }));
+    for (const [path, file] of files.byPath) {
+        const named = conventionOf(basename(path));
+        if (named !== undefined) {
+            found.push({ file, rule: named.convention.rule, source: named.spelled, exports: true });
+            if (named.convention.testRunner) {
+                found.push(...setupFilesOf(file, files));
+            }
+            if (named.convention.rule === "browser-tests") {
+                found.push(...browserTestsOf(file, files));
+            }
+        }
+        for (const { pattern, expression } of tests) {
+            if (expression.test(path)) {
+                found.push({ file, rule: "test-runner", source: pattern, exports: false });
+            }
+        }
+        found.push(...workersOf(project, file, files));
+    }
+    return found;
+}

package/dist/src/finding.js

@@ -0,0 +1,12 @@
+/**
+ * The members of a finding its emitter decides: the code, where the subject is,
+ * what the subject is, and the sentence the finding reports. They are the
+ * Contract's finding members of the same names, spelled in this language's case.
+ *
+ * Every other member the finding schema requires follows from these and from the
+ * run: the kind's name, its fixability and its ceiling come from the code's row of
+ * the issue-kind vocabulary, the severity and the confidence from the resolved
+ * configuration, the language from the analyzer. A report completes them, so an
+ * emitter cannot state one that disagrees with the vocabulary.
+ */
+export {};

package/dist/src/glob.js

@@ -0,0 +1,65 @@
+/**
+ * Glob patterns over the paths of the target's own files, as the configuration
+ * writes them. Both `ts.test_files` and `ts.entry_files` name files this way, and
+ * one grammar answers for both.
+ *
+ * A configured root is not written in this grammar. It names a symbol reference
+ * rather than a path, `*` there spans the solidus and a brace list means nothing,
+ * so that rule is written where it is read.
+ */
+/**
+ * One literal run of a pattern, with every character the expression syntax claims
+ * escaped.
+ *
+ * The set is the syntax characters and the solidus, and it is closed: an escape of any
+ * other character is refused outright by the expression syntax under the unicode flag,
+ * so escaping a hyphen, which needs none outside a character class, would refuse every
+ * pattern that names a hyphenated path.
+ */
+function quoted(text) {
+    return text.replaceAll(/[.*+?^${}()|[\]\\/]/gu, (character) => `\\${character}`);
+}
+/**
+ * The expression one glob pattern denotes. `**` spans path separators while `*` and `?`
+ * do not, a brace list is an alternation of its members, and every other character
+ * stands for itself.
+ */
+export function globExpression(pattern) {
+    let source = "^";
+    let at = 0;
+    while (at < pattern.length) {
+        const rest = pattern.slice(at);
+        if (rest.startsWith("**/")) {
+            source += "(?:[^/]*/)*";
+            at += 3;
+            continue;
+        }
+        if (rest.startsWith("**")) {
+            source += ".*";
+            at += 2;
+            continue;
+        }
+        const character = pattern[at] ?? "";
+        at += 1;
+        if (character === "*") {
+            source += "[^/]*";
+            continue;
+        }
+        if (character === "?") {
+            source += "[^/]";
+            continue;
+        }
+        if (character === "{") {
+            const close = pattern.indexOf("}", at);
+            if (close < 0) {
+                source += "\\{";
+                continue;
+            }
+            source += `(?:${pattern.slice(at, close).split(",").map(quoted).join("|")})`;
+            at = close + 1;
+            continue;
+        }
+        source += quoted(character);
+    }
+    return new RegExp(`${source}$`, "u");
+}

package/dist/src/index.js

@@ -1,4 +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";

package/dist/src/manifest.js

@@ -0,0 +1,120 @@
+/**
+ * The entry points a package manifest names, which are roots because something
+ * outside the analyzed program reaches them: a consumer importing the package, or a
+ * shell running its command.
+ *
+ * Only the target's own manifest is read. A manifest below the target root belongs
+ * to another package, whose entry points are that package's roots and not this
+ * target's.
+ */
+import { isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+/** The manifest's own name. */
+const MANIFEST = "package.json";
+/** The three members that name an entry point beside `exports` and `bin`. */
+const LEGACY_MEMBERS = ["main", "module", "types"];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether one member's value names a file of this package rather than another
+ * package or a URL. A target written with no leading dot is a path too, which is
+ * how the members that preceded `exports` are written.
+ */
+function isTarget(value, requireDot) {
+    if (value === "" || isAbsolutePath(value) || value.includes("://")) {
+        return false;
+    }
+    return !requireDot || value.startsWith("./");
+}
+/** One member's spelling below another: `exports` then `exports["."]`. */
+function below(member, key) {
+    return `${member}[${JSON.stringify(key)}]`;
+}
+/**
+ * Every target one `exports` value carries, at the member each is written under.
+ *
+ * The value is a string, an object whose keys are subpaths or conditions, or an
+ * array of alternatives, nested to any depth, and a `null` blocks a subpath rather
+ * than naming a target. Every level is walked because a condition names a different
+ * file of the same package and each is an entry point of its own; a key's meaning
+ * is not read, because a subpath and a condition both lead to a target and the
+ * walk needs no more than that.
+ */
+function exportTargets(value, member, found) {
+    if (typeof value === "string") {
+        if (isTarget(value, true)) {
+            found.push({ member, path: value, role: "import", published: true });
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((alternative, index) => {
+            exportTargets(alternative, below(member, String(index)), found);
+        });
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    for (const [key, held] of Object.entries(value)) {
+        exportTargets(held, below(member, key), found);
+    }
+}
+/** The manifest at the target root, decoded, or undefined where there is none to read. */
+function manifestOf(host, targetRoot) {
+    let text;
+    try {
+        text = host.readFile(joinPath(targetRoot, MANIFEST));
+    }
+    catch {
+        return undefined;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        // A manifest this program cannot read names no entry point, which is the same
+        // answer as an absent one. What a manifest's contents say is not refused here:
+        // the package manager owns that refusal, and an analysis of a tree it rejects
+        // is not the run's subject.
+        return undefined;
+    }
+    return isRecord(value) ? value : undefined;
+}
+/**
+ * What the target's own manifest declares about where the package is entered.
+ *
+ * A target is taken as written. It is not resolved to a source file here, because
+ * which file a target names is a fact about the compiler configuration that emits
+ * it and there is one such configuration per project, while there is one manifest.
+ */
+export function readManifest(host, targetRoot) {
+    const manifest = manifestOf(host, targetRoot);
+    if (manifest === undefined) {
+        return { entries: [], declaresExports: false };
+    }
+    const found = [];
+    for (const member of LEGACY_MEMBERS) {
+        const value = manifest[member];
+        if (typeof value === "string" && isTarget(value, false)) {
+            found.push({ member, path: value, role: "import", published: true });
+        }
+    }
+    const bin = manifest["bin"];
+    if (typeof bin === "string" && isTarget(bin, false)) {
+        found.push({ member: "bin", path: bin, role: "run", published: false });
+    }
+    else if (isRecord(bin)) {
+        for (const [command, value] of Object.entries(bin)) {
+            if (typeof value === "string" && isTarget(value, false)) {
+                found.push({ member: below("bin", command), path: value, role: "run", published: false });
+            }
+        }
+    }
+    exportTargets(manifest["exports"], "exports", found);
+    return {
+        entries: found.map((entry) => ({ ...entry, path: resolvePath(targetRoot, entry.path) })),
+        declaresExports: manifest["exports"] !== undefined,
+    };
+}