@cplieger/deadset-ts 2.2.1 → 3.0.0

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,15 +1,15 @@
-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";
-import { resolve } from "./resolve.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 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;
@@ -194,21 +197,25 @@ function printConfigVerb(args, out, err, host) {
     }
 }
 /**
- * Writes the compiler configuration of every project one run analyzes, one per
- * line, in discovery order, having read each project's diagnostics first.
+ * 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.
  */
 function printProjectsVerb(args, out, err, host, openClient) {
     let engine;
     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);
+        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 project.configFile;
+            return ids.get(project.configFile) ?? project.configFile;
         });
         if (failures.length > 0) {
             for (const line of failures) {
@@ -217,8 +224,8 @@ function printProjectsVerb(args, out, err, host, openClient) {
             err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
             return EXIT_FAILURE;
         }
-        for (const configFile of projects) {
-            out.write(`${configFile}\n`);
+        for (const id of projects) {
+            out.write(`${id}\n`);
         }
         return EXIT_CLEAN;
     }
@@ -227,6 +234,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/schema.js

@@ -19,7 +19,7 @@ export const SCHEMA_ROOT = {
                 consumer_tests: leaf,
                 configurations: {
                     kind: "list",
-                    members: { id: leaf, os: leaf, arch: leaf, tags: leaf },
+                    members: { id: leaf, os: leaf, arch: leaf, tags: leaf, project: leaf },
                 },
                 matrix: { kind: "section", members: { complete: leaf } },
                 template_dirs: leaf,

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

package/dist/src/source-files.js

@@ -0,0 +1,122 @@
+/**
+ * The target's own source files of one project, looked up the ways a path written
+ * in a document or a string names one: as the file itself, or as a file the
+ * compiler emits from it.
+ */
+import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.js";
+/** The source extensions the compiler emits each output extension from. */
+const EMITTED = [
+    { emitted: ".d.ts", sources: [".ts", ".tsx"] },
+    { emitted: ".d.mts", sources: [".mts"] },
+    { emitted: ".d.cts", sources: [".cts"] },
+    { emitted: ".js", sources: [".ts", ".tsx"] },
+    { emitted: ".jsx", sources: [".tsx"] },
+    { emitted: ".mjs", sources: [".mts"] },
+    { emitted: ".cjs", sources: [".cts"] },
+];
+/** The one character a subpath pattern of a manifest's `exports` holds. */
+const SUBPATH_WILDCARD = "*";
+/** One path with its extension replaced, where it carries the one named. */
+function reExtended(path, emitted, source) {
+    return path.endsWith(emitted) ? path.slice(0, path.length - emitted.length) + source : undefined;
+}
+/**
+ * The longest directory every path shares, which is the directory the compiler
+ * emits from where the configuration declares no root directory.
+ */
+function commonDirectory(paths) {
+    const first = paths[0];
+    if (first === undefined) {
+        return "";
+    }
+    let common = dirnamePath(first).split("/");
+    for (const path of paths.slice(1)) {
+        const segments = dirnamePath(path).split("/");
+        let shared = 0;
+        while (shared < common.length &&
+            shared < segments.length &&
+            common[shared] === segments[shared]) {
+            shared += 1;
+        }
+        common = common.slice(0, shared);
+    }
+    return common.join("/");
+}
+/**
+ * Whether one path is what a subpath pattern stands for: the text before the
+ * wildcard, any run of characters including the solidus, then the text after it.
+ */
+function matchesSubpath(pattern, path) {
+    const at = pattern.indexOf(SUBPATH_WILDCARD);
+    const before = pattern.slice(0, at);
+    const after = pattern.slice(at + SUBPATH_WILDCARD.length);
+    return (path.length >= before.length + after.length && path.startsWith(before) && path.endsWith(after));
+}
+/**
+ * The lookups over one project's own files.
+ *
+ * A path that names an emitted file is read back to the source the project would
+ * emit it from through the project's own emit mapping and nothing else: the
+ * extension is one the compiler emits from a source extension, and a path below the
+ * output directory is read below the directory the compiler emits from, which the
+ * configuration declares or which is the directory every input file shares.
+ */
+export function sourceFilesOf(project, targetRoot) {
+    const byName = new Map();
+    const byPath = new Map();
+    for (const file of project.ownSourceFiles()) {
+        byName.set(file.fileName, file);
+        const path = relativePath(targetRoot, file.fileName);
+        if (path !== undefined) {
+            byPath.set(path, file);
+        }
+    }
+    const options = project.program.getCompilerOptions();
+    const configDir = dirnamePath(project.configFile);
+    const at = (option) => option === undefined ? undefined : resolvePath(configDir, option);
+    const outDir = at(options.outDir);
+    const declarationDir = at(options.declarationDir);
+    const sourceDir = at(options.rootDir) ?? commonDirectory([...byName.keys()]);
+    /** One path read below the directory the compiler emits from, where it is below the one it emits to. */
+    const fromEmit = (path, emitted) => {
+        const emitDir = emitted.startsWith(".d.") ? (declarationDir ?? outDir) : outDir;
+        if (emitDir === undefined) {
+            return undefined;
+        }
+        const below = relativePath(emitDir, path);
+        return below === undefined ? undefined : joinPath(sourceDir, below);
+    };
+    /** The source paths one written path may stand for, the path itself first. */
+    const candidates = (path) => {
+        const found = [path];
+        for (const { emitted, sources } of EMITTED) {
+            const mapped = fromEmit(path, emitted);
+            for (const source of sources) {
+                for (const from of [path, mapped]) {
+                    const candidate = from === undefined ? undefined : reExtended(from, emitted, source);
+                    if (candidate !== undefined) {
+                        found.push(candidate);
+                    }
+                }
+            }
+        }
+        return found;
+    };
+    return {
+        byPath,
+        byName,
+        named: (path) => {
+            if (!path.includes(SUBPATH_WILDCARD)) {
+                for (const candidate of candidates(path)) {
+                    const held = byName.get(candidate);
+                    if (held !== undefined) {
+                        return [held];
+                    }
+                }
+                return [];
+            }
+            const patterns = candidates(path).filter((candidate) => candidate.includes(SUBPATH_WILDCARD));
+            return [...byName.values()].filter((file) => patterns.some((pattern) => matchesSubpath(pattern, file.fileName)));
+        },
+    };
+}