@cplieger/deadset-ts 3.2.0 → 3.3.1

package/dist/src/member-names.js

@@ -0,0 +1,76 @@
+/**
+ * The members of one project's inventory by the name each is written with, for the
+ * classes whose evidence is a name rather than a type relation: a template and a
+ * string key both hold a name and nothing else, so each holds back every member of
+ * that name its own mechanism can reach.
+ */
+import { isIdentifier, isNumericLiteral, isPrivateIdentifier, isStringLiteral, } from "@typescript/native/unstable/ast";
+import { nodeKey } from "./inventory.js";
+/** The kinds of declaration a member name can name. */
+const MEMBER_KINDS = new Set([
+    "method",
+    "class-member",
+    "interface-method",
+    "type-member",
+    "enum-member",
+]);
+/**
+ * The name a member declaration is written with: an identifier's text, a private
+ * name's text without its `#`, a string key's value and a numeric key's text. A
+ * private name is indexed under the name a template or a string would spell, so the
+ * rule that no such evidence holds it back is the framework's alone. A computed key
+ * names nothing a string can be equal to before the program runs.
+ */
+function writtenName(name) {
+    if (name === undefined) {
+        return undefined;
+    }
+    if (isPrivateIdentifier(name)) {
+        return name.text.replace(/^#/u, "");
+    }
+    if (isIdentifier(name)) {
+        return name.text;
+    }
+    if (isStringLiteral(name) || isNumericLiteral(name)) {
+        return name.text;
+    }
+    return undefined;
+}
+/**
+ * Every member the inventory holds, keyed by the name it is written with, each
+ * member once and in inventory order. A getter and a setter of one name are one
+ * member.
+ */
+export function memberNames(files, held) {
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    const named = new Map();
+    for (const file of files) {
+        const visit = (node) => {
+            const id = held.declarations.get(nodeKey(file, node));
+            const symbol = id === undefined ? undefined : byId.get(id);
+            if (symbol !== undefined && MEMBER_KINDS.has(symbol.kind)) {
+                const name = writtenName(node.name);
+                if (name !== undefined) {
+                    named.set(symbol.id, name);
+                }
+            }
+            node.forEachChild(visit);
+        };
+        visit(file);
+    }
+    const index = new Map();
+    for (const symbol of held.symbols) {
+        const name = named.get(symbol.id);
+        if (name === undefined) {
+            continue;
+        }
+        const members = index.get(name);
+        if (members === undefined) {
+            index.set(name, [symbol]);
+        }
+        else {
+            members.push(symbol);
+        }
+    }
+    return index;
+}

package/dist/src/references.js

@@ -1,4 +1,4 @@
-import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
 import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
@@ -207,6 +207,7 @@ function sitesOf(file, declarations, fileId) {
     const found = [];
     const links = [];
     const evaluations = [];
+    const decorated = [];
     const writes = new Set();
     const declared = new Set();
     const shorthands = new Map();
@@ -251,12 +252,17 @@ function sitesOf(file, declarations, fileId) {
         const outer = enclosing;
         if (held !== undefined) {
             enclosing = held;
+            for (const modifier of node.modifiers ?? []) {
+                if (isDecorator(modifier)) {
+                    decorated.push({ decorator: modifier, declaration: held });
+                }
+            }
         }
         node.forEachChild(visit);
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return { uses: found, links, evaluations };
+    return { uses: found, links, evaluations, decorated };
 }
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
@@ -336,7 +342,20 @@ export function references(project, held, targetRoot, options) {
         if (test) {
             tests.push(path);
         }
-        const { uses, links, evaluations } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        const { uses, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        // A decorator is written inside the declaration it is attached to and receives it,
+        // so the declaration is used where the decorator is written, whatever the
+        // decorator does with it.
+        for (const { decorator, declaration } of decorated) {
+            found.push({
+                from: declaration,
+                to: declaration,
+                position: renderPosition(file, targetRoot, decorator.getStart()),
+                use: "decorator",
+                resolution: "syntax",
+                test,
+            });
+        }
         // One batch per capped run of the file's name nodes, the re-exports' nodes after
         // the uses and the evaluated modules' specifiers last, each node once: a bare star
         // re-export's specifier is a link and an evaluation both. A shorthand is left out

package/dist/src/reflective-lookup.js

@@ -0,0 +1,96 @@
+/**
+ * The reflective-lookup class: a member is held back, at the lowest confidence, when
+ * a string literal equal to its name is the key of an element access or the property
+ * key of a `Reflect.get`, `Reflect.set` or `Reflect.has` call, because the member is
+ * then read by a name the program computes nowhere the reference pass can follow.
+ *
+ * The evidence is a string beside a lookup rather than a type relation, so the
+ * string reaches every member of that name on any type, static members included,
+ * and every record names the string's own position. A key that is not literal text
+ * holds nothing back: a computed name is the case no exact rule serves. `Reflect` is
+ * the global one only: a local declaration of that name is a different object.
+ */
+import { isCallExpression, isElementAccessExpression, isIdentifier, isNoSubstitutionTemplateLiteral, isPropertyAccessExpression, isStringLiteral, } from "@typescript/native/unstable/ast";
+import { memberNames } from "./member-names.js";
+import { renderPosition } from "./position.js";
+/** The `Reflect` methods whose second argument is a property key. */
+const REFLECT_KEYED = new Set(["get", "set", "has"]);
+/** The text one key denotes, where it is literal text. */
+function literalText(node) {
+    if (node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))) {
+        return node.text;
+    }
+    return undefined;
+}
+/** Every lookup one file writes with a literal key, in source order. */
+function lookupsOf(file) {
+    const found = [];
+    const visit = (node) => {
+        if (isElementAccessExpression(node)) {
+            const name = literalText(node.argumentExpression);
+            if (name !== undefined) {
+                found.push({
+                    key: node.argumentExpression,
+                    name,
+                    callee: `[${JSON.stringify(name)}]`,
+                    reflect: undefined,
+                });
+            }
+        }
+        else if (isCallExpression(node) && isPropertyAccessExpression(node.expression)) {
+            const target = node.expression.expression;
+            const method = node.expression.name;
+            const key = node.arguments[1];
+            const name = literalText(key);
+            if (isIdentifier(target) &&
+                target.text === "Reflect" &&
+                isIdentifier(method) &&
+                REFLECT_KEYED.has(method.text) &&
+                key !== undefined &&
+                name !== undefined) {
+                found.push({ key, name, callee: `Reflect.${method.text}`, reflect: target });
+            }
+        }
+        node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+    return found;
+}
+/**
+ * The reflective-lookup detector: every member whose name a literal key of a lookup
+ * spells, recorded at the key.
+ */
+export function reflectiveLookup(input) {
+    const { project, held, targetRoot } = input;
+    const files = project.ownSourceFiles();
+    const lookups = files.flatMap(lookupsOf);
+    if (lookups.length === 0) {
+        return [];
+    }
+    // Whether each written `Reflect` is the global one, asked in one batch: a
+    // declaration of that name in one of the project's own files shadows it.
+    const ownFiles = new Set(files.map((file) => file.fileName));
+    const reflects = lookups.flatMap((lookup) => lookup.reflect === undefined ? [] : [lookup.reflect]);
+    const global = new Set();
+    if (reflects.length > 0) {
+        project.symbolsAt(reflects.map((node) => project.handle(node))).forEach((symbol, index) => {
+            const node = reflects[index];
+            const declaredHere = symbol?.declarations.some((declaration) => ownFiles.has(declaration.path));
+            if (node !== undefined && declaredHere === false) {
+                global.add(node);
+            }
+        });
+    }
+    const members = memberNames(files, held);
+    const found = [];
+    for (const lookup of lookups) {
+        if (lookup.reflect !== undefined && !global.has(lookup.reflect)) {
+            continue;
+        }
+        const site = renderPosition(lookup.key.getSourceFile(), targetRoot, lookup.key.getStart());
+        for (const member of members.get(lookup.name) ?? []) {
+            found.push({ id: member.id, detail: `looked up by ${lookup.callee}`, site });
+        }
+    }
+    return found;
+}

package/dist/src/run.js

@@ -1,29 +1,30 @@
-import { runRoots, runSweep } from "./analysis.js";
 import { ConfigError, REPOSITORY_DOCUMENT } from "./config.js";
-import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
-import { retainedLines } from "./exempt.js";
+import { DiscoveryError, renderDiagnostic } from "./discover.js";
+import { EMITTERS } from "./findings/emitters.js";
 import { joinPath, resolvePath } from "./paths.js";
-import { printConfig } from "./print.js";
-import { resolve, resolveMatrix } from "./resolve.js";
 import { readScope, ScopeError, scopeForDir } from "./scope.js";
-import { diagnosticsOf, openEngine, runSession } from "./session.js";
-import { CONTRACT_VERSION } from "./version.js";
-/** The exit codes the Contract's exit-code table names. */
-const EXIT_CLEAN = 0;
-const EXIT_FINDINGS = 1;
-const EXIT_USAGE = 2;
-const EXIT_FAILURE = 3;
+import { openEngine } from "./session.js";
+import { printConfigVerb } from "./verbs/print-config.js";
+import { printProjectsVerb } from "./verbs/print-projects.js";
+import { printRetainedVerb } from "./verbs/print-retained.js";
+import { printRootsVerb } from "./verbs/print-roots.js";
+import { EXIT_FAILURE, EXIT_USAGE } from "./verbs/verb.js";
+import { versionVerb } from "./verbs/version.js";
+/**
+ * Every verb this command answers, in the order the usage text lists them. A verb
+ * with no `run` is listed, and invoking it is a usage error.
+ */
 const VERBS = [
-    "analyze",
-    "explain",
-    "print-config",
-    "print-projects",
-    "print-roots",
-    "print-retained",
-    "describe",
-    "version",
+    { name: "analyze" },
+    { name: "explain" },
+    { name: "print-config", run: printConfigVerb },
+    { name: "print-projects", run: printProjectsVerb },
+    { name: "print-roots", run: printRootsVerb },
+    { name: "print-retained", run: printRetainedVerb },
+    { name: "describe" },
+    { name: "version", run: versionVerb },
 ];
-const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`;
+const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.map((verb) => verb.name).join(", ")}\n`;
 /**
  * The tokens whose presence in an option's name makes that option a request to
  * edit a source file. The set is closed, and a token is matched in any position of
@@ -31,15 +32,11 @@ const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.join(", ")}\n`
  */
 const SOURCE_EDIT_TOKENS = ["fix", "edit", "delete", "rewrite"];
 /**
- * Maps an option name to the setting it supplies, so one entry registers the
- * option, supplies the document resolution reads, and gives the spelling the
- * setting's provenance names.
- *
- * An option's name is this command's own vocabulary, chosen for how it reads on a
- * command line, and its path is the setting of the Contract's configuration schema
- * that option supplies. The two are mapped here and never derived from one
- * another, so this table is the authority for both: a setting reaches the command
- * line only by an entry, and a path names a key the schema declares.
+ * Maps an option name to the setting of the Contract's configuration schema it supplies,
+ * so one entry registers the option, supplies the document resolution reads, and gives
+ * the spelling the setting's provenance names. The name is this command's vocabulary and
+ * is never derived from the path: a setting reaches the command line only by an entry,
+ * and a path names a key the schema declares.
  */
 export const SETTING_OPTIONS = new Map([
     ["min-confidence", "analysis.min_confidence"],
@@ -139,20 +136,13 @@ function scopeOf(host, options) {
     return scopeForDir(host, options.named.get("target") ?? ".");
 }
 /**
- * Runs the deadset-ts command line over `args` (the arguments after the program
- * name) and returns the process exit code: 0 for a completed verb, 2 for a usage
- * error or a configuration this analyzer refuses, 3 for a failure that produced no
- * answer. It writes nothing outside `out` and `err` and never exits the process,
- * so a caller decides what the code means.
- *
- * An option asking for a source edit is refused before the verb is read: this
- * analyzer reports and never edits a source file.
- *
- * `host` is the platform the run reads, the version it reports included;
- * `openClient` opens the compiler client a verb that reads projects needs.
- * Both are parameters because both are the platform, which no module below this one
- * names: the command entry binds them, and a caller that wants to watch what a run
- * reads supplies its own.
+ * Runs the command line over `args`, the arguments after the program name, and returns
+ * the exit code: 0 for a completed verb, 1 for a finding that fails the run, 2 for a
+ * usage error, a requested source edit or a refused configuration, 3 for a failure that
+ * produced no answer. It writes nothing outside `out` and `err` and never exits the
+ * process. `host` is the platform the run reads, the version it reports included, and
+ * `openClient` opens the compiler client; a caller that watches what a run reads
+ * supplies its own of either.
  */
 export function run(args, out, err, host, openClient = (collectTiming) => openEngine({ collectTiming })) {
     const editing = sourceEditOption(args);
@@ -161,151 +151,45 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
         err.write(USAGE);
         return EXIT_USAGE;
     }
-    const verb = args[0];
-    if (verb === "version") {
-        out.write(`deadset-ts ${host.analyzerVersion()}\ncontract ${CONTRACT_VERSION}\n`);
-        return EXIT_CLEAN;
-    }
-    if (verb === "print-config") {
-        return printConfigVerb(args.slice(1), out, err, host);
-    }
-    if (verb === "print-projects") {
-        return printProjectsVerb(args.slice(1), out, err, host, openClient);
-    }
-    if (verb === "print-roots") {
-        return printRootsVerb(args.slice(1), out, err, host, openClient);
+    const name = args[0];
+    const verb = VERBS.find((listed) => listed.name === name);
+    if (verb?.run !== undefined) {
+        return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
     }
-    if (verb === "print-retained") {
-        return printRetainedVerb(args.slice(1), out, err, host, openClient);
-    }
-    if (verb !== undefined && VERBS.includes(verb)) {
-        err.write(`deadset-ts: ${verb} is not implemented\n`);
+    if (verb !== undefined) {
+        err.write(`deadset-ts: ${verb.name} is not implemented\n`);
         return EXIT_USAGE;
     }
-    if (verb !== undefined) {
-        err.write(`deadset-ts: unknown verb ${JSON.stringify(verb)}\n`);
+    if (name !== undefined) {
+        err.write(`deadset-ts: unknown verb ${JSON.stringify(name)}\n`);
     }
     err.write(USAGE);
     return EXIT_USAGE;
 }
-/** Writes the resolved configuration with the source of every setting. */
-function printConfigVerb(args, out, err, host) {
-    try {
-        const options = readOptions(args);
-        const { config, provenance } = resolve(inputsOf(host, options));
-        out.write(printConfig(config, provenance));
-        return EXIT_CLEAN;
-    }
-    catch (error) {
-        return refuse(error, err);
-    }
-}
 /**
- * Writes the name of every project one run analyzes, one per line, having read each
- * project's diagnostics first: the identifier the build matrix declares for it, or,
- * where discovery derived the project, its configuration file's path below the
- * target root.
+ * Runs one verb over the arguments after its name. The options are read the first
+ * time the verb asks for what they name, and a refusal the verb throws is written
+ * and turned into its exit code once the client the verb opened is closed.
  */
-function printProjectsVerb(args, out, err, host, openClient) {
-    let engine;
+function invoke(verb, args, streams, openClient) {
+    let options;
+    const read = () => (options ??= readOptions(args));
+    let opened;
     try {
-        const options = readOptions(args);
-        const matrix = resolveMatrix(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const discovered = discoverProjects(engine, host, scope, matrix);
-        const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
-        const failures = [];
-        const { projects } = runSession(engine, discovered.configFiles, (project) => {
-            const errors = diagnosticErrors(diagnosticsOf(project));
-            failures.push(...errors.map(renderDiagnostic));
-            return ids.get(project.configFile) ?? project.configFile;
+        return verb({
+            ...streams,
+            inputs: () => inputsOf(streams.host, read()),
+            scope: () => scopeOf(streams.host, read()),
+            openClient: (collectTiming) => {
+                opened = openClient(collectTiming);
+                return opened;
+            },
+            emitters: EMITTERS,
         });
-        if (failures.length > 0) {
-            for (const line of failures) {
-                err.write(`${line}\n`);
-            }
-            err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
-            return EXIT_FAILURE;
-        }
-        for (const id of projects) {
-            out.write(`${id}\n`);
-        }
-        return EXIT_CLEAN;
-    }
-    catch (error) {
-        engine?.close();
-        return refuse(error, err);
-    }
-}
-/**
- * One root as a line: the declaration's reference, why it is a root, and the string
- * that named it, separated by tabs. A run of several configurations adds the ones
- * whose project holds the root as a fourth field, and writes the third present and
- * empty where no string named the root, so every line of one run holds the same
- * fields.
- */
-function rootLine(root, several) {
-    const line = `${root.ref}\t${root.kind}`;
-    if (several) {
-        return `${line}\t${root.source}\t${root.configurations.join(" ")}`;
-    }
-    return root.source === "" ? line : `${line}\t${root.source}`;
-}
-/**
- * Writes the root set of the run, one root per line, and then names on the error
- * stream, by its issue kind, every configured root or pattern that named nothing;
- * one such string fails the run. The line shape is this command's own rather than a
- * Contract format, so that sort and cut read it.
- */
-function printRootsVerb(args, out, err, host, openClient) {
-    let engine;
-    try {
-        const options = readOptions(args);
-        const { config, provenance } = resolve(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const answer = runRoots(engine, host, scope, config, provenance);
-        const several = answer.configurations.length > 1;
-        for (const root of answer.roots) {
-            out.write(`${rootLine(root, several)}\n`);
-        }
-        for (const finding of answer.findings) {
-            err.write(`${finding.code}: roots.patterns names nothing: ${finding.symbol.ref}\n`);
-        }
-        return answer.findings.length > 0 ? EXIT_FINDINGS : EXIT_CLEAN;
-    }
-    catch (error) {
-        engine?.close();
-        return refuse(error, err);
-    }
-}
-/**
- * Writes every declaration an exemption held back in the production sweep a report is
- * built from, one per line, and nothing where no exemption held one back. One fact
- * several configurations found is one record, so the line names no configuration. The
- * line shape is this command's own rather than a Contract format, so that sort and cut
- * read it.
- */
-function printRetainedVerb(args, out, err, host, openClient) {
-    let engine;
-    try {
-        const options = readOptions(args);
-        const { config } = resolve(inputsOf(host, options));
-        const scope = scopeOf(host, options);
-        engine = openClient(false);
-        const swept = runSweep(engine, host, scope, config, {
-            marked: [],
-            mode: { production: true },
-        });
-        for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
-            out.write(`${line}\n`);
-        }
-        return EXIT_CLEAN;
     }
     catch (error) {
-        engine?.close();
-        return refuse(error, err);
+        opened?.close();
+        return refuse(error, streams.err);
     }
 }
 /** Turns one refusal into the exit code the Contract's table gives it. */