@goodbones/core 0.1.0-beta.7 → 0.1.0-beta.9

package/build/esm/core/campaigns.js

@@ -0,0 +1,778 @@
+import * as Result from "effect/Result";
+import { ImportUnresolved, PatternInvalid } from "../domain/architecture-error.js";
+import { probeTargetOf } from "./imports.js";
+import { compilePatterns } from "./patterns.js";
+import { siblingsOf } from "./structure.js";
+const targetOf = (name, field, resolves) => {
+    if (typeof resolves === "string") {
+        const compiled = compilePatterns(name, field, resolves);
+        if (Result.isFailure(compiled))
+            return Result.fail(compiled.failure);
+        const [pattern] = compiled.success;
+        return pattern === undefined
+            ? Result.fail(new PatternInvalid({ ruleName: name, field, pattern: resolves, detail: "empty pattern" }))
+            : Result.succeed({ kind: "path", pattern });
+    }
+    if ("external" in resolves)
+        return Result.succeed({ kind: "external", name: resolves.external });
+    return Result.succeed({ kind: "builtin", name: resolves.builtin });
+};
+const compileDetector = (name, detector) => {
+    const compileAll = (terms) => {
+        const compiled = [];
+        for (const term of terms) {
+            const one = compileDetector(name, term);
+            if (Result.isFailure(one))
+                return Result.fail(one.failure);
+            compiled.push(one.success);
+        }
+        return Result.succeed(compiled);
+    };
+    const patterns = (field, value) => compilePatterns(name, field, value);
+    if ("all" in detector) {
+        const terms = compileAll(detector.all);
+        return Result.isFailure(terms)
+            ? Result.fail(terms.failure)
+            : Result.succeed({ kind: "all", terms: terms.success });
+    }
+    if ("any" in detector) {
+        const terms = compileAll(detector.any);
+        return Result.isFailure(terms)
+            ? Result.fail(terms.failure)
+            : Result.succeed({ kind: "any", terms: terms.success });
+    }
+    if ("not" in detector) {
+        const term = compileDetector(name, detector.not);
+        return Result.isFailure(term)
+            ? Result.fail(term.failure)
+            : Result.succeed({ kind: "not", term: term.success });
+    }
+    if ("path" in detector) {
+        const file = patterns("path.file", detector.path.file);
+        if (Result.isFailure(file))
+            return Result.fail(file.failure);
+        const fileNot = patterns("path.fileNot", detector.path.fileNot);
+        if (Result.isFailure(fileNot))
+            return Result.fail(fileNot.failure);
+        const convention = patterns("path.convention", detector.path.convention);
+        if (Result.isFailure(convention))
+            return Result.fail(convention.failure);
+        return Result.succeed({
+            kind: "path",
+            file: file.success,
+            fileNot: fileNot.success,
+            subject: detector.path.subject ?? null,
+            convention: convention.success[0] ?? null,
+        });
+    }
+    if ("imports" in detector) {
+        const resolves = targetOf(name, "imports.resolves", detector.imports.resolves);
+        if (Result.isFailure(resolves))
+            return Result.fail(resolves.failure);
+        return Result.succeed({
+            kind: "imports",
+            resolves: resolves.success,
+            symbols: detector.imports.symbols === undefined ? null : [...detector.imports.symbols],
+        });
+    }
+    if ("exports" in detector) {
+        const named = patterns("exports.name", detector.exports.name);
+        if (Result.isFailure(named))
+            return Result.fail(named.failure);
+        return Result.succeed({
+            kind: "exports",
+            name: named.success,
+            kinds: detector.exports.kinds === undefined ? null : [...detector.exports.kinds],
+            declares: detector.exports.declares === undefined ? null : [...detector.exports.declares],
+            reexport: detector.exports.reexport ?? null,
+        });
+    }
+    if ("members" in detector) {
+        const named = patterns("members.name", detector.members.name);
+        if (Result.isFailure(named))
+            return Result.fail(named.failure);
+        const inside = patterns("members.in", detector.members.in);
+        if (Result.isFailure(inside))
+            return Result.fail(inside.failure);
+        return Result.succeed({
+            kind: "members",
+            subject: detector.members.subject,
+            name: named.success,
+            in: inside.success,
+            declares: detector.members.declares === undefined ? null : [...detector.members.declares],
+        });
+    }
+    if ("requires" in detector) {
+        return Result.succeed({ kind: "requires", templates: [...detector.requires] });
+    }
+    if ("content" in detector) {
+        // The codec refuses a bare string here; a caller that built the rule by
+        // hand can still pass one, and `new RegExp(undefined)` is `/(?:)/`, which
+        // matches every file. A detector that fires on everything is refused,
+        // not compiled.
+        const source = detector.content.regex;
+        if (typeof source !== "string") {
+            return Result.fail(new PatternInvalid({
+                ruleName: name,
+                field: "content.regex",
+                pattern: String(source),
+                detail: "a content term is { regex: <string> }",
+            }));
+        }
+        let regex;
+        try {
+            regex = new RegExp(source, "m");
+        }
+        catch (cause) {
+            return Result.fail(new PatternInvalid({
+                ruleName: name,
+                field: "content.regex",
+                pattern: detector.content.regex,
+                detail: String(cause),
+            }));
+        }
+        return Result.succeed({ kind: "content", regex });
+    }
+    if ("syntax" in detector) {
+        const where = [];
+        for (const [capture, narrowing] of Object.entries(detector.syntax.where ?? {})) {
+            const regex = patterns(`syntax.where.${capture}.regex`, narrowing.regex);
+            if (Result.isFailure(regex))
+                return Result.fail(regex.failure);
+            let binding = null;
+            if (narrowing.binding !== undefined) {
+                const resolves = targetOf(name, `syntax.where.${capture}.binding.resolves`, narrowing.binding.resolves);
+                if (Result.isFailure(resolves))
+                    return Result.fail(resolves.failure);
+                binding = {
+                    resolves: resolves.success,
+                    member: narrowing.binding.member === undefined ? null : [...narrowing.binding.member],
+                };
+            }
+            where.push({ capture, regex: regex.success[0] ?? null, binding });
+        }
+        return Result.succeed({ kind: "syntax", rule: detector.syntax.rule, where });
+    }
+    if ("report" in detector) {
+        const term = detector.report;
+        if (term.pattern !== undefined) {
+            const pattern = patterns("report.pattern", term.pattern);
+            if (Result.isFailure(pattern))
+                return Result.fail(pattern.failure);
+        }
+        return Result.succeed({
+            kind: "report",
+            command: term.command ?? null,
+            file: term.file ?? null,
+            format: term.format,
+            pattern: term.pattern ?? null,
+            codes: term.codes === undefined ? null : new Set(term.codes),
+            codesNot: new Set(term.codesNot ?? []),
+        });
+    }
+    return Result.succeed({ kind: "fn", name: detector.fn });
+};
+export const compileCampaignRule = (rule) => {
+    const scope = compilePatterns(rule.name, "scope", rule.scope);
+    if (Result.isFailure(scope))
+        return Result.fail(scope.failure);
+    const detect = compileDetector(rule.name, rule.detect);
+    if (Result.isFailure(detect))
+        return Result.fail(detect.failure);
+    return Result.succeed({
+        name: rule.name,
+        id: rule.id,
+        title: rule.title ?? null,
+        message: rule.message,
+        why: rule.why,
+        owner: rule.owner ?? null,
+        scope: scope.success,
+        unit: rule.unit,
+        detect: detect.success,
+        probes: rule.probes,
+        staleAfter: rule.staleAfter,
+        onComplete: rule.onComplete,
+    });
+};
+export const compileCampaignRules = (rules) => {
+    const compiled = [];
+    for (const rule of rules) {
+        const one = compileCampaignRule(rule);
+        if (Result.isFailure(one))
+            return Result.fail(one.failure);
+        compiled.push(one.success);
+    }
+    return Result.succeed(compiled);
+};
+const anyMatches = (patterns, value) => patterns.some((pattern) => pattern.test(value));
+export const campaignsSelecting = (rules, file) => rules.filter((rule) => anyMatches(rule.scope, file));
+// The leaf terms the compiled detector holds, in the order the evaluator
+// ranks them by cost.
+const LEAF_ORDER = [
+    "path",
+    "imports",
+    "exports",
+    "members",
+    "requires",
+    "content",
+    "syntax",
+    "report",
+    "fn",
+];
+const costOf = (detector) => {
+    switch (detector.kind) {
+        case "all":
+        case "any":
+            return Math.max(0, ...detector.terms.map(costOf));
+        case "not":
+            return costOf(detector.term);
+        default:
+            return LEAF_ORDER.indexOf(detector.kind);
+    }
+};
+const byCost = (terms) => [...terms].sort((left, right) => costOf(left) - costOf(right));
+export const leafTermsOf = (detector) => {
+    switch (detector.kind) {
+        case "all":
+        case "any":
+            return detector.terms.flatMap(leafTermsOf);
+        case "not":
+            return leafTermsOf(detector.term);
+        default:
+            return [detector.kind];
+    }
+};
+// A short, stable hash of a match's text, so a `match` subject survives the
+// declaration around it being edited and changes only when the match does.
+// FNV-1a, so the core needs no hashing library.
+const contentHash = (text) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+};
+export const matchKeyOf = (anchor, text) => `${anchor ?? ""}#${contentHash(text)}`;
+// Two matches with the same key — the same text twice in one declaration,
+// the same diagnostic twice on one line — are two entries, not one: the
+// second is `key~2`, the third `key~3`. The ordinal is positional only among
+// duplicates, so a ledger keeps its count under any edit that leaves them
+// duplicates.
+const uniqueKeys = () => {
+    const seen = new Map();
+    return (key) => {
+        const count = (seen.get(key) ?? 0) + 1;
+        seen.set(key, count);
+        return count === 1 ? key : `${key}~${String(count)}`;
+    };
+};
+const targetMatches = (target, resolved) => {
+    switch (target.kind) {
+        case "path":
+            return target.pattern.test(resolved.path);
+        case "external":
+            return resolved.kind === "external" && resolved.package === target.name;
+        case "builtin":
+            return resolved.kind === "builtin" && resolved.path === target.name;
+    }
+};
+const exportGoverned = (term, site) => {
+    if (term.kinds !== null && !term.kinds.includes(site.kind))
+        return false;
+    if (term.declares !== null && !term.declares.includes(site.declares))
+        return false;
+    if (term.reexport !== null && term.reexport !== site.reexport)
+        return false;
+    if (term.name.length > 0 && !anyMatches(term.name, site.name))
+        return false;
+    return true;
+};
+const memberGoverned = (term, site) => {
+    if (term.subject !== site.subject)
+        return false;
+    if (term.in.length > 0 && (site.in === undefined || !anyMatches(term.in, site.in)))
+        return false;
+    if (term.declares !== null &&
+        (site.declares === undefined || !term.declares.includes(site.declares))) {
+        return false;
+    }
+    if (term.name.length > 0 && !anyMatches(term.name, site.name))
+        return false;
+    return true;
+};
+const IDENTIFIER = /^[A-Za-z_$][\w$]*/;
+const ACCESSED = /^\s*\.\s*([A-Za-z_$][\w$]*)/;
+// A capture narrowed by what its root identifier is bound to: the binding
+// with that local name, the module its edge resolves to, and the name it
+// pulled across — the exported name for a named import, the member accessed
+// for a default or namespace one.
+const bindingAdmits = (narrowing, captured, input) => {
+    const root = IDENTIFIER.exec(captured)?.[0];
+    if (root === undefined)
+        return false;
+    for (const specifier of input.facts.specifiers) {
+        for (const binding of input.facts.bindings.get(specifier) ?? []) {
+            if (binding.local !== root)
+                continue;
+            const resolved = input.resolver.resolve(input.file, specifier);
+            if (Result.isFailure(resolved))
+                return false;
+            if (!targetMatches(narrowing.resolves, resolved.success))
+                return false;
+            if (narrowing.member === null)
+                return true;
+            const accessed = binding.kind === "named" ? binding.symbol : ACCESSED.exec(captured.slice(root.length))?.[1];
+            return accessed !== undefined && narrowing.member.includes(accessed);
+        }
+    }
+    return false;
+};
+const narrowed = (where, match, input) => where.every((one) => {
+    const captured = match.captures.get(one.capture);
+    if (captured === undefined)
+        return false;
+    if (one.regex !== null && !one.regex.test(captured))
+        return false;
+    if (one.binding !== null && !bindingAdmits(one.binding, captured, input))
+        return false;
+    return true;
+});
+const declarationsOf = (names, ranges = new Map()) => {
+    const set = new Set(names);
+    return {
+        level: "declaration",
+        names: set,
+        candidates: [...set].map((name) => ({
+            key: name,
+            anchor: name,
+            range: ranges.get(name) ?? null,
+        })),
+    };
+};
+const matchesOf = (candidates) => ({
+    level: "match",
+    anchors: new Set(candidates.flatMap((one) => (one.anchor === null ? [] : [one.anchor]))),
+    candidates,
+});
+const evaluateLeaf = (term, input) => {
+    switch (term.kind) {
+        case "path": {
+            if (anyMatches(term.fileNot, input.file))
+                return { level: "file", holds: false };
+            for (const pattern of term.file) {
+                const found = pattern.exec(input.file);
+                if (found === null)
+                    continue;
+                if (term.convention === null || term.subject === null) {
+                    return { level: "file", holds: true };
+                }
+                const subject = found[term.subject];
+                return { level: "file", holds: subject !== undefined && term.convention.test(subject) };
+            }
+            return { level: "file", holds: false };
+        }
+        case "imports": {
+            for (const specifier of input.facts.specifiers) {
+                if (term.symbols !== null) {
+                    const bound = input.facts.bindings.get(specifier) ?? [];
+                    const wanted = term.symbols;
+                    if (!bound.some((binding) => wanted.includes(binding.symbol)))
+                        continue;
+                }
+                const resolved = input.resolver.resolve(input.file, specifier);
+                if (Result.isFailure(resolved))
+                    continue;
+                if (targetMatches(term.resolves, resolved.success))
+                    return { level: "file", holds: true };
+            }
+            return { level: "file", holds: false };
+        }
+        case "exports":
+            return declarationsOf(input.facts.exportSites
+                .filter((site) => exportGoverned(term, site))
+                .map((site) => site.name));
+        case "members": {
+            const sites = input.facts.memberSites.filter((site) => memberGoverned(term, site));
+            // A called name sits in no declaration the facts know, so a `calls`
+            // term is a statement about the file.
+            if (term.subject === "calls")
+                return { level: "file", holds: sites.length > 0 };
+            return declarationsOf(sites.flatMap((site) => (site.in === undefined ? [] : [site.in])));
+        }
+        case "requires":
+            return {
+                level: "file",
+                holds: siblingsOf(term.templates, input.file).every((sibling) => input.fileSystem.exists(sibling)),
+            };
+        case "content":
+            return { level: "file", holds: term.regex.test(input.text) };
+        case "syntax": {
+            if (input.syntax === null)
+                return matchesOf([]);
+            const unique = uniqueKeys();
+            const candidates = [];
+            for (const match of input.syntax.findAll(term.rule)) {
+                if (!narrowed(term.where, match, input))
+                    continue;
+                candidates.push({
+                    key: unique(matchKeyOf(match.anchor, match.text)),
+                    anchor: match.anchor,
+                    range: match.range,
+                });
+            }
+            return matchesOf(candidates);
+        }
+        case "report": {
+            // Each diagnostic is a match: anchored on the declaration at its
+            // position (or none, at the top level or without a matcher), keyed by
+            // its code and a hash of its message — so an entry survives the line
+            // moving and changes when the message does.
+            const unique = uniqueKeys();
+            const candidates = [];
+            for (const diagnostic of input.reports.diagnosticsOf(specOf(term), input.file)) {
+                if (term.codes !== null && !term.codes.has(diagnostic.code))
+                    continue;
+                if (term.codesNot.has(diagnostic.code))
+                    continue;
+                const position = { line: diagnostic.line, column: diagnostic.column };
+                const anchor = input.syntax?.anchorAt(position) ?? null;
+                const code = diagnostic.code === "" ? "" : `${diagnostic.code}#`;
+                candidates.push({
+                    key: unique(`${anchor ?? ""}#${code}${contentHash(diagnostic.message)}`),
+                    anchor,
+                    range: { start: position, end: position },
+                });
+            }
+            return matchesOf(candidates);
+        }
+        case "fn": {
+            const predicate = input.functions.get(term.name);
+            if (predicate === undefined)
+                return { level: "file", holds: false };
+            const answer = predicate({
+                file: input.file,
+                text: input.text,
+                facts: input.facts,
+                syntax: input.syntax,
+            });
+            if (typeof answer === "boolean")
+                return { level: "file", holds: answer };
+            return matchesOf(answer.map((one) => ({ key: one.subject, anchor: one.subject, range: one.range ?? null })));
+        }
+        default:
+            throw new Error(`not a leaf: ${term.kind}`);
+    }
+};
+// Whether every leaf under a node answers about the file, in which case the
+// node has one boolean answer and an `all` may stop at it.
+const isFileLevel = (term, unit) => unit === "file" ||
+    leafTermsOf(term).every((leaf) => leaf !== "exports" &&
+        leaf !== "members" &&
+        leaf !== "syntax" &&
+        leaf !== "report" &&
+        leaf !== "fn");
+// Whether a leaf answer holds for one candidate. A file-level answer holds
+// for every candidate or none; a declaration-level one for the candidate
+// named (or, for a match, the one anchored there); a match-level one for the
+// candidate keyed (or, for a declaration, the one some match is anchored in).
+const holdsFor = (answer, candidate, unit) => {
+    switch (answer.level) {
+        case "file":
+            return answer.holds;
+        case "declaration":
+            return unit === "match"
+                ? candidate.anchor !== null && answer.names.has(candidate.anchor)
+                : answer.names.has(candidate.key);
+        case "match":
+            return unit === "declaration"
+                ? answer.anchors.has(candidate.key)
+                : answer.candidates.some((one) => one.key === candidate.key);
+    }
+};
+// In a `file` campaign every term is existential.
+const holdsAtAll = (answer) => answer.level === "file" ? answer.holds : answer.candidates.length > 0;
+const judge = (term, candidate, unit, evaluation) => {
+    switch (term.kind) {
+        case "all":
+            return term.terms.every((one) => judge(one, candidate, unit, evaluation));
+        case "any":
+            return term.terms.some((one) => judge(one, candidate, unit, evaluation));
+        case "not":
+            return !judge(term.term, candidate, unit, evaluation);
+        default: {
+            const answer = evaluation.leaf(term);
+            return candidate === null ? holdsAtAll(answer) : holdsFor(answer, candidate, unit);
+        }
+    }
+};
+// The first pass: evaluate the leaves that decide anything, cheapest first.
+// An `all` stops at a file-level child that fails — nothing after it can
+// rescue the conjunction, and the terms after it are the expensive ones. An
+// `any` in a `file` campaign stops at a child that holds; in the other units
+// it goes on, because the other branches are where the candidates come from.
+const prepare = (term, unit, evaluation) => {
+    switch (term.kind) {
+        case "all": {
+            for (const child of byCost(term.terms)) {
+                const verdict = prepare(child, unit, evaluation);
+                if (verdict === false)
+                    return false;
+            }
+            return null;
+        }
+        case "any": {
+            for (const child of byCost(term.terms)) {
+                const verdict = prepare(child, unit, evaluation);
+                if (verdict === true && unit === "file")
+                    return true;
+            }
+            return null;
+        }
+        case "not": {
+            const verdict = prepare(term.term, unit, evaluation);
+            return verdict === null ? null : !verdict;
+        }
+        default: {
+            if (!isFileLevel(term, unit)) {
+                evaluation.leaf(term);
+                return null;
+            }
+            return holdsAtAll(evaluation.leaf(term));
+        }
+    }
+};
+const FILE_CANDIDATE = { key: "", anchor: null, range: null };
+const evaluationOf = (input) => {
+    const answers = new Map();
+    return {
+        answers,
+        leaf: (term) => {
+            const found = answers.get(term);
+            if (found !== undefined)
+                return found;
+            const answer = evaluateLeaf(term, input);
+            answers.set(term, answer);
+            return answer;
+        },
+    };
+};
+const universeOf = (evaluation, unit) => {
+    const byKey = new Map();
+    for (const answer of evaluation.answers.values()) {
+        if (answer.level === "file")
+            continue;
+        if (unit === "declaration" && answer.level === "match") {
+            // A match sources the declaration it sits in; one at the top level of
+            // the file sits in none and sources nothing.
+            for (const one of answer.candidates) {
+                if (one.anchor === null || byKey.has(one.anchor))
+                    continue;
+                byKey.set(one.anchor, { key: one.anchor, anchor: one.anchor, range: one.range });
+            }
+            continue;
+        }
+        if (unit === "match" && answer.level === "declaration")
+            continue;
+        for (const one of answer.candidates)
+            if (!byKey.has(one.key))
+                byKey.set(one.key, one);
+    }
+    return [...byKey.values()].sort((left, right) => left.key.localeCompare(right.key));
+};
+const hitOf = (rule, file, candidate) => ({
+    violation: {
+        kind: "campaign",
+        ruleName: rule.name,
+        message: rule.message,
+        file,
+        subject: rule.unit === "file" ? null : candidate.key,
+    },
+    campaign: rule.id,
+    ...(candidate.range === null ? {} : { range: candidate.range }),
+});
+export const evaluateCampaign = (rule, input) => {
+    const evaluation = evaluationOf(input);
+    const verdict = prepare(rule.detect, rule.unit, evaluation);
+    if (rule.unit === "file") {
+        const holds = verdict ?? judge(rule.detect, null, "file", evaluation);
+        return holds ? [hitOf(rule, input.file, FILE_CANDIDATE)] : [];
+    }
+    if (verdict === false)
+        return [];
+    return universeOf(evaluation, rule.unit)
+        .filter((candidate) => judge(rule.detect, candidate, rule.unit, evaluation))
+        .map((candidate) => hitOf(rule, input.file, candidate));
+};
+// What a `report` term asks its source for: the command or file, the format
+// and, for `regex`, the pattern. The codes are the term's own filter.
+const specOf = (term) => ({
+    ...(term.command === null ? {} : { command: term.command }),
+    ...(term.file === null ? {} : { file: term.file }),
+    format: term.format,
+    ...(term.pattern === null ? {} : { pattern: term.pattern }),
+});
+// Every distinct report the campaigns name, for a host that asks for them
+// before any file: the plugin does, at load, because a `command` forks the
+// process that asks, and the linter's process is one Linux can refuse to
+// fork once it is linting — its per-thread AST buffers merge into a mapping
+// larger than the machine has to give, and the heuristic overcommit mode
+// refuses that at fork. At load, the process is small.
+export const reportSpecsOf = (rules) => {
+    const seen = new Map();
+    const walk = (detector) => {
+        switch (detector.kind) {
+            case "all":
+            case "any":
+                for (const term of detector.terms)
+                    walk(term);
+                return;
+            case "not":
+                walk(detector.term);
+                return;
+            case "report": {
+                const spec = specOf(detector);
+                seen.set(JSON.stringify(spec), spec);
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    for (const rule of rules)
+        walk(rule.detect);
+    return [...seen.values()];
+};
+export const evaluateCampaigns = (selected, input) => selected.flatMap((rule) => evaluateCampaign(rule, input));
+const describeTerm = (term) => {
+    switch (term.kind) {
+        case "path":
+            return `path ${term.file.map((one) => `/${one.source}/`).join(" | ")}`;
+        case "imports":
+            return `imports ${describeTarget(term.resolves)}${term.symbols === null ? "" : ` { ${term.symbols.join(", ")} }`}`;
+        case "exports":
+            return `exports${term.name.length === 0 ? "" : ` ${term.name.map((one) => `/${one.source}/`).join(" | ")}`}${term.kinds === null ? "" : ` [${term.kinds.join(", ")}]`}`;
+        case "members":
+            return `members (${term.subject})${term.name.length === 0 ? "" : ` ${term.name.map((one) => `/${one.source}/`).join(" | ")}`}`;
+        case "requires":
+            return `requires ${term.templates.join(", ")}`;
+        case "content":
+            return `content /${term.regex.source}/`;
+        case "syntax":
+            return `syntax ${JSON.stringify(term.rule)}`;
+        case "report":
+            return `report ${term.format} ${term.command === null ? `file ${term.file ?? ""}` : `\`${term.command}\``}${term.codes === null ? "" : ` [${[...term.codes].join(", ")}]`}`;
+        case "fn":
+            return `fn ${term.name}`;
+        default:
+            return term.kind;
+    }
+};
+const describeTarget = (target) => {
+    switch (target.kind) {
+        case "path":
+            return `/${target.pattern.source}/`;
+        case "external":
+            return `external ${target.name}`;
+        case "builtin":
+            return `builtin ${target.name}`;
+    }
+};
+export const explainCampaign = (rule, input) => {
+    const evaluation = evaluationOf(input);
+    const lines = [];
+    const walk = (term, negated) => {
+        switch (term.kind) {
+            case "all":
+            case "any":
+                for (const one of term.terms)
+                    walk(one, negated);
+                return;
+            case "not":
+                walk(term.term, !negated);
+                return;
+            default: {
+                const answer = evaluation.leaf(term);
+                lines.push({
+                    term: `${negated ? "not " : ""}${describeTerm(term)}`,
+                    answer: holdsAtAll(answer),
+                    ...(answer.level === "file" ? {} : { count: answer.candidates.length }),
+                });
+            }
+        }
+    };
+    walk(rule.detect, false);
+    return lines;
+};
+// The input a probe stands in for: its edges answer the resolver, its files
+// the file system, its source the extractor and the matcher.
+const NOTHING = {
+    specifiers: [],
+    bindings: new Map(),
+    memberSites: [],
+    exportSites: [],
+};
+export const probeInputOf = (probe, extractor, matcher, functions) => {
+    const edges = probe.edges ?? {};
+    const files = new Set(probe.files ?? []);
+    const text = probe.source ?? "";
+    // The probe's diagnostics, one-based as written, on the probe's own file.
+    const reported = (probe.report ?? []).map((one) => ({
+        file: probe.path,
+        line: Math.max(0, one.line - 1),
+        column: Math.max(0, (one.column ?? 1) - 1),
+        code: one.code ?? "",
+        message: one.message ?? "",
+    }));
+    return {
+        file: probe.path,
+        text,
+        facts: probe.source === undefined ? NOTHING : extractor.factsOf(probe.path, probe.source),
+        resolver: {
+            resolve: (fromFile, specifier) => {
+                const target = edges[specifier];
+                return target === undefined
+                    ? Result.fail(new ImportUnresolved({ fromFile, specifier, detail: "not among the probe's edges" }))
+                    : Result.succeed(probeTargetOf(target));
+            },
+        },
+        fileSystem: { exists: (at) => files.has(at), readText: () => null },
+        syntax: probe.source === undefined || matcher === null ? null : matcher.parse(probe.path, text),
+        functions,
+        reports: { diagnosticsOf: (_spec, file) => (file === probe.path ? reported : []) },
+    };
+};
+// Every campaign must fire on each of its `fires` probes and stay silent on
+// each of its `ignores` — the same vacuity check every family makes, with
+// the second half added because a campaign's detector is composed, and the
+// term that admits too much is the one the author wants named.
+export const campaignsFailingTheirProbe = (rules, extractor, matcherFor, functions) => {
+    const failed = [];
+    for (const rule of rules) {
+        const check = (probe, expected) => {
+            if (!anyMatches(rule.scope, probe.path)) {
+                failed.push({ name: rule.name, probe, expected, outOfScope: true });
+                return;
+            }
+            const input = probeInputOf(probe, extractor, matcherFor(probe.path), functions);
+            const hits = evaluateCampaign(rule, input);
+            if (expected === "fires" && hits.length === 0)
+                failed.push({ name: rule.name, probe, expected });
+            if (expected === "ignores" && hits.length > 0) {
+                const admitting = explainCampaign(rule, input).find((line) => line.answer);
+                failed.push({
+                    name: rule.name,
+                    probe,
+                    expected,
+                    ...(admitting === undefined ? {} : { admittedBy: admitting.term }),
+                });
+            }
+        };
+        for (const probe of rule.probes.fires)
+            check(probe, "fires");
+        for (const probe of rule.probes.ignores)
+            check(probe, "ignores");
+    }
+    return failed;
+};
+//# sourceMappingURL=campaigns.js.map