@cplieger/deadset-ts 4.0.1 → 5.1.0

package/dist/src/kinds.js

@@ -30,6 +30,7 @@ const ROWS = [
         name: "unused-member",
         languages: ["go", "ts"],
         rule: "A struct field, class member or type member with no reference, a private member included. A member referenced only from its own declaration site counts as unreferenced.",
+        precondition: "A TypeScript member that no value writes and nothing reads, whose type names a type parameter of its declaring interface, class or type alias, is not reported when every part of that declaration that names the type parameter is a member no value writes and nothing reads. TypeScript compares object types by their members, so such members are what make two instantiations of their type distinct types, and deleting them leaves the type parameter phantom and lets one instantiation stand for another. A member a value writes is decided by the rule of DS1301 instead, whatever its type names.",
         defaultSeverity: "deny",
         maxClass: "certain",
         fixability: "deletable",
@@ -39,7 +40,7 @@ const ROWS = [
         code: "DS1004",
         name: "test-only-use",
         languages: ["go", "ts"],
-        rule: "A symbol with zero production references and at least one test reference: an unused-exported, unused-unexported or unused-member candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production.",
+        rule: "A symbol with zero production references and at least one test reference: an unused-exported, unused-unexported or unused-member candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production. A reference from test-support code, a package or file that only test code imports, is a test reference, and a declaration of test-support code is never reported under this code.",
         defaultSeverity: "deny",
         maxClass: "certain",
         fixability: "deletable",
@@ -70,7 +71,7 @@ const ROWS = [
         name: "unnecessary-export",
         languages: ["go", "ts"],
         rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
-        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
+        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the package references that function or method, because the caller holds values of the type, and unexporting it would leave an exported signature naming a type its callers cannot name.",
         defaultSeverity: "warn",
         maxClass: "certain",
         fixability: "narrowable",
@@ -81,7 +82,7 @@ const ROWS = [
         name: "unnecessary-exposure",
         languages: ["go"],
         rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
-        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
+        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the target module references that function or method, because the caller holds values of the type, and moving it behind an internal boundary would leave an exported signature naming a type its callers cannot name.",
         defaultSeverity: "warn",
         maxClass: "certain",
         fixability: "narrowable",
@@ -143,7 +144,7 @@ const ROWS = [
         code: "DS1301",
         name: "write-only-symbol",
         languages: ["go", "ts"],
-        rule: "A package-level or module-level variable, struct field, class member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. The finding names each write position, so the deletion set is visible.",
+        rule: "A package-level or module-level variable, struct field, class member, type member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. In TypeScript a property of an object literal writes the member of the same name that the literal's contextual type declares, whether or not the compiler checks the literal for excess properties. Where that contextual type is a union or an intersection, the property writes the member of that name on each constituent that declares one. So a literal that a declaration annotates, a function returns, a call passes or a `satisfies` expression checks writes the members of the type it is given. A store through the value a field or a member holds reads that field or member rather than writing it, because the store lands in storage every other holder of the value reads. In Go that store is an assignment, an increment, a compound assignment or a `delete` whose target is reached through a struct field holding a map, a slice or a pointer. Examples are `s.f[k] = v`, `s.f.x = v` and `delete(s.f, k)`. The same store through a field holding an array or a struct is a store into the field itself. TypeScript holds every object by reference, so an element or property store through a member's value reads the member. The finding names each write position, so the deletion set is visible. Deleting the subject and its writes also deletes every declaration whose only uses they hold. Such a declaration is a type parameter of the subject's declaring type that the subject's type alone names, or an import binding the writes alone use. The finding's message names each such declaration.",
         defaultSeverity: "deny",
         maxClass: "certain",
         fixability: "deletable",
@@ -278,7 +279,7 @@ const ROWS = [
         name: "unused-parameter",
         languages: ["go", "ts"],
         rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
-        precondition: "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
+        precondition: "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
         defaultSeverity: "warn",
         maxClass: "certain",
         fixability: "manual",

package/dist/src/manifest.js

@@ -1,11 +1,9 @@
 /**
  * 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.
+ * shell running its command or one of its scripts.
  *
- * 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.
+ * One call reads one manifest, the one in the directory it is given.
  */
 import { isAbsolutePath, joinPath, resolvePath } from "./paths.js";
 /** The manifest's own name. */
@@ -26,6 +24,21 @@ function isTarget(value, requireDot) {
     }
     return !requireDot || value.startsWith("./");
 }
+/** Where a script's command line splits into tokens: white space and the shell's operators. */
+const SCRIPT_SEPARATORS = /\s+|&&|\|\||;|\|/u;
+/** A token written inside one pair of quotes. */
+const QUOTED = /^(["'])(.*)\1$/su;
+/**
+ * Every token one script's command line holds, each with one pair of enclosing quotes
+ * removed. A token holding a wildcard is a pattern rather than a path, and names no
+ * entry point.
+ */
+export function scriptTokens(command) {
+    return command
+        .split(SCRIPT_SEPARATORS)
+        .map((token) => token.replace(QUOTED, "$2"))
+        .filter((token) => token !== "" && !token.includes("*"));
+}
 /** One member's spelling below another: `exports` then `exports["."]`. */
 function below(member, key) {
     return `${member}[${JSON.stringify(key)}]`;
@@ -33,12 +46,9 @@ function below(member, 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.
+ * The value nests strings, subpath or condition objects and alternative arrays to
+ * any depth; a `null` blocks a subpath. Every level is walked, because each
+ * condition names its own entry file, and a key's meaning is never read.
  */
 function exportTargets(value, member, found) {
     if (typeof value === "string") {
@@ -83,7 +93,7 @@ function manifestOf(host, targetRoot) {
     return isRecord(value) ? value : undefined;
 }
 /**
- * What the target's own manifest declares about where the package is entered.
+ * What the manifest in `targetRoot` declares about where its 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
@@ -113,6 +123,22 @@ export function readManifest(host, targetRoot) {
         }
     }
     exportTargets(manifest["exports"], "exports", found);
+    const scripts = manifest["scripts"];
+    if (isRecord(scripts)) {
+        for (const [name, command] of Object.entries(scripts)) {
+            if (typeof command !== "string") {
+                continue;
+            }
+            for (const token of new Set(scriptTokens(command))) {
+                found.push({
+                    member: below("scripts", name),
+                    path: token,
+                    role: "script",
+                    published: false,
+                });
+            }
+        }
+    }
     return {
         entries: found.map((entry) => ({ ...entry, path: resolvePath(targetRoot, entry.path) })),
         declaresExports: manifest["exports"] !== undefined,

package/dist/src/matrix.js

@@ -32,32 +32,31 @@ export function referenceKey(reference) {
 }
 /**
  * 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.
+ * A declaration is keyed by its rendered position, with the fields of the first
+ * configuration that judges it; one in a file every holder holds only for its references
+ * is judged by none and is not in the union. One reference at one position of a file
+ * several configurations compile is one reference; two one configuration makes are two.
  */
 export function matrixOf(per) {
     const symbols = [];
     const holders = new Map();
     const references = [];
     const firstSeen = new Map();
+    const judged = new Set();
     per.forEach((one, index) => {
+        const referenceOnly = new Set(one.referenceOnly);
         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);
             }
+            if (!referenceOnly.has(symbol.position.path) && !judged.has(symbol.id)) {
+                judged.add(symbol.id);
+                symbols.push(symbol);
+            }
         }
         for (const reference of one.references) {
             const key = referenceKey(reference);
@@ -74,8 +73,8 @@ export function matrixOf(per) {
     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))]),
+        graphs: per.map((one) => graphOf(one.symbols, one.references, one.roots, one.testFiles, one.supportFiles)),
+        union: graphOf(symbols, references, per.flatMap((one) => one.roots), [...new Set(per.flatMap((one) => one.testFiles))], [...new Set(per.flatMap((one) => one.supportFiles ?? []))]),
         heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
     };
 }
@@ -131,6 +130,15 @@ export function sweepMatrix(matrix, input) {
         components: componentsOf(union, dead, testOfDeadCode),
     };
 }
+/**
+ * The file declarations at `paths`, below the target root, that one sweep holds live
+ * under both relations, the rule a judged declaration is live by.
+ */
+export function liveFilesAt(matrix, result, paths) {
+    return matrix.union.symbols.filter((symbol) => symbol.kind === "file" &&
+        paths.has(symbol.position.path) &&
+        (result.liveUnder.get(symbol.id)?.length ?? 0) === RELATIONS.length);
+}
 /** The relations in the order a declaration's entry lists them. */
 const RELATIONS = ["reference-counting", "reachability"];
 /**

package/dist/src/partial.js

@@ -1,3 +1,4 @@
+import { relativePath } from "./paths.js";
 /** A count with its noun, so a line reads for one as well as for several. */
 function counted(n, one, many) {
     return `${String(n)} ${n === 1 ? one : many}`;
@@ -14,7 +15,8 @@ export function partialNotes(partial) {
     if (partial.unanswered.length > 0) {
         const byProject = new Map();
         for (const question of partial.unanswered) {
-            byProject.set(question.configFile, (byProject.get(question.configFile) ?? 0) + 1);
+            const configFile = relativePath(partial.targetRoot, question.configFile) ?? question.configFile;
+            byProject.set(configFile, (byProject.get(configFile) ?? 0) + 1);
         }
         const where = [...byProject].map(([configFile, n]) => `${configFile}: ${String(n)}`).join(", ");
         notes.push(`the checker answered ${counted(partial.unanswered.length, "question", "questions")} with a failure (${where}); every declaration an answer could have kept live is kept live and reported by nothing`);

package/dist/src/pnpm-workspace.js

@@ -0,0 +1,120 @@
+/**
+ * The `packages` list of a `pnpm-workspace.yaml`. The document is read as far as that
+ * one key needs and no further: a top-level `packages` key holding a block sequence or
+ * a one-line flow sequence of plain or quoted strings. Any other value of the key is
+ * refused rather than guessed at, because a list read wrong names the wrong packages.
+ */
+/** The characters a plain scalar may not start with. */
+const INDICATORS = new Set(["[", "]", "{", "}", ",", "&", "*", "!", "|", ">", "%", "@", "`", "#"]);
+/** One line with its comment removed, a `#` inside quotes kept. */
+function uncommented(line) {
+    let quote;
+    for (let at = 0; at < line.length; at += 1) {
+        const character = line[at];
+        if (quote !== undefined) {
+            if (character === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"') {
+            quote = character;
+        }
+        else if (character === "#" && (at === 0 || /\s/u.test(line[at - 1] ?? ""))) {
+            return line.slice(0, at).trimEnd();
+        }
+    }
+    return line.trimEnd();
+}
+/** One scalar as written, or `undefined` where it is not a string this reader reads. */
+function scalarOf(text) {
+    const value = text.trim();
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+        const inner = value.slice(1, -1);
+        return /'(?!')/u.test(inner.replaceAll("''", "")) ? undefined : inner.replaceAll("''", "'");
+    }
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        const inner = value.slice(1, -1);
+        return inner.includes("\\") || inner.includes('"') ? undefined : inner;
+    }
+    if (value === "" ||
+        INDICATORS.has(value[0] ?? "") ||
+        value.startsWith("'") ||
+        value.startsWith('"')) {
+        return undefined;
+    }
+    if (value.startsWith("- ") || value.startsWith("? ") || /:(?:\s|$)/u.test(value)) {
+        return undefined;
+    }
+    return value;
+}
+/** The entries of a one-line flow sequence, or `undefined` where one does not read. */
+function flowOf(text) {
+    const inner = text.slice(1, -1).trim();
+    if (inner === "") {
+        return [];
+    }
+    const entries = inner.split(",");
+    if (entries.length > 1 && entries.at(-1)?.trim() === "") {
+        entries.pop();
+    }
+    const found = [];
+    for (const entry of entries) {
+        const value = scalarOf(entry);
+        if (value === undefined) {
+            return undefined;
+        }
+        found.push(value);
+    }
+    return found;
+}
+const KEY = /^(?:packages|'packages'|"packages")\s*:(?:\s(.*))?$/u;
+/** The `packages` list one `pnpm-workspace.yaml` text declares. */
+export function pnpmPackages(text) {
+    const lines = text.split(/\r?\n/u).map(uncommented);
+    const keys = lines.flatMap((line, at) => (KEY.test(line) ? [at] : []));
+    const [at] = keys;
+    if (at === undefined) {
+        return { kind: "absent" };
+    }
+    if (keys.length > 1) {
+        return { kind: "refused", reason: "the packages key is declared more than once" };
+    }
+    const rest = (KEY.exec(lines[at] ?? "")?.[1] ?? "").trim();
+    if (rest !== "") {
+        const listed = rest.startsWith("[") && rest.endsWith("]") ? flowOf(rest) : undefined;
+        return listed === undefined
+            ? {
+                kind: "refused",
+                reason: `packages holds ${JSON.stringify(rest)}, not a sequence of strings`,
+            }
+            : { kind: "listed", patterns: listed };
+    }
+    const patterns = [];
+    for (const line of lines.slice(at + 1)) {
+        if (line.trim() === "") {
+            continue;
+        }
+        const item = /^(\s*)-(?:\s+(.*))?$/u.exec(line);
+        if (item === null) {
+            if (/^\s/u.test(line)) {
+                return {
+                    kind: "refused",
+                    reason: `packages holds ${JSON.stringify(line.trim())}, not a sequence item`,
+                };
+            }
+            break;
+        }
+        const value = scalarOf(item[2] ?? "");
+        if (value === undefined) {
+            return {
+                kind: "refused",
+                reason: `the packages item ${JSON.stringify(line.trim())} is not a plain or quoted string`,
+            };
+        }
+        patterns.push(value);
+    }
+    return patterns.length === 0
+        ? { kind: "refused", reason: "packages holds no sequence" }
+        : { kind: "listed", patterns };
+}

package/dist/src/position.js

@@ -13,18 +13,33 @@ export class PositionError extends Error {
         this.file = file;
     }
 }
+/** Whether the compiler read one file through a content mapper, which makes it a component file. */
+export function isComponentFile(file) {
+    return file.contentMapper !== undefined;
+}
+/**
+ * The length of the file as it is written. A component file's module holds the file's
+ * text at its own offsets and appends what it needs past its end.
+ */
+export function writtenLength(file) {
+    return isComponentFile(file) ? file.originalText.length : file.text.length;
+}
 /**
  * The position of one offset of one file, rendered against the target root.
  *
  * `offset` is a UTF-16 code unit offset into the file's text, which is what every
- * node of the tree carries.
+ * node of the tree carries. An offset a component file's module appends renders where
+ * the module's span map places it in the file.
  */
 export function renderPosition(file, root, offset) {
     const path = relativePath(root, file.fileName);
     if (path === undefined) {
         throw new PositionError(file.fileName, root);
     }
-    const { line, character } = file.getLineAndCharacterOfPosition(offset);
+    const written = isComponentFile(file) && offset >= file.originalText.length
+        ? Math.min(file.spanMap?.virtualToOriginalPosition(offset).position ?? offset, file.originalText.length)
+        : offset;
+    const { line, character } = file.getLineAndCharacterOfPosition(written);
     return { path, line: line + 1, column: character + 1 };
 }
 /**

package/dist/src/print.js

@@ -64,6 +64,8 @@ export function printConfig(config, provenance) {
         ts: {
             test_files: config.ts.testFiles,
             entry_files: config.ts.entryFiles,
+            component_extensions: config.ts.componentExtensions,
+            disabled_conventions: config.ts.disabledConventions,
             injection_registrations: config.ts.injectionRegistrations.map(declarationOf),
             lifecycle_contracts: config.ts.lifecycleContracts.map((entry) => ({
                 components: entry.components.map(declarationOf),

package/dist/src/query.js

@@ -73,6 +73,21 @@ function symbolLocation(symbol) {
 function typeLocation(type) {
     return `type ${String(type.id)}`;
 }
+/** The property tables over one project's questions. */
+export function propertyTables(queries) {
+    const held = new Map();
+    return {
+        of: (type) => {
+            const known = held.get(type.id);
+            if (known !== undefined) {
+                return { properties: known, asked: false };
+            }
+            const properties = queries.propertiesOf(type);
+            held.set(type.id, properties);
+            return { properties, asked: true };
+        },
+    };
+}
 /**
  * The guarded questions over one project's checker. `configFile` names the project
  * in the log, `batch` sends many questions in one round trip, `log` is the run's,