@cplieger/deadset-ts 2.2.0 → 2.3.0

package/dist/src/references.js

@@ -1,4 +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 { SymbolFlags } from "@typescript/native/unstable/sync";
+import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
 import { byPosition, renderPosition } from "./position.js";
 /**
@@ -31,21 +33,6 @@ const ASSIGNMENTS = new Set([
     SyntaxKind.QuestionQuestionEqualsToken,
     SyntaxKind.CaretEqualsToken,
 ]);
-/**
- * The declaration forms that name something declared elsewhere. Each is a link rather
- * than a declaration of what it names, so a reference through one names the next link
- * and, at the end of the chain, the declaration itself: a re-export something imports
- * is used, and so is the declaration behind it.
- */
-const ALIASES = new Set([
-    SyntaxKind.ImportClause,
-    SyntaxKind.ImportEqualsDeclaration,
-    SyntaxKind.ImportSpecifier,
-    SyntaxKind.NamespaceImport,
-    SyntaxKind.ExportAssignment,
-    SyntaxKind.ExportSpecifier,
-    SyntaxKind.NamespaceExport,
-]);
 /** Whether one node is an identifier or a private name, the two forms a name takes. */
 function isName(node) {
     return node.kind === SyntaxKind.Identifier || node.kind === SyntaxKind.PrivateIdentifier;
@@ -197,62 +184,6 @@ function sitesOf(file, declarations, fileId) {
     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");
-}
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
  * vocabulary spells, which cannot carry a pattern, so a rule is named by the place of
@@ -284,7 +215,7 @@ 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 reached = new Map();
@@ -303,11 +234,17 @@ export function references(project, held, targetRoot, options) {
      * is the declaration behind it, so both are named; a link this project does not
      * declare is stepped over rather than recorded.
      *
-     * A declaration handle carries the file it is in and the syntax it is written as, so
-     * both questions the walk asks of a declaration are 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.
+     * 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);
@@ -320,9 +257,8 @@ export function references(project, held, targetRoot, options) {
         let stepped = false;
         while (at !== undefined && !walked.has(at.id)) {
             walked.add(at.id);
-            let alias = false;
+            const alias = (at.flags & SymbolFlags.Alias) !== 0;
             for (const handle of at.declarations) {
-                alias = alias || ALIASES.has(handle.kind);
                 if (!ownFiles.has(handle.path)) {
                     continue;
                 }

package/dist/src/roots.js

@@ -0,0 +1,345 @@
+/**
+ * The root set of one project: every declaration the analysis keeps live without a
+ * reference, and why.
+ *
+ * A root makes its declaration live under REACHABILITY and plays no part in
+ * reference counting, which asks only whether some declaration of the loaded graph
+ * names it. The two relations are different sets, so an exported declaration that
+ * something outside the program reaches is live under the first and still a
+ * candidate under the second.
+ */
+import { REPOSITORY_DOCUMENT } from "./config.js";
+import { entryPoints } from "./entry-points.js";
+import { globExpression } from "./glob.js";
+import { nodeKey } from "./inventory.js";
+import { byPosition } from "./position.js";
+import { sourceFilesOf } from "./source-files.js";
+/** The code the Contract gives a configured root that matches nothing. */
+const UNMATCHED_ROOT_CODE = "DS1704";
+/** The subject kind a finding under that code carries, from the Contract's vocabulary. */
+const UNMATCHED_ROOT_SUBJECT = "root";
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+/** Whether a configured string carries either special character. */
+function isPattern(text) {
+    return text.includes("*") || text.includes("?");
+}
+/**
+ * Whether ref matches a pattern whose only special characters are `*`, which stands
+ * for any run of characters including the solidus, and `?`, which stands for exactly
+ * one character counted as a code point. A star keeps the position it last stood at,
+ * so the shortest run it can stand for is tried first.
+ */
+function matchGlob(pattern, ref) {
+    let next = 0;
+    let star = -1;
+    let resume = 0;
+    let at = 0;
+    while (at < ref.length) {
+        if (next < pattern.length && (pattern[next] === "?" || pattern[next] === ref[at])) {
+            next += 1;
+            at += 1;
+        }
+        else if (next < pattern.length && pattern[next] === "*") {
+            star = next;
+            resume = at;
+            next += 1;
+        }
+        else if (star >= 0) {
+            resume += 1;
+            next = star + 1;
+            at = resume;
+        }
+        else {
+            return false;
+        }
+    }
+    while (next < pattern.length && pattern[next] === "*") {
+        next += 1;
+    }
+    return next === pattern.length;
+}
+/**
+ * Whether one configured string names the symbol reference ref. A string carrying
+ * neither special character names only the reference it spells.
+ *
+ * Both sides are read as code points: a character outside the basic plane is two
+ * string units, and `?` stands for one character.
+ */
+export function matchRef(pattern, ref) {
+    if (!isPattern(pattern)) {
+        return pattern === ref;
+    }
+    return matchGlob(Array.from(pattern), Array.from(ref));
+}
+/** Two strings ordered bytewise, which is the order every set of a run is read in. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/** The members of one declaration, indexed by the container that holds them. */
+function childrenOf(held) {
+    const byParent = new Map();
+    for (const symbol of held.symbols) {
+        const siblings = byParent.get(symbol.parent);
+        if (siblings === undefined) {
+            byParent.set(symbol.parent, [symbol]);
+        }
+        else {
+            siblings.push(symbol);
+        }
+    }
+    return byParent;
+}
+/**
+ * The roots one project holds, and every configured string that named nothing in it.
+ *
+ * A file a manifest member, an entry-file pattern or a tool's configuration names
+ * is a root with everything its module exports: each name of the module's export
+ * table, and where a name is a re-export, every link of the chain to the declaration
+ * it carries, so a re-exported declaration is a root of the file that publishes it.
+ * A file a runtime executes without reading its exports, a test file or a worker, is
+ * a root by itself.
+ */
+export function roots(project, held, targetRoot, options) {
+    const files = sourceFilesOf(project, targetRoot);
+    const declared = held.declarations;
+    const fileIds = new Map();
+    for (const file of files.byName.values()) {
+        const id = declared.get(nodeKey(file, file));
+        if (id !== undefined) {
+            fileIds.set(file.fileName, id);
+        }
+    }
+    const found = new Map();
+    const add = (id, kind, source) => {
+        found.set([id, kind, source].join("\u0000"), { id, kind, source });
+    };
+    const entered = [];
+    const enter = (file, kind, source, exports) => {
+        entered.push({ file, kind, source, exports });
+    };
+    const published = [];
+    const publishes = (entry) => entry.published &&
+        (options.manifest.declaresExports ? entry.member.startsWith("exports") : true);
+    for (const entry of options.manifest.entries) {
+        for (const file of files.named(entry.path)) {
+            enter(file, entry.role === "run" ? "manifest-binary" : "manifest-entry", entry.member, true);
+            if (options.publishedAPI && publishes(entry)) {
+                published.push(file);
+            }
+        }
+    }
+    for (const pattern of options.entryFiles) {
+        const expression = globExpression(pattern);
+        for (const [path, file] of files.byPath) {
+            if (expression.test(path)) {
+                enter(file, "entry-file", pattern, true);
+            }
+        }
+    }
+    for (const point of entryPoints(project, files, options.testFiles)) {
+        enter(point.file, point.rule, point.source, point.exports);
+    }
+    const exportsOf = exportTables(project, held, [...entered.filter((entry) => entry.exports).map((entry) => entry.file), ...published], files.byName);
+    for (const entry of entered) {
+        const id = fileIds.get(entry.file.fileName);
+        if (id === undefined) {
+            continue;
+        }
+        add(id, entry.kind, entry.source);
+        if (entry.exports) {
+            for (const exported of exportsOf.get(entry.file.fileName) ?? []) {
+                add(exported, entry.kind, entry.source);
+            }
+        }
+    }
+    if (options.publishedAPI) {
+        for (const id of publishedAPI(published, exportsOf, held)) {
+            add(id, "published-api", "");
+        }
+    }
+    const unmatched = configured(held, options.patterns, add);
+    const sites = new Map(held.symbols.map((symbol) => [symbol.id, symbol.position]));
+    const ordered = [...found.values()].sort((a, b) => {
+        const left = sites.get(a.id);
+        const right = sites.get(b.id);
+        const site = left === undefined || right === undefined ? 0 : byPosition(left, right);
+        return site || compare(a.kind, b.kind) || compare(a.source, b.source);
+    });
+    return { configFile: project.configFile, liveUnderReachability: ordered, unmatched };
+}
+/**
+ * Every declaration each file's module exports, by the file's name: the declaration
+ * each name of the export table is, and every link of a re-export's chain. A name
+ * whose declaration is outside the project's own files belongs to another program
+ * and names nothing here.
+ *
+ * One batch resolves every file to its module and one request per module reads
+ * its export table, star re-exports resolved into it. A file that is no module
+ * exports nothing.
+ */
+function exportTables(project, held, wanted, ownFiles) {
+    const unique = [...new Map(wanted.map((file) => [file.fileName, file])).values()];
+    const tables = new Map();
+    if (unique.length === 0) {
+        return tables;
+    }
+    const modules = project.symbolsAt(unique.map((file) => project.handle(file)));
+    const chains = new Map();
+    const chainOf = (symbol) => {
+        const cached = chains.get(symbol.id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const ids = [];
+        const walked = new Set();
+        let at = symbol;
+        while (at !== undefined && !walked.has(at.id)) {
+            walked.add(at.id);
+            for (const handle of at.declarations) {
+                if (!ownFiles.has(handle.path)) {
+                    continue;
+                }
+                const node = project.declarationAt(handle)?.node;
+                const id = node === undefined
+                    ? undefined
+                    : held.declarations.get(nodeKey(node.getSourceFile(), node));
+                if (id !== undefined && !ids.includes(id)) {
+                    ids.push(id);
+                }
+            }
+            at = project.aliasStepOf(at);
+        }
+        chains.set(symbol.id, ids);
+        return ids;
+    };
+    unique.forEach((file, index) => {
+        const module = modules[index];
+        if (module === undefined) {
+            tables.set(file.fileName, []);
+            return;
+        }
+        const ids = new Set();
+        for (const exported of project.checker.getExportsOfModule(module)) {
+            for (const id of chainOf(exported)) {
+                ids.add(id);
+            }
+        }
+        tables.set(file.fileName, [...ids]);
+    });
+    return tables;
+}
+/** The kinds of container whose export table, not its members' visibility, says what it publishes. */
+const EXPORTING_CONTAINERS = new Set(["file", "namespace"]);
+/**
+ * Every declaration a consumer of the library can name: what the published files
+ * export, and below each, the members a consumer reaches through it.
+ *
+ * The published files are the ones `exports` reaches where the manifest declares
+ * one, because a package that declares `exports` has said exactly what a consumer may
+ * import; where it declares none, they are the ones the members that preceded it
+ * name. Below a published module or namespace the walk follows what its export table
+ * names; below any other published declaration it follows every member a consumer
+ * can write: a public one, and a protected one, which a consumer's subclass names. A
+ * private member is not published, nor is anything below one, and a type parameter
+ * is not published either, because a consumer supplies a type argument by position.
+ *
+ * A published file is not itself published. A consumer imports a module and names
+ * what it exports; the file is a root because the manifest names it, which is a
+ * different reason.
+ */
+function publishedAPI(published, exportsOf, held) {
+    const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+    const children = childrenOf(held);
+    const reached = new Set();
+    const pending = [];
+    for (const file of published) {
+        for (const id of exportsOf.get(file.fileName) ?? []) {
+            if (byId.get(id)?.kind === "file") {
+                pending.push(id);
+            }
+            else if (!reached.has(id)) {
+                reached.add(id);
+                pending.push(id);
+            }
+        }
+    }
+    for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+        const exporting = EXPORTING_CONTAINERS.has(byId.get(next)?.kind ?? "");
+        for (const member of children.get(next) ?? []) {
+            const reachable = exporting
+                ? member.exported
+                : member.visibility !== "private" && member.visibility !== "private-name";
+            if (member.kind === "type-parameter" || reached.has(member.id) || !reachable) {
+                continue;
+            }
+            reached.add(member.id);
+            pending.push(member.id);
+        }
+    }
+    return [...reached];
+}
+/**
+ * Keeps every declaration the configuration names and returns every string that
+ * named none, in configuration order. A string the configuration lists twice is one
+ * configured root.
+ */
+function configured(held, patterns, add) {
+    const unmatched = [];
+    for (const pattern of new Set(patterns)) {
+        const kind = isPattern(pattern) ? "pattern" : "configured";
+        let matched = false;
+        for (const symbol of held.symbols) {
+            if (matchRef(pattern, symbol.ref)) {
+                add(symbol.id, kind, pattern);
+                matched = true;
+            }
+        }
+        if (!matched) {
+            unmatched.push(pattern);
+        }
+    }
+    return unmatched;
+}
+/**
+ * Every configured string that named no declaration in ANY project of the run, in
+ * configuration order and each once.
+ *
+ * A finding about a configured root is about the configuration and not about a
+ * declaration, so there is one per run: a string that names a declaration of one
+ * project has named something, and the projects it named nothing in are not a
+ * finding. A run with no project names nothing with any of them.
+ */
+export function unmatchedEverywhere(patterns, perProject) {
+    return [...new Set(patterns)].filter((pattern) => perProject.every((project) => project.unmatched.includes(pattern)));
+}
+/**
+ * The findings a run reports for the configured strings that named nothing.
+ *
+ * `document` is the path of the document that declared the roots, below the target
+ * root; where the run read them from no document of the target it is empty and the
+ * finding names the conventional repository configuration, which is the document a
+ * maintainer writes a configured root in. Every finding of one run sits at that
+ * document's first position: the roots are written as an array whose members carry
+ * no line of their own, so the string each finding names is what tells one from
+ * another.
+ */
+export function unmatchedRoots(sources, document) {
+    const position = {
+        path: document === "" ? REPOSITORY_DOCUMENT : document,
+        line: DOCUMENT_POSITION,
+        column: DOCUMENT_POSITION,
+        endLine: DOCUMENT_POSITION,
+    };
+    return sources.map((source) => ({
+        code: UNMATCHED_ROOT_CODE,
+        position,
+        symbol: { ref: source, kind: UNMATCHED_ROOT_SUBJECT, name: source, sizeLines: 1 },
+        message: isPattern(source)
+            ? "configured root pattern matches no symbol of the inventory"
+            : "configured root matches no symbol of the inventory",
+    }));
+}

package/dist/src/run.js

@@ -1,4 +1,5 @@
-import { ConfigError } from "./config.js";
+import { runRoots } from "./analysis.js";
+import { ConfigError, REPOSITORY_DOCUMENT } from "./config.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
 import { joinPath, resolvePath } from "./paths.js";
 import { printConfig } from "./print.js";
@@ -6,10 +7,9 @@ import { resolve } from "./resolve.js";
 import { readScope, ScopeError, scopeForDir } from "./scope.js";
 import { diagnosticsOf, openEngine, runSession } from "./session.js";
 import { CONTRACT_VERSION } from "./version.js";
-/** The repository configuration's name at the target root. */
-const REPOSITORY_DOCUMENT = "deadset.json";
 /** 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;
 const VERBS = [
@@ -171,6 +171,9 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     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);
+    }
     if (verb !== undefined && VERBS.includes(verb)) {
         err.write(`deadset-ts: ${verb} is not implemented\n`);
         return EXIT_USAGE;
@@ -227,6 +230,48 @@ function printProjectsVerb(args, out, err, host, openClient) {
         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);
+    }
+}
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error, err) {
     if (error instanceof ConfigError) {

package/dist/src/session.js

@@ -1,4 +1,4 @@
-import { API } from "@typescript/native/unstable/sync";
+import { API, SymbolFlags } from "@typescript/native/unstable/sync";
 import { isIdentifier } from "@typescript/native/unstable/ast";
 /**
  * Opens the compiler client the analysis reads through.
@@ -53,6 +53,11 @@ function viewOf(project) {
         resolvedSymbolAt: ({ node }) => isIdentifier(node) ? project.checker.getResolvedSymbol(node) : undefined,
         shorthandValueAt: ({ node }) => project.checker.getShorthandAssignmentValueSymbol(node),
         aliasStepOf: (symbol) => {
+            // The step is asked of an alias only: asked of any other symbol, the compiler
+            // fails an assertion and the session ends.
+            if ((symbol.flags & SymbolFlags.Alias) === 0) {
+                return undefined;
+            }
             const held = project.checker.getImmediateAliasedSymbol(symbol);
             // An alias that resolves to nothing answers with the checker's own unknown
             // symbol, which declares nothing; a symbol that is no alias answers with