@cplieger/deadset-ts 2.2.1 → 3.0.0

package/dist/src/references.js

@@ -1,5 +1,6 @@
-import { isArrayLiteralExpression, isBinaryExpression, isDeleteExpression, isElementAccessExpression, isForInStatement, isForOfStatement, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { isArrayLiteralExpression, isBinaryExpression, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isForInStatement, isForOfStatement, isNamespaceExport, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
+import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
 import { byPosition, renderPosition } from "./position.js";
 /**
@@ -125,18 +126,54 @@ function markStores(node, writes) {
         }
     }
 }
+/**
+ * The re-exports one node writes, if it is an export declaration. A specifier and a
+ * namespace export are declarations whose names are where they are written, so no use is
+ * read from them; each references what it carries forward instead. A bare star declares
+ * nothing, so the declaration enclosing it, at the top level the file, references the
+ * module it names.
+ */
+function linksOf(file, node, declarations, enclosing) {
+    if (!isExportDeclaration(node)) {
+        return [];
+    }
+    const clause = node.exportClause;
+    const specifier = node.moduleSpecifier;
+    if (clause === undefined) {
+        return specifier === undefined
+            ? []
+            : [{ node: specifier, at: specifier, from: enclosing, alias: false }];
+    }
+    if (isNamespaceExport(clause)) {
+        const from = declarations.get(nodeKey(file, clause));
+        return from === undefined
+            ? []
+            : [{ node: clause.name, at: specifier ?? clause.name, from, alias: true }];
+    }
+    const found = [];
+    for (const element of clause.elements) {
+        const from = declarations.get(nodeKey(file, element));
+        if (from !== undefined) {
+            found.push({
+                node: element.name,
+                at: element.propertyName ?? element.name,
+                from,
+                alias: true,
+            });
+        }
+    }
+    return found;
+}
 /**
  * Every name node one file holds that is a use rather than a declaration, in source
- * order, each with the declaration that encloses it and the use it makes.
- *
- * One walk answers all three, because the three facts are positional and a second walk
- * would have to agree with this one about which nodes are names. A name that is the
- * declared name of the declaration it belongs to is left out: it is where that
- * declaration is written rather than a use of it, which is what makes a declaration
- * referenced only from its own site an unreferenced declaration.
+ * order, each with its enclosing declaration and its use, and every re-export the file
+ * writes. One walk answers all of it, because a second would have to agree with this one
+ * about which nodes are names. A declaration's own declared name is left out, which is
+ * what makes a declaration referenced only from its own site an unreferenced one.
  */
 function sitesOf(file, declarations, fileId) {
     const found = [];
+    const links = [];
     const writes = new Set();
     const declared = new Set();
     const shorthands = new Map();
@@ -172,6 +209,7 @@ function sitesOf(file, declarations, fileId) {
         }
         markNames(node);
         markStores(node, writes);
+        links.push(...linksOf(file, node, declarations, enclosing));
         const held = declarations.get(nodeKey(file, node));
         const outer = enclosing;
         if (held !== undefined) {
@@ -181,63 +219,7 @@ function sitesOf(file, declarations, fileId) {
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return found;
-}
-/**
- * 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.
- */
-function expressionOf(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");
+    return { uses: found, links };
 }
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
@@ -270,10 +252,12 @@ function compare(a, b) {
 export function references(project, held, targetRoot, options) {
     const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
     const declarations = held.declarations;
-    const patterns = options.testFiles.map(expressionOf);
+    const patterns = options.testFiles.map(globExpression);
     const matched = options.testFiles.map(() => 0);
     const found = [];
+    const tests = [];
     const reached = new Map();
+    const steps = new Map();
     let batched = 0;
     let fileBatches = 0;
     let residueFallbacks = 0;
@@ -283,23 +267,51 @@ export function references(project, held, targetRoot, options) {
     const ownFiles = new Set(files.map((file) => file.fileName));
     /** The identifier of the declaration one node of this program is, where it is one. */
     const declaredAt = (node) => declarations.get(nodeKey(node.getSourceFile(), node));
+    /**
+     * The declarations of the inventory one symbol is.
+     *
+     * A declaration handle carries the file it is in, so the question is answered before
+     * the handle is resolved: a declaration outside the project's own files belongs to
+     * another program and is never read, which is what keeps the pass from fetching a
+     * library file to discover that the inventory does not hold what is in it.
+     */
+    const declarationsOf = (symbol) => {
+        const ids = [];
+        for (const handle of symbol.declarations) {
+            if (!ownFiles.has(handle.path)) {
+                continue;
+            }
+            const node = project.declarationAt(handle)?.node;
+            const id = node === undefined ? undefined : declaredAt(node);
+            if (id !== undefined && !ids.includes(id)) {
+                ids.push(id);
+            }
+        }
+        return ids;
+    };
+    /**
+     * What one alias names, one link along, asked once per alias whatever the number of
+     * chains it is a link of. Only a symbol the binder flagged an alias is asked, which is
+     * the condition the step asserts on: a default export of an expression is written in
+     * an alias form and names nothing declared elsewhere, so its chain ends at itself.
+     */
+    const stepOf = (symbol) => {
+        if ((symbol.flags & SymbolFlags.Alias) === 0) {
+            return undefined;
+        }
+        if (steps.has(symbol.id)) {
+            return steps.get(symbol.id);
+        }
+        const next = project.aliasStepOf(symbol);
+        aliasSteps += 1;
+        steps.set(symbol.id, next);
+        return next;
+    };
     /**
      * The declarations one symbol names: the declaration it is, and every link of the
      * alias chain it stands at the head of. A re-export something imports is used and so
      * is the declaration behind it, so both are named; a link this project does not
      * declare is stepped over rather than recorded.
-     *
-     * A symbol is asked to step only where the binder flagged it an alias, which is the
-     * same condition the step itself asserts on. The declaration's syntax is not that
-     * condition and does not stand in for it: a default export of an expression is
-     * written as one of the alias forms and names nothing declared elsewhere, so it is
-     * recorded as the declaration it is and the chain ends there.
-     *
-     * A declaration handle carries the file it is in, so the question the walk asks of a
-     * declaration is answered before it is resolved: a declaration outside the project's
-     * own files belongs to another program and is never read, which is what keeps the
-     * pass from fetching a library file to discover that the inventory does not hold what
-     * is in it.
      */
     const targetsOf = (symbol) => {
         const cached = reached.get(symbol.id);
@@ -312,34 +324,47 @@ export function references(project, held, targetRoot, options) {
         let stepped = false;
         while (at !== undefined && !walked.has(at.id)) {
             walked.add(at.id);
-            const alias = (at.flags & SymbolFlags.Alias) !== 0;
-            for (const handle of at.declarations) {
-                if (!ownFiles.has(handle.path)) {
-                    continue;
-                }
-                const node = project.declarationAt(handle)?.node;
-                const id = node === undefined ? undefined : declaredAt(node);
-                if (id !== undefined && !targets.some((target) => target.id === id)) {
+            for (const id of declarationsOf(at)) {
+                if (!targets.some((target) => target.id === id)) {
                     targets.push({ id, stepped });
                 }
             }
-            if (!alias) {
-                break;
-            }
-            at = project.aliasStepOf(at);
-            aliasSteps += 1;
+            at = stepOf(at);
             stepped = true;
         }
         reached.set(symbol.id, targets);
         return targets;
     };
+    /**
+     * The declarations one re-export carries forward: for an alias, the first link along
+     * its chain that the inventory declares, stepping over the links it does not, such as
+     * an import the re-export is written against; for a bare star, the module it names.
+     * Each later link is a declaration of its own that references the next, so one link
+     * per re-export is what lets a chain be followed one declaration at a time.
+     */
+    const carriedBy = (link, symbol) => {
+        if (!link.alias) {
+            return declarationsOf(symbol);
+        }
+        const walked = new Set([symbol.id]);
+        let at = stepOf(symbol);
+        while (at !== undefined && !walked.has(at.id)) {
+            walked.add(at.id);
+            const ids = declarationsOf(at);
+            if (ids.length > 0) {
+                return ids;
+            }
+            at = stepOf(at);
+        }
+        return [];
+    };
     /** The symbol one site resolves to, asking only the accessor the site's form names. */
     const symbolFor = (site, answered) => {
         if (site.shorthand !== undefined) {
             shorthandLookups += 1;
             return project.shorthandValueAt(project.handle(site.shorthand));
         }
-        const batched = answered.get(site.node.pos);
+        const batched = answered.get(site.node);
         if (batched !== undefined) {
             return batched;
         }
@@ -348,35 +373,59 @@ export function references(project, held, targetRoot, options) {
     };
     for (const file of files) {
         const path = renderPosition(file, targetRoot, 0).path;
-        let test = false;
-        patterns.forEach((pattern, index) => {
-            if (pattern.test(path)) {
+        const hits = patterns.map((pattern) => pattern.test(path));
+        hits.forEach((hit, index) => {
+            if (hit) {
                 matched[index] = (matched[index] ?? 0) + 1;
-                test = true;
             }
         });
-        const sites = sitesOf(file, declarations, declaredAt(file) ?? "");
-        // One batch per capped run of the file's name nodes. A shorthand is left out of
-        // the batch: its name resolves to the property the literal declares, so the batch's
-        // answer for it would name something this project's inventory never holds.
-        const batching = sites.filter((site) => site.shorthand === undefined);
+        const test = hits.includes(true);
+        if (test) {
+            tests.push(path);
+        }
+        const { uses, links } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        // One batch per capped run of the file's name nodes, the re-exports' nodes after
+        // the uses. A shorthand is left out of the batch: its name resolves to the property
+        // the literal declares, so the batch's answer for it would name something this
+        // project's inventory never holds.
+        const batching = [
+            ...uses.filter((site) => site.shorthand === undefined).map((site) => site.node),
+            ...links.map((link) => link.node),
+        ];
         const answered = new Map();
         batched += batching.length;
         for (let from = 0; from < batching.length; from += cap) {
             const run = batching.slice(from, from + cap);
-            const answers = project.symbolsAt(run.map((site) => project.handle(site.node)));
+            const answers = project.symbolsAt(run.map((node) => project.handle(node)));
             fileBatches += 1;
-            run.forEach((site, index) => {
+            run.forEach((node, index) => {
                 const symbol = answers[index];
                 if (symbol !== undefined) {
-                    answered.set(site.node.pos, symbol);
+                    answered.set(node, symbol);
                 }
             });
         }
-        for (const site of sites) {
+        for (const link of links) {
+            const symbol = answered.get(link.node);
+            if (symbol === undefined) {
+                continue;
+            }
+            const position = renderPosition(file, targetRoot, link.at.getStart());
+            for (const id of carriedBy(link, symbol)) {
+                found.push({
+                    from: link.from,
+                    to: id,
+                    position,
+                    use: "read",
+                    resolution: link.alias ? "alias" : "batch",
+                    test,
+                });
+            }
+        }
+        for (const site of uses) {
             const direct = site.shorthand !== undefined
                 ? "shorthand"
-                : answered.has(site.node.pos)
+                : answered.has(site.node)
                     ? "batch"
                     : "resolved-symbol";
             const symbol = symbolFor(site, answered);
@@ -406,6 +455,7 @@ export function references(project, held, targetRoot, options) {
         testFileRules: options.testFiles
             .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
             .sort((a, b) => compare(a.rule, b.rule)),
+        testFilePaths: tests.sort(compare),
         cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps },
     };
 }

package/dist/src/resolve.js

@@ -8,6 +8,20 @@ const FAMILY_KEY_LENGTH = 4;
 const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;
 const CONTRACT_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/u;
+/** The members only a platform build configuration carries. */
+const PLATFORM_MEMBERS = ["os", "arch", "tags"];
+/** The member only a project build configuration carries. */
+const PROJECT_MEMBER = "project";
+/**
+ * One segment of a project path: not empty, not `.` or `..`, and holding no
+ * solidus, backslash or line break.
+ */
+const PROJECT_SEGMENT = String.raw `(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+)`;
+/**
+ * A project path: segments joined by a solidus, so the path is relative, below
+ * the root it is read against, and spelled one way on every machine.
+ */
+const PROJECT_PATH = new RegExp(`^${PROJECT_SEGMENT}(?:/${PROJECT_SEGMENT})*$`, "u");
 const TARGET_KINDS = ["application", "library"];
 const CONFIDENCES = ["certain", "probable", "possible"];
 const GENERATED_FILES = ["exclude", "include"];
@@ -135,10 +149,52 @@ function requireMember(value, path, label) {
     }
     return value;
 }
+/** One build configuration entry as a platform: an identifier, an operating system and an architecture. */
+function readPlatform(entry, at, label) {
+    return {
+        shape: "platform",
+        id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
+        os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
+        arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
+        tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
+    };
+}
+/** One build configuration entry as a project: an identifier and a configuration file below the target root. */
+function readProject(entry, at, label) {
+    const id = requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label);
+    const path = `${at}.${PROJECT_MEMBER}`;
+    const project = requireMember(readString(entry, PROJECT_MEMBER, path, label), path, label);
+    if (!PROJECT_PATH.test(project)) {
+        throw malformed(label, path, `${JSON.stringify(project)} is not a path below the target root: segments joined by /, ` +
+            "none empty, . or .., and no backslash or line break");
+    }
+    return { shape: "project", id, project };
+}
 /**
- * The build matrix: every entry names an identifier, an operating system and an
- * architecture.
+ * One build configuration entry, read as the one shape its members name: a member
+ * only a platform carries makes it a platform, the member only a project carries
+ * makes it a project, and an entry naming members of both, or of neither, is
+ * refused at the entry, because the two shapes are exclusive.
  */
+function readConfiguration(entry, at, label) {
+    if (!isRecord(entry)) {
+        throw malformed(label, at, "is not an object");
+    }
+    const platform = PLATFORM_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+    const project = Object.hasOwn(entry, PROJECT_MEMBER);
+    if (platform.length > 0 && project) {
+        throw malformed(label, at, `carries ${spell(platform)} of a platform and ${JSON.stringify(PROJECT_MEMBER)} of a ` +
+            "project, and an entry is one shape or the other");
+    }
+    if (project) {
+        return readProject(entry, at, label);
+    }
+    if (platform.length === 0) {
+        throw malformed(label, at, `names neither a platform's "os" and "arch" nor a project's ${JSON.stringify(PROJECT_MEMBER)}`);
+    }
+    return readPlatform(entry, at, label);
+}
+/** The build matrix, one entry in one shape at a time. */
 function readConfigurations(analysis, label) {
     const value = member(analysis, "configurations");
     if (value === undefined) {
@@ -147,18 +203,7 @@ function readConfigurations(analysis, label) {
     if (!Array.isArray(value)) {
         throw malformed(label, "analysis.configurations", "is not an array");
     }
-    return value.map((entry, index) => {
-        const at = `analysis.configurations[${String(index)}]`;
-        if (!isRecord(entry)) {
-            throw malformed(label, at, "is not an object");
-        }
-        return {
-            id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
-            os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
-            arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
-            tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
-        };
-    });
+    return value.map((entry, index) => readConfiguration(entry, `analysis.configurations[${String(index)}]`, label));
 }
 /**
  * The action delimiter pair: once a document names the object both members are
@@ -439,6 +484,29 @@ function checkLabels(provenance) {
  * the usage exit code.
  */
 export function resolve(inputs) {
+    const { config, provenance } = settleAll(inputs);
+    if (config.targetKind === "") {
+        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set, it has no default and is never inferred: searched " +
+            `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
+            describeSource("the central configuration", inputs.central, inputs.centralLabel));
+    }
+    checkLabels(provenance);
+    return { config, provenance };
+}
+/**
+ * The build matrix the configuration documents resolve to, every document read and
+ * refused as {@link resolve} refuses it, and nothing else required of them: which
+ * projects a run analyzes depends on the matrix alone, so a question about the
+ * projects asks no target kind.
+ */
+export function resolveMatrix(inputs) {
+    return settleAll(inputs).config.analysis.configurations;
+}
+/**
+ * Every setting the documents supply, each from the highest-ranked source carrying
+ * it, with the origin of each. The target kind is empty where no source names one.
+ */
+function settleAll(inputs) {
     const sources = readSources(inputs);
     const defaults = defaultConfig();
     const provenance = new Map();
@@ -472,11 +540,5 @@ export function resolve(inputs) {
             entryFiles: at("ts.entry_files", defaults.ts.entryFiles, (doc) => doc.entryFiles),
         },
     };
-    if (config.targetKind === "") {
-        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set, it has no default and is never inferred: searched " +
-            `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
-            describeSource("the central configuration", inputs.central, inputs.centralLabel));
-    }
-    checkLabels(provenance);
     return { config, provenance };
 }