flagrm 0.1.0 → 0.2.0

package/dist/adapters/dotnet/flow.js

@@ -0,0 +1,429 @@
+/**
+ * Follow a flag's value through C# code: the bool locals, fields and
+ * properties that hold `IsEnabled(<flag>)`, the methods that only return it
+ * (or a ternary on it), and the parameters it is passed to. Each is a name
+ * the removal has to get rid of, and that `verify` should check. Tests that
+ * call such a method with a `true`/`false` literal for the parameter are
+ * parameterized over the flag.
+ *
+ * Like the rest of discovery this is lexical (comments and strings masked,
+ * brackets matched), not a C# parser: it finds the common shapes and misses
+ * unusual ones, which the agent still records with `--name`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { computeCodeMask, escapeRegExp, isTestPath, methodNamePattern } from "../../core/scan.js";
+import { SourceText } from "../../core/source-text.js";
+import { matchBracket, toLf } from "../../core/text-utils.js";
+/** Keywords that can precede `name(` without it being a declaration or a call of `name`. */
+const KEYWORDS = new Set("new return await throw else case in is as yield out ref typeof nameof sizeof default using if while for foreach switch lock catch when var get set init and or not".split(" "));
+export function dotnetFlow(ctx, flags, evalMethods) {
+    const files = readCsFiles(ctx);
+    const code = files.filter((f) => !f.isTest);
+    const names = [];
+    const args = [];
+    const add = (name) => {
+        if (evalMethods.includes(name.name) || KEYWORDS.has(name.name))
+            return;
+        const same = (n) => n.flag === name.flag && n.name === name.name && n.kind === name.kind && n.file === name.file;
+        if (names.some(same))
+            return;
+        names.push({ ...name, project: ctx.name });
+    };
+    const declarations = methodDeclarations(code);
+    const ternaries = new Set();
+    const flagOfArgs = flagMatcher(flags);
+    const evaluators = evalMethods.length
+        ? [
+            {
+                pattern: new RegExp(`\\b(?:${evalMethods.map(methodNamePattern).join("|")})\\s*(?:<[^<>()]*>)?\\s*\\(`, "g"),
+                flagOf: (a) => flagOfArgs(firstArgument(a)),
+            },
+        ]
+        : [];
+    // Pass 1: the eval calls. Pass 2: calls of the wrapper methods pass 1 found.
+    for (let pass = 0; pass < 2; pass++) {
+        for (const f of code) {
+            for (const ev of evaluators) {
+                if (!ev.onlyIn || ev.onlyIn === f.file)
+                    findEvaluations(f, ev, add, args, ternaries);
+            }
+        }
+        // A method returning a ternary on the flag (`? "collections" : "shared folders"`) returns another
+        // value, not the flag's: a local holding its result stays after the removal.
+        const methods = names.filter((n) => n.kind === "method" && !ternaries.has(n.name));
+        if (pass === 1 || methods.length === 0)
+            break;
+        evaluators.length = 0;
+        for (const m of methods)
+            evaluators.push(...wrapperCalls(m, declarations));
+    }
+    // An instance method is recorded by its bare name: when another method has the same name, that name
+    // would match the other one's calls too.
+    for (const n of names) {
+        if (n.kind !== "method" || n.name.includes("."))
+            continue;
+        if ((declarations.get(n.name) ?? []).filter((d) => d.hasBody).length > 1)
+            n.ambiguous = true;
+    }
+    // Locals, fields and properties holding the value, passed on as an argument.
+    for (const f of code) {
+        for (const n of names.filter((x) => (x.kind === "local" || x.kind === "field" || x.kind === "property") && x.file === f.file)) {
+            for (const m of f.text.matchAll(new RegExp(`(?<![\\w$.])(?:this\\s*\\.\\s*)?${escapeRegExp(n.name)}(?![\\w$])`, "g"))) {
+                if (!f.mask[m.index])
+                    continue;
+                const arg = wholeArgument(f, m.index, m.index + m[0].length);
+                if (arg)
+                    args.push({ flag: n.flag, ...arg });
+            }
+        }
+    }
+    // The parameter each argument lands in. Only the callee's name is known, so every declaration of that
+    // name with a bool parameter there is a candidate: when they name it differently (`GetName(bool
+    // useVfo1Terminology)`, `Organization.GetName(bool includeDomain)`), which one the call reaches is
+    // unknown, so each is only suggested and its tests aren't reported.
+    const parameters = [];
+    for (const a of args) {
+        const candidates = [];
+        for (const d of declarations.get(a.callee) ?? []) {
+            const offset = a.viaDot && d.extension ? 1 : 0;
+            const p = a.label ? d.params.find((x) => x.name === a.label) : d.params[a.index + offset];
+            if (p && /^bool\??$/.test(p.type))
+                candidates.push({ d, p });
+        }
+        const ambiguous = new Set(candidates.map((c) => c.p.name)).size > 1;
+        for (const { d, p } of candidates) {
+            add({
+                flag: a.flag,
+                name: p.name,
+                kind: "parameter",
+                file: d.file,
+                line: d.line,
+                ...(ambiguous ? { ambiguous } : {}),
+            });
+            const index = d.params.indexOf(p);
+            if (!ambiguous && !parameters.some((x) => x.method === a.callee && x.index === index)) {
+                parameters.push({ flag: a.flag, method: a.callee, index, name: p.name, extension: d.extension });
+            }
+        }
+    }
+    const tests = [];
+    for (const f of files.filter((x) => x.isTest)) {
+        for (const p of parameters) {
+            for (const m of f.text.matchAll(new RegExp(`\\b${escapeRegExp(p.method)}\\s*(?:<[^<>()]*>)?\\s*\\(`, "g"))) {
+                if (!f.mask[m.index])
+                    continue;
+                const open = m.index + m[0].length - 1;
+                const close = matchBracket(f.text, f.mask, open, "(", ")");
+                if (close === -1)
+                    continue;
+                const list = splitTopLevel(f.text.slice(open + 1, close));
+                const viaDot = /\.\s*$/.test(f.text.slice(Math.max(0, m.index - 20), m.index));
+                const offset = viaDot && p.extension ? 1 : 0;
+                const named = list.find((a) => new RegExp(`^${escapeRegExp(p.name)}\\s*:`).test(a));
+                const value = (named ? named.slice(named.indexOf(":") + 1) : list[p.index - offset])?.trim();
+                if (value !== "true" && value !== "false")
+                    continue;
+                tests.push({
+                    flag: p.flag,
+                    project: ctx.name,
+                    file: f.file,
+                    line: f.source.position(m.index).line,
+                    method: p.method,
+                    parameter: p.name,
+                    value: value === "true",
+                });
+            }
+        }
+    }
+    return { names, tests };
+}
+function readCsFiles(ctx) {
+    const out = [];
+    for (const file of ctx.files) {
+        if (!file.endsWith(".cs"))
+            continue;
+        let text;
+        try {
+            text = toLf(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        out.push({
+            file,
+            text,
+            mask: computeCodeMask(text),
+            source: new SourceText(file, text),
+            isTest: isTestPath(path.relative(ctx.root, file)),
+        });
+    }
+    return out;
+}
+/** Which flag an eval call's argument names: its literal (`"NewCheckout"`) or a definition (`FeatureFlags.NewCheckout`). */
+function flagMatcher(flags) {
+    const tests = flags.map((f) => {
+        const parts = [`(['"])${escapeRegExp(f.flag)}\\1`];
+        for (const alias of f.aliases) {
+            parts.push(`(?<![\\w$])${alias.split(".").map(escapeRegExp).join("\\s*\\.\\s*")}(?![\\w$])`);
+        }
+        return { flag: f.flag, pattern: new RegExp(parts.join("|")) };
+    });
+    return (arg) => tests.find((t) => t.pattern.test(arg))?.flag;
+}
+function firstArgument(args) {
+    return splitTopLevel(args)[0] ?? "";
+}
+/**
+ * Generic type arguments right after a name (`Dictionary<string, bool>`, one
+ * level nested): their commas don't split. A `<` or `>` anywhere else is an
+ * operator (`a < b`, `x => x.Id`), not a bracket.
+ */
+const TYPE_ARGS = /^<(?:[\w\s.,?[\]]|<[\w\s.,?[\]]*>)*>/;
+/** Split an argument or parameter list at its top-level commas. */
+function splitTopLevel(list) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    let quote;
+    for (let i = 0; i < list.length; i++) {
+        const c = list[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = undefined;
+        }
+        else if (c === '"' || c === "'")
+            quote = c;
+        else if (c === "<" && /\w/.test(list[i - 1] ?? "")) {
+            const args = TYPE_ARGS.exec(list.slice(i));
+            if (args)
+                i += args[0].length - 1;
+        }
+        else if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        else if (c === "," && depth === 0) {
+            out.push(list.slice(start, i));
+            start = i + 1;
+        }
+    }
+    if (list.trim())
+        out.push(list.slice(start));
+    return out.map((s) => s.trim());
+}
+/** The receiver chain and `await` before a call: `await _featureService.` in `await _featureService.IsEnabledAsync(`. */
+const RECEIVER = /(?:\bawait\s+)?(?:(?:this|base|@?\w+)(?:\(\))?\s*[?!]?\.\s*)*$/;
+/**
+ * Each call of `ev` that evaluates a flag, and what its value goes into: a
+ * local, field or property assigned only that value, a method returning it
+ * (or a ternary on it) and nothing else, or an argument of another call.
+ */
+function findEvaluations(f, ev, add, args, ternaries) {
+    const { text, mask } = f;
+    for (const m of text.matchAll(ev.pattern)) {
+        if (!mask[m.index])
+            continue;
+        const open = m.index + m[0].length - 1;
+        const close = matchBracket(text, mask, open, "(", ")");
+        if (close === -1)
+            continue;
+        const flag = ev.flagOf(text.slice(open + 1, close));
+        if (!flag)
+            continue;
+        const start = m.index - (RECEIVER.exec(text.slice(Math.max(0, m.index - 200), m.index))?.[0].length ?? 0);
+        const line = f.source.position(m.index).line;
+        const arg = wholeArgument(f, start, close + 1);
+        if (arg) {
+            args.push({ flag, ...arg });
+            continue;
+        }
+        const boundary = statementStart(text, mask, start);
+        if (boundary === undefined)
+            continue;
+        const head = text.slice(boundary + 1, start);
+        const next = nextCode(text, mask, close + 1);
+        const holdsOnly = text[next] === ";";
+        const valueOrTernary = holdsOnly || text[next] === "?";
+        let hit;
+        if (holdsOnly && (hit = /\b(?:var|bool\??)\s+(@?\w+)\s*=\s*$/.exec(head))) {
+            const field = /\b(?:private|public|protected|internal|readonly|static)\b/.test(head);
+            add({ flag, name: hit[1], kind: field ? "field" : "local", file: f.file, line });
+        }
+        else if (holdsOnly && (hit = /(?:^|[\s(])(this\s*\.\s*)?(@?\w+)\s*=\s*$/.exec(head))) {
+            const field = Boolean(hit[1]) || hit[2].startsWith("_");
+            add({ flag, name: hit[2], kind: field ? "field" : "local", file: f.file, line });
+        }
+        else if (holdsOnly && (hit = /\bbool\??\s+(\w+)\s*=>\s*$/.exec(head))) {
+            add({ flag, name: hit[1], kind: "property", file: f.file, line });
+        }
+        else if (valueOrTernary && (hit = /(\w+)\s*(?:<[^<>()]*>)?\s*\(([^()]*)\)\s*=>\s*$/.exec(head))) {
+            const name = methodName(text, mask, boundary, head, hit[1]);
+            if (!holdsOnly)
+                ternaries.add(name);
+            add({ flag, name, kind: "method", file: f.file, line });
+        }
+        else if (valueOrTernary && /^\s*return\s+$/.test(head) && text[boundary] === "{" && onlyStatement(f, close)) {
+            const signature = /(\w+)\s*(?:<[^<>()]*>)?\s*\(([^()]*)\)\s*$/.exec(text.slice(Math.max(0, boundary - 300), boundary));
+            const outer = statementStart(text, mask, boundary);
+            if (signature && outer !== undefined) {
+                const decl = text.slice(outer + 1, boundary);
+                const name = methodName(text, mask, outer, decl, signature[1]);
+                if (!holdsOnly)
+                    ternaries.add(name);
+                add({ flag, name, kind: "method", file: f.file, line });
+            }
+        }
+    }
+}
+/**
+ * How a wrapper method found in pass 1 is called. A static one by
+ * `Class.Method(`, or by its bare name inside its own file. An instance one
+ * by its name, but only when exactly one method of that name has a body in
+ * the project: otherwise `x.Plural()` may be another class's `Plural`.
+ */
+function wrapperCalls(method, declarations) {
+    const flagOf = () => method.flag;
+    const dot = method.name.lastIndexOf(".");
+    const simple = method.name.slice(dot + 1);
+    if (dot >= 0) {
+        const owner = method.name.slice(0, dot);
+        return [
+            { pattern: new RegExp(`\\b${escapeRegExp(owner)}\\s*\\.\\s*${escapeRegExp(simple)}\\s*\\(`, "g"), flagOf },
+            { pattern: new RegExp(`(?<![\\w$.])${escapeRegExp(simple)}\\s*\\(`, "g"), flagOf, onlyIn: method.file },
+        ];
+    }
+    const bodies = (declarations.get(simple) ?? []).filter((d) => d.hasBody);
+    if (bodies.length !== 1)
+        return [];
+    return [{ pattern: new RegExp(`\\b${escapeRegExp(simple)}\\s*\\(`, "g"), flagOf }];
+}
+/** A static method is recorded as `Class.Method`, which callers outside the class write; an instance method by name. */
+function methodName(text, mask, at, declaration, name) {
+    if (!/\bstatic\b/.test(declaration))
+        return name;
+    let owner;
+    for (const m of text.slice(0, at).matchAll(/\b(?:class|struct|record)\s+(\w+)/g))
+        if (mask[m.index])
+            owner = m[1];
+    return owner ? `${owner}.${name}` : name;
+}
+/**
+ * Whether `[start, end)` is a whole argument of a call: what comes before it
+ * up to the enclosing `(` or `,` is at most a `name:` label, and a `,` or `)`
+ * follows it. Returns the callee, the argument's position and its label.
+ */
+function wholeArgument(f, start, end) {
+    const { text, mask } = f;
+    const after = nextCode(text, mask, end);
+    if (text[after] !== "," && text[after] !== ")")
+        return undefined;
+    let depth = 0;
+    let index = 0;
+    let edge = -1;
+    let open = -1;
+    for (let i = start - 1; i >= 0; i--) {
+        if (!mask[i])
+            continue;
+        const c = text[i];
+        if (c === ")" || c === "]" || c === "}")
+            depth++;
+        else if (c === "(" || c === "[" || c === "{") {
+            if (depth === 0) {
+                open = i;
+                break;
+            }
+            depth--;
+        }
+        else if (c === "," && depth === 0) {
+            if (edge === -1)
+                edge = i;
+            index++;
+        }
+        else if (c === ";" && depth === 0)
+            return undefined;
+    }
+    if (open === -1 || text[open] !== "(")
+        return undefined;
+    const before = text.slice((edge === -1 ? open : edge) + 1, start);
+    const label = /^\s*(@?\w+)\s*:\s*$/.exec(before)?.[1];
+    if (!label && before.trim())
+        return undefined;
+    const callee = /(@?\w+)\s*(?:<[^<>()]*>)?\s*$/.exec(text.slice(Math.max(0, open - 200), open));
+    if (!callee || KEYWORDS.has(callee[1]))
+        return undefined;
+    const viaDot = /\.\s*$/.test(text.slice(Math.max(0, open - 200), open - callee[0].length + 1));
+    return { callee: callee[1], index, label, viaDot };
+}
+/** The `;`, `{` or `}` that ends the previous statement, outside brackets; undefined inside an argument list. */
+function statementStart(text, mask, from) {
+    let depth = 0;
+    for (let i = from - 1; i >= 0; i--) {
+        if (!mask[i])
+            continue;
+        const c = text[i];
+        if (c === ")" || c === "]")
+            depth++;
+        else if (c === "(" || c === "[") {
+            if (depth === 0)
+                return undefined;
+            depth--;
+        }
+        else if (depth === 0 && (c === ";" || c === "{" || c === "}"))
+            return i;
+    }
+    return -1;
+}
+/** Index of the next code character that isn't whitespace. */
+function nextCode(text, mask, from) {
+    let i = from;
+    while (i < text.length && (!mask[i] || /\s/.test(text[i])))
+        i++;
+    return i;
+}
+/** Whether the statement ending after `close` is the last one in its block (`{ return X(...); }`). */
+function onlyStatement(f, close) {
+    let i = close + 1;
+    while (i < f.text.length && !(f.mask[i] && f.text[i] === ";"))
+        i++;
+    return f.text[nextCode(f.text, f.mask, i + 1)] === "}";
+}
+/** Method and constructor declarations by name, with their parameters. */
+function methodDeclarations(files) {
+    const out = new Map();
+    for (const f of files) {
+        for (const m of f.text.matchAll(/([\w<>[\]?,.]+)\s+(@?\w+)\s*(?:<[^<>()]*>)?\s*\(/g)) {
+            if (!f.mask[m.index] || KEYWORDS.has(m[1]) || KEYWORDS.has(m[2]))
+                continue;
+            const open = m.index + m[0].length - 1;
+            const close = matchBracket(f.text, f.mask, open, "(", ")");
+            if (close === -1)
+                continue;
+            const after = /^\s*(\{|=>|;|where\b|:)/.exec(f.text.slice(close + 1, close + 40))?.[1];
+            if (!after)
+                continue;
+            const raw = splitTopLevel(f.text.slice(open + 1, close));
+            const params = raw.map((p) => {
+                const plain = p
+                    .replace(/\[[^\]]*\]/g, "")
+                    .replace(/=.*$/s, "")
+                    .replace(/^\s*(?:this|ref|out|in|params|scoped)\s+/, "")
+                    .trim();
+                const word = /(@?\w+)$/.exec(plain);
+                return { type: word ? plain.slice(0, word.index).trim() : plain, name: word?.[1] ?? "" };
+            });
+            const list = out.get(m[2]) ?? [];
+            list.push({
+                file: f.file,
+                line: f.source.position(m.index).line,
+                params,
+                extension: /^\s*this\s/.test(raw[0] ?? ""),
+                hasBody: after !== ";",
+            });
+            out.set(m[2], list);
+        }
+    }
+    return out;
+}

package/dist/adapters/dotnet/index.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { discoverInText } from "../../core/discover.js";
 import { BACKEND_GLOBS } from "../../core/scan.js";
+import { dotnetFlow } from "./flow.js";
 import { dotnetUnusedDiagnostics } from "./unused.js";
 /** Discover candidate flag names (appsettings config keys, [FeatureGate] args, eval-call literals, *Flags constants/enums). */
 export function discoverDotnetFlags(ctx) {
@@ -22,6 +23,7 @@ export const dotnetAdapter = {
     id: "dotnet",
     defaultGlobs: BACKEND_GLOBS,
     discover: async (ctx) => discoverDotnetFlags(ctx),
+    flow: (ctx, flags) => dotnetFlow(ctx, flags, ctx.project.methods),
     // --no-incremental: an up-to-date project skips compiling and prints none of its
     // warnings, so the baseline's dead-code comparison would have nothing to subtract.
     defaultCommands: () => ({ build: "dotnet build --no-incremental", test: "dotnet test" }),

package/dist/adapters/dotnet/setup.js

@@ -0,0 +1,163 @@
+/**
+ * Whether this machine can build and test a .NET solution: an installed SDK
+ * that satisfies global.json, `cargo` for projects whose build runs it, Docker
+ * for test projects that use Testcontainers. And which projects a solution
+ * filter has to leave out when one of the last two is missing.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+// --- SDK -------------------------------------------------------------------------
+/** global.json's SDK request, from the nearest global.json at or above `dir` (where `dotnet` looks). */
+export function sdkRequest(dir) {
+    for (let d = path.resolve(dir);; d = path.dirname(d)) {
+        const file = path.join(d, "global.json");
+        if (fs.existsSync(file)) {
+            try {
+                const sdk = JSON.parse(fs.readFileSync(file, "utf8"))?.sdk;
+                if (typeof sdk?.version !== "string")
+                    return undefined;
+                const rollForward = typeof sdk.rollForward === "string" ? sdk.rollForward : "latestPatch";
+                return { file, version: sdk.version, rollForward };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        if (path.dirname(d) === d)
+            return undefined;
+    }
+}
+/** `8.0.403` → [8, 0, 4, 3]: major, minor, feature band, patch. Undefined for anything else. */
+function sdkParts(version) {
+    const m = /^(\d+)\.(\d+)\.(\d)(\d\d)(?:-|$)/.exec(version);
+    return m ? m.slice(1).map(Number) : undefined;
+}
+/**
+ * Whether an installed SDK satisfies the request under its rollForward policy:
+ * how many leading version parts must match the requested ones (`patch`: the
+ * feature band, `feature`: the minor, `minor`: the major, `major`: none), and
+ * the version must be at least the requested one. `disable` needs it exactly.
+ * The `latest*` policies accept the same SDKs as their plain forms; they only
+ * prefer a newer one.
+ */
+export function satisfiesSdk(installed, requested, rollForward) {
+    const have = sdkParts(installed);
+    const want = sdkParts(requested);
+    if (!have || !want)
+        return installed === requested;
+    const policy = rollForward.replace(/^latest/, "").toLowerCase();
+    if (policy === "disable")
+        return installed === requested;
+    const fixed = { patch: 3, feature: 2, minor: 1, major: 0 }[policy] ?? 3;
+    for (let i = 0; i < fixed; i++)
+        if (have[i] !== want[i])
+            return false;
+    for (let i = 0; i < 4; i++)
+        if (have[i] !== want[i])
+            return have[i] > want[i];
+    return true;
+}
+/** Why `dir` can't build with the installed SDKs, or undefined when it can (or no global.json pins one). */
+export function sdkProblem(dir, probes, root) {
+    const request = sdkRequest(dir);
+    if (!request)
+        return undefined;
+    const installed = probes.installedSdks();
+    const where = path.relative(root, request.file) || "global.json";
+    if (!installed)
+        return `\`dotnet\` is not installed; ${where} requests SDK ${request.version}`;
+    if (installed.some((v) => satisfiesSdk(v, request.version, request.rollForward)))
+        return undefined;
+    return (`${where} requests .NET SDK ${request.version} (rollForward: ${request.rollForward}); ` +
+        `installed: ${installed.join(", ") || "none"}. Install a matching SDK or change ${where}`);
+}
+/** The projects of a `.sln` (`Project(...) = "Name", "path", ...`) or `.slnx` (`<Project Path="..."/>`). */
+export function solutionProjects(solution) {
+    const text = fs.readFileSync(solution, "utf8");
+    const entries = solution.endsWith(".slnx")
+        ? [...text.matchAll(/<Project\b[^>]*\bPath\s*=\s*"([^"]+)"/g)].map((m) => m[1])
+        : [...text.matchAll(/^Project\("[^"]*"\)\s*=\s*"[^"]*",\s*"([^"]+)"/gm)].map((m) => m[1]);
+    const dir = path.dirname(solution);
+    return entries
+        .filter((entry) => /\.\w*proj$/i.test(entry))
+        .map((entry) => ({ entry, file: path.resolve(dir, entry.replace(/\\/g, "/")) }));
+}
+function projectInfo(file) {
+    let text = "";
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        // A project the solution lists but that's missing: nothing to learn from it.
+    }
+    const dir = path.dirname(file);
+    return {
+        references: [...text.matchAll(/<ProjectReference\b[^>]*\bInclude\s*=\s*"([^"]+)"/g)].map((m) => path.resolve(dir, m[1].replace(/\\/g, "/"))),
+        cargo: /<Exec\b[^>]*\bCommand\s*=\s*"[^"]*\bcargo\b/i.test(text),
+        testcontainers: /<PackageReference\b[^>]*\bInclude\s*=\s*"Testcontainers\b/i.test(text),
+    };
+}
+/**
+ * Check a solution's projects against the machine: a project whose build
+ * runs `cargo` needs it on PATH, one using Testcontainers needs Docker. Each
+ * such project is left out, and so is every project that references one,
+ * directly or not (it can't build, or can't run, without it). With `only`
+ * (the project files a solution filter keeps), the other projects aren't built
+ * and so aren't checked or kept.
+ */
+export function solutionSetup(solution, probes, root, only) {
+    const kept = only && new Set(only);
+    const projects = solutionProjects(solution).filter((p) => !kept || kept.has(p.file));
+    const info = new Map(projects.map((p) => [p.file, projectInfo(p.file)]));
+    const rel = (file) => path.relative(root, file).split(path.sep).join("/");
+    const problems = [];
+    const reasons = new Map();
+    const cargo = projects.filter((p) => info.get(p.file)?.cargo);
+    if (cargo.length && !probes.onPath("cargo")) {
+        problems.push(`\`cargo\` is not installed, and ${cargo.map((p) => rel(p.file)).join(", ")} ${cargo.length === 1 ? "runs" : "run"} it to build`);
+        for (const p of cargo)
+            reasons.set(p.file, "runs `cargo`, which is not installed");
+    }
+    const docker = projects.filter((p) => info.get(p.file)?.testcontainers);
+    if (docker.length && !probes.dockerRunning()) {
+        problems.push(`Docker is not running, and ${docker.map((p) => rel(p.file)).join(", ")} ${docker.length === 1 ? "uses" : "use"} Testcontainers`);
+        for (const p of docker)
+            reasons.set(p.file, "uses Testcontainers, and Docker is not running");
+    }
+    // Everything that references a left-out project, transitively.
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const p of projects) {
+            if (reasons.has(p.file))
+                continue;
+            const blocked = info.get(p.file)?.references.find((r) => reasons.has(r));
+            if (blocked) {
+                reasons.set(p.file, `references ${path.basename(blocked)}`);
+                changed = true;
+            }
+        }
+    }
+    const leaveOut = projects
+        .filter((p) => reasons.has(p.file))
+        .map((p) => ({ entry: p.entry, reason: reasons.get(p.file) ?? "" }));
+    return { solution, problems, leaveOut, projects };
+}
+// --- probes ----------------------------------------------------------------------
+export function realProbes(onPath) {
+    return {
+        installedSdks() {
+            // From a temp directory, so no global.json gets in the way of listing.
+            const r = spawnSync("dotnet", ["--list-sdks"], { cwd: os.tmpdir(), encoding: "utf8", timeout: 30_000 });
+            if (r.error || r.status !== 0)
+                return undefined;
+            return [...r.stdout.matchAll(/^(\S+)\s+\[/gm)].map((m) => m[1]);
+        },
+        onPath,
+        dockerRunning() {
+            const r = spawnSync("docker", ["info"], { stdio: "ignore", timeout: 20_000 });
+            return !r.error && r.status === 0;
+        },
+    };
+}