@adversarylabs/sdk 0.1.3

package/dist/index.js

@@ -0,0 +1,1305 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+export const DEFAULT_INPUT_PATH = "/adversary/input.json";
+export const DEFAULT_OUTPUT_PATH = "/adversary/output.json";
+export const ADVERSARY_RUN_PROTOCOL_VERSION = 1;
+const verboseValues = new Set(["1", "true", "TRUE", "yes", "YES"]);
+export const Severity = {
+    Info: "info",
+    Low: "low",
+    Medium: "medium",
+    High: "high",
+    Critical: "critical",
+};
+export const DEFAULT_SEVERITY_GUIDANCE = [
+    {
+        severity: Severity.Info,
+        guidance: "Interesting observations.",
+    },
+    {
+        severity: Severity.Low,
+        guidance: "Reasonable engineering improvements.",
+    },
+    {
+        severity: Severity.Medium,
+        guidance: "Issues likely to create operational problems.",
+    },
+    {
+        severity: Severity.High,
+        guidance: "Security, correctness, or reliability risks.",
+    },
+    {
+        severity: Severity.Critical,
+        guidance: "Immediate production risk.",
+    },
+];
+export const Confidence = {
+    Low: "low",
+    Medium: "medium",
+    High: "high",
+};
+export const DEFAULT_CONFIDENCE_THRESHOLDS = {
+    medium: 0.6,
+    high: 0.85,
+};
+export class RuleRegistry {
+    rules = new Map();
+    register(rule) {
+        assertRuleDefinition(rule);
+        this.rules.set(rule.id, rule);
+    }
+    lookup(ruleId) {
+        return this.rules.get(ruleId);
+    }
+    has(ruleId) {
+        return this.rules.has(ruleId);
+    }
+}
+export const ruleRegistry = new RuleRegistry();
+export function defineRule(rule) {
+    ruleRegistry.register(rule);
+}
+export const log = {
+    debug(message) {
+        if (isVerbose()) {
+            writeLog("debug", message);
+        }
+    },
+    info(message) {
+        if (isVerbose()) {
+            writeLog("info", message);
+        }
+    },
+    warn(message) {
+        writeLog("warn", message);
+    },
+    error(message) {
+        writeLog("error", message);
+    },
+};
+export class Adversary {
+    name;
+    version;
+    rules = [];
+    reviewPolicy;
+    constructor(options) {
+        if (options.name.length === 0) {
+            throw new Error("Adversary name must be a non-empty string.");
+        }
+        this.name = options.name;
+        this.version = options.version;
+        this.reviewPolicy = options.review ?? {};
+    }
+    rule(id, handler) {
+        if (id.length === 0) {
+            throw new Error("Rule id must be a non-empty string.");
+        }
+        this.rules.push({ id, handler });
+    }
+    async run(options = {}) {
+        const startedAt = performance.now();
+        const input = options.input ?? (await parseInput(options.inputPath));
+        const repoPath = process.env.ADVERSARY_REPO ?? input.source.path;
+        const summary = {};
+        const cache = new Map();
+        const collector = createReviewCollector();
+        const context = createRuleContext(repoPath, summary, cache, collector);
+        const includeSuppressed = options.includeSuppressed ?? parseBooleanEnv(process.env.ADVERSARY_INCLUDE_SUPPRESSED);
+        for (const rule of this.rules) {
+            log.debug(`running rule ${rule.id}`);
+            await rule.handler(context);
+        }
+        const output = buildReviewResult({
+            adversary: { name: this.name, version: this.version },
+            repository: repoPath,
+            filesScanned: typeof summary.files_scanned === "number" ? summary.files_scanned : undefined,
+            collector,
+            policy: { ...this.reviewPolicy, ...options.review },
+            includeSuppressed,
+            includeRawObservations: options.includeRawObservations,
+            timing: { totalMs: Math.round(performance.now() - startedAt) },
+        });
+        if (options.write !== false) {
+            await writeOutput(createAdversaryRunEnvelope(output), options.outputPath);
+        }
+        return output;
+    }
+}
+export function createAdversaryRunEnvelope(result) {
+    return {
+        protocolVersion: ADVERSARY_RUN_PROTOCOL_VERSION,
+        result,
+    };
+}
+export async function parseInput(path = process.env.ADVERSARY_INPUT ?? DEFAULT_INPUT_PATH) {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+        throw new Error(`Invalid input at ${path}: expected an object.`);
+    }
+    if (!isRecord(parsed.source)) {
+        throw new Error(`Invalid input at ${path}: source must be an object.`);
+    }
+    if (typeof parsed.source.path !== "string" || parsed.source.path.length === 0) {
+        throw new Error(`Invalid input at ${path}: source.path must be a non-empty string.`);
+    }
+    return parsed;
+}
+export async function writeOutput(output, path = process.env.ADVERSARY_OUTPUT ?? DEFAULT_OUTPUT_PATH) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(output, null, 2)}\n`, "utf8");
+}
+export function normalizeConfidence(confidence, thresholds = DEFAULT_CONFIDENCE_THRESHOLDS) {
+    if (isConfidence(confidence)) {
+        return confidence;
+    }
+    if (typeof confidence !== "number" ||
+        Number.isNaN(confidence) ||
+        confidence < 0 ||
+        confidence > 1) {
+        throw new Error("confidence must be low, medium, high, or a number from 0 to 1.");
+    }
+    if (confidence >= thresholds.high) {
+        return Confidence.High;
+    }
+    if (confidence >= thresholds.medium) {
+        return Confidence.Medium;
+    }
+    return Confidence.Low;
+}
+export function rankFindings(findings) {
+    return [...findings].sort((left, right) => {
+        const scoreComparison = scoreFinding(right) - scoreFinding(left);
+        if (scoreComparison !== 0) {
+            return scoreComparison;
+        }
+        const severityComparison = severityWeight(right.severity) - severityWeight(left.severity);
+        if (severityComparison !== 0) {
+            return severityComparison;
+        }
+        const titleComparison = compareStrings(left.title, right.title);
+        if (titleComparison !== 0) {
+            return titleComparison;
+        }
+        return compareStrings(left.id, right.id);
+    });
+}
+export class JsonRenderer {
+    write;
+    constructor(write = (text) => process.stdout.write(text)) {
+        this.write = write;
+    }
+    render(result) {
+        this.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+}
+export class TerminalRenderer {
+    write;
+    constructor(write = (text) => process.stdout.write(text)) {
+        this.write = write;
+    }
+    render(result) {
+        const lines = [];
+        lines.push(`Adversary: ${result.adversary.name}`);
+        if (result.target.repository !== undefined) {
+            lines.push(`Repository: ${result.target.repository}`);
+        }
+        lines.push("");
+        if (result.assessment !== undefined) {
+            lines.push("Overall assessment", "");
+            lines.push(`Risk: ${capitalize(result.assessment.risk)}`, "");
+            if (result.assessment.summary !== undefined) {
+                lines.push(normalizeParagraph(result.assessment.summary), "");
+            }
+        }
+        if (result.scores !== undefined && result.scores.length > 0) {
+            lines.push("Scores", "");
+            for (const score of result.scores) {
+                lines.push(formatScore(score));
+            }
+            lines.push("");
+        }
+        if (result.positives.length > 0) {
+            lines.push("Positive signals", "");
+            for (const positive of result.positives) {
+                lines.push(`- ${normalizeParagraph(positive.summary)}`);
+            }
+            lines.push("");
+        }
+        if (result.observations.length > 0) {
+            lines.push("Additional observations", "");
+            for (const observation of result.observations) {
+                lines.push(`- ${normalizeParagraph(observation.summary)}`);
+            }
+            lines.push("");
+        }
+        const primary = result.findings[0];
+        if (primary !== undefined) {
+            lines.push("Primary opportunity", "");
+            lines.push(`- ${primary.title.endsWith(".") ? primary.title : `${primary.title}.`}`, "");
+        }
+        if (result.opinion !== undefined) {
+            lines.push("Overall opinion", "", normalizeParagraph(result.opinion.summary), "");
+        }
+        lines.push("Scan complete", "");
+        if (result.target.filesScanned !== undefined) {
+            lines.push(`Files scanned: ${result.target.filesScanned}`);
+        }
+        lines.push(`Findings: ${result.findings.length}`, "");
+        for (const finding of result.findings) {
+            lines.push(`[${finding.severity}] ${finding.title}`);
+            const firstEvidence = finding.evidence.find((item) => item.file !== undefined);
+            if (firstEvidence?.file !== undefined) {
+                lines.push(formatEvidenceLocation(firstEvidence));
+            }
+            lines.push("");
+            lines.push(`Category: ${finding.category}`);
+            lines.push(`Confidence: ${finding.confidence}`, "");
+            lines.push("Summary", "", finding.summary, "");
+            if (finding.whyItMatters !== undefined) {
+                lines.push("Why it matters", "", finding.whyItMatters, "");
+            }
+            if (finding.impact !== undefined) {
+                lines.push("Impact", "", finding.impact, "");
+            }
+            if (finding.evidence.length > 0) {
+                lines.push("Evidence", "");
+                for (const evidence of finding.evidence) {
+                    lines.push(...formatEvidenceLines(evidence));
+                }
+                lines.push("");
+            }
+            if (finding.recommendation !== undefined) {
+                lines.push("Recommendation", "", normalizeParagraph(finding.recommendation), "");
+            }
+        }
+        this.write(`${lines.join("\n").trimEnd()}\n`);
+    }
+}
+function createRuleContext(repoPath, summary, cache, collector) {
+    const absoluteRepoPath = resolve(repoPath);
+    return {
+        repoPath: absoluteRepoPath,
+        summary,
+        cache,
+        relpath(path) {
+            return relative(absoluteRepoPath, isAbsolute(path) ? path : resolve(absoluteRepoPath, path));
+        },
+        glob(pattern) {
+            return findMatchingPaths(absoluteRepoPath, pattern, false);
+        },
+        rglob(pattern) {
+            return findMatchingPaths(absoluteRepoPath, pattern, true);
+        },
+        observe(observation) {
+            assertObservationInit(observation, "ctx.observe");
+            collector.observations.push(observation);
+        },
+        finding(finding) {
+            assertFindingInput(finding, "ctx.finding");
+            collector.findings.push(normalizeFindingInput(finding));
+        },
+        review: {
+            assessment(assessment) {
+                assertAssessment(assessment);
+                collector.assessment = assessment;
+            },
+            positive(note) {
+                assertReviewNote(note, "ctx.review.positive");
+                collector.positives.push(note);
+            },
+            observe(note) {
+                assertReviewNote(note, "ctx.review.observe");
+                collector.reviewObservations.push(note);
+            },
+            score(score) {
+                assertReviewScore(score);
+                collector.scores.push(score);
+            },
+            opinion(opinion) {
+                assertOpinion(opinion);
+                collector.opinion = opinion;
+            },
+        },
+    };
+}
+async function findMatchingPaths(repoPath, pattern, recursive) {
+    const matcher = globPatternToRegExp(pattern);
+    const paths = recursive ? await walk(repoPath) : await listFiles(repoPath);
+    return paths
+        .map((path) => relative(repoPath, path))
+        .filter((path) => {
+        const posixPath = toPosixPath(path);
+        const candidate = recursive && !pattern.includes("/") ? basename(posixPath) : posixPath;
+        return matcher.test(candidate);
+    })
+        .sort(compareStrings);
+}
+async function listFiles(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries.filter((entry) => entry.isFile()).map((entry) => resolve(directory, entry.name));
+}
+async function walk(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const paths = [];
+    for (const entry of entries) {
+        const path = resolve(directory, entry.name);
+        if (entry.isDirectory()) {
+            paths.push(...(await walk(path)));
+        }
+        else if (entry.isFile()) {
+            paths.push(path);
+        }
+    }
+    return paths;
+}
+function globPatternToRegExp(pattern) {
+    const source = toPosixPath(pattern)
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\0")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/\0/g, ".*");
+    return new RegExp(`^${source}$`);
+}
+function createReviewCollector() {
+    return {
+        observations: [],
+        findings: [],
+        positives: [],
+        reviewObservations: [],
+        scores: [],
+    };
+}
+function buildReviewResult(input) {
+    const thresholds = input.policy.confidenceThresholds ?? DEFAULT_CONFIDENCE_THRESHOLDS;
+    const synthesized = synthesizeObservationFindings(input.collector.observations, thresholds);
+    const allFindings = deduplicateFindings([...synthesized, ...input.collector.findings]).map((finding) => calibrateFindingSeverity(finding, input.policy));
+    const ranked = rankFindings(allFindings);
+    const minimumConfidence = input.policy.minimumConfidence ?? Confidence.Medium;
+    const includeInformational = input.policy.includeInformational ?? false;
+    const maximumFindings = input.policy.maximumFindings ?? Number.POSITIVE_INFINITY;
+    const eligible = [];
+    const suppressedFindings = [];
+    for (const finding of ranked) {
+        const suppressed = confidenceWeight(finding.confidence) < confidenceWeight(minimumConfidence) ||
+            (!includeInformational && finding.severity === Severity.Info) ||
+            eligible.length >= maximumFindings;
+        if (suppressed) {
+            suppressedFindings.push(finding);
+        }
+        else {
+            eligible.push(finding);
+        }
+    }
+    const positives = selectPositiveSignals(input.collector.positives);
+    const reviewObservations = deduplicateReviewObservations(input.collector.reviewObservations, positives);
+    return omitUndefined({
+        adversary: input.adversary,
+        target: omitUndefined({
+            repository: input.repository,
+            filesScanned: input.filesScanned,
+        }),
+        assessment: input.collector.assessment ?? synthesizeAssessment(eligible, positives),
+        positives,
+        observations: reviewObservations,
+        scores: input.collector.scores.length > 0 ? deduplicateScores(input.collector.scores) : undefined,
+        findings: eligible,
+        opinion: input.collector.opinion ?? synthesizeOpinion(eligible),
+        suppressed: {
+            observations: 0,
+            findings: suppressedFindings.length,
+        },
+        timing: input.timing,
+        suppressedFindings: input.includeSuppressed ? suppressedFindings : undefined,
+        rawObservations: input.includeRawObservations ? input.collector.observations : undefined,
+    });
+}
+function synthesizeObservationFindings(observations, thresholds) {
+    const grouped = new Map();
+    const seen = new Set();
+    for (const observation of observations) {
+        const rule = ruleRegistry.lookup(observation.ruleId);
+        const groupKey = observation.groupKey ?? defaultObservationGroupKey(observation, rule);
+        const dedupeKey = stableStringify({ groupKey, observation });
+        if (observation.deduplicate !== false && seen.has(dedupeKey)) {
+            continue;
+        }
+        seen.add(dedupeKey);
+        grouped.set(groupKey, [...(grouped.get(groupKey) ?? []), observation]);
+    }
+    return [...grouped.entries()].map(([groupKey, group]) => {
+        const first = group[0];
+        if (first === undefined) {
+            throw new Error("Cannot synthesize finding from an empty observation group.");
+        }
+        const rule = ruleRegistry.lookup(first.ruleId);
+        const synthesis = rule?.aggregate?.(group) ?? {};
+        const synthesisSource = rule?.aggregate === undefined ? "generic" : "rule";
+        log.debug(`review synthesis ruleId=${first.ruleId} groupKey=${groupKey} observations=${group.length} selected=${synthesisSource} fallback=${synthesisSource === "generic"}`);
+        const evidence = deduplicateEvidence(synthesis.evidence ?? group.map(observationToEvidence));
+        const recommendation = synthesis.recommendation === undefined
+            ? synthesizeRecommendation(group)
+            : normalizeParagraph(synthesis.recommendation);
+        const confidence = aggregateConfidence(group.map((observation) => normalizeConfidence(observation.confidence ?? rule?.defaultConfidence ?? Confidence.Medium, thresholds)), first.confidenceAggregation ?? "maximum");
+        const severity = aggregateSeverity(group.map((observation) => observation.severity ?? rule?.defaultSeverity ?? Severity.Info), first.severityAggregation ?? "highest");
+        return {
+            id: synthesis.id ?? stableId(`${first.ruleId}:${groupKey}`),
+            ruleId: synthesis.ruleId ?? first.ruleId,
+            groupKey: synthesis.groupKey ?? groupKey,
+            title: synthesis.title ??
+                synthesizeObservationTitle(first.title, group.length, first.groupedTitle),
+            category: synthesis.category ?? first.category ?? rule?.category ?? "general",
+            severity: synthesis.severity ?? severity,
+            confidence: synthesis.confidence ??
+                (rule?.defaultConfidence === undefined
+                    ? confidence
+                    : normalizeConfidence(rule.defaultConfidence, thresholds)),
+            summary: synthesis.summary ?? summarizeObservationGroup(group),
+            whyItMatters: synthesis.whyItMatters ?? first.whyItMatters,
+            impact: synthesis.impact ?? first.impact,
+            evidence,
+            recommendation: recommendation.length > 0 ? recommendation : undefined,
+            remediation: synthesis.remediation ?? first.remediation,
+            synthesisSource,
+            tags: synthesis.tags ?? uniqueStrings(group.flatMap((observation) => observation.tags ?? [])),
+            metadata: synthesis.metadata ?? first.metadata,
+        };
+    });
+}
+function normalizeFindingInput(input) {
+    return omitUndefined({
+        id: input.id ?? stableId(`${input.ruleId ?? input.title}:${input.groupKey ?? input.category}`),
+        ruleId: input.ruleId,
+        groupKey: input.groupKey,
+        title: input.title,
+        category: input.category,
+        severity: input.severity,
+        confidence: normalizeConfidence(input.confidence),
+        summary: input.summary,
+        whyItMatters: input.whyItMatters,
+        impact: input.impact,
+        evidence: deduplicateEvidence(input.evidence),
+        recommendation: input.recommendation === undefined ? undefined : normalizeParagraph(input.recommendation),
+        remediation: input.remediation,
+        tags: input.tags === undefined ? undefined : uniqueStrings(input.tags),
+        metadata: input.metadata,
+    });
+}
+function deduplicateFindings(findings) {
+    const seen = new Set();
+    const result = [];
+    for (const finding of findings) {
+        const key = finding.groupKey ?? finding.id;
+        if (seen.has(key)) {
+            const existing = result.find((item) => (item.groupKey ?? item.id) === key);
+            if (existing !== undefined) {
+                existing.evidence = deduplicateEvidence([...existing.evidence, ...finding.evidence]);
+                existing.tags = uniqueStrings([...(existing.tags ?? []), ...(finding.tags ?? [])]);
+            }
+            continue;
+        }
+        seen.add(key);
+        result.push({ ...finding, evidence: deduplicateEvidence(finding.evidence) });
+    }
+    return result;
+}
+function deduplicateEvidence(evidence) {
+    const seen = new Set();
+    const result = [];
+    for (const item of evidence) {
+        const normalized = omitUndefined(item);
+        const key = stableStringify(normalized);
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(normalized);
+        }
+    }
+    return result.sort((left, right) => {
+        const fileComparison = compareStrings(left.file ?? "", right.file ?? "");
+        if (fileComparison !== 0) {
+            return fileComparison;
+        }
+        const lineComparison = compareNumbers(left.line, right.line);
+        if (lineComparison !== 0) {
+            return lineComparison;
+        }
+        return compareStrings(left.message ?? "", right.message ?? "");
+    });
+}
+function deduplicateNotes(notes) {
+    const seen = new Set();
+    const result = [];
+    for (const note of notes) {
+        const normalized = {
+            ...note,
+            evidence: note.evidence === undefined ? undefined : deduplicateEvidence(note.evidence),
+        };
+        const key = note.key;
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(normalized);
+        }
+    }
+    return result.sort((left, right) => compareStrings(left.key, right.key));
+}
+function selectPositiveSignals(notes) {
+    const selected = [];
+    const seen = new Set();
+    // Registration order expresses the review author's priority. Two strong signals
+    // provide useful context without diluting the findings.
+    for (const note of notes) {
+        if (!seen.has(note.key)) {
+            seen.add(note.key);
+            selected.push(note);
+        }
+        if (selected.length === 2) {
+            break;
+        }
+    }
+    return deduplicateNotes(selected);
+}
+function deduplicateReviewObservations(observations, positives) {
+    const deduped = deduplicateNotes(observations);
+    return deduped.filter((item) => {
+        return !positives.some((positive) => notesDescribeSameFact(positive, item));
+    });
+}
+function notesDescribeSameFact(positive, observation) {
+    if (positive.key === observation.key) {
+        return true;
+    }
+    const positiveText = normalizeSemanticText(`${positive.key} ${positive.summary}`);
+    const observationText = normalizeSemanticText(`${observation.key} ${observation.summary}`);
+    if (positiveText.length > 0 && positiveText === observationText) {
+        return true;
+    }
+    const positiveSignals = highSignalSemanticTokens(positiveText);
+    const observationSignals = highSignalSemanticTokens(observationText);
+    return positiveSignals.some((token) => observationSignals.includes(token));
+}
+function synthesizeAssessment(findings, positives = []) {
+    const strength = assessmentStrength(positives[0], findings);
+    if (findings.length === 0) {
+        return {
+            risk: "none",
+            summary: joinSentences(strength, "No material concerns were identified in the reviewed repository."),
+        };
+    }
+    const risk = highestRisk(findings);
+    const primary = findings[0];
+    const primaryConcern = primary === undefined ? "the highest-ranked finding" : assessmentConcern(primary);
+    if (findings.length === 1) {
+        return {
+            risk,
+            summary: joinSentences(strength, `The only material concern identified is ${primaryConcern}.`),
+        };
+    }
+    return {
+        risk,
+        summary: joinSentences(strength, `${numberWord(findings.length)} material concerns were identified. The highest-value improvement is ${primaryConcern}.`),
+    };
+}
+function assessmentStrength(positive, findings) {
+    if (positive === undefined) {
+        return undefined;
+    }
+    if (findingsReferenceDockerfile(findings)) {
+        return "This is a well-structured production Dockerfile.";
+    }
+    const summary = normalizeParagraph(positive.summary);
+    if (/^uses\b/i.test(summary)) {
+        return `The repository ${lowercaseFirst(summary)}`;
+    }
+    return summary;
+}
+function assessmentConcern(finding) {
+    const title = findingConcern(finding);
+    const recommendation = recommendationSubject(finding.recommendation);
+    if (recommendation === "Digest pinning" || /base images?.*digest/i.test(title)) {
+        const plural = /base images\b/i.test(title);
+        return `that the base ${plural ? "images are" : "image is"} referenced by mutable tags rather than immutable digests`;
+    }
+    const summary = normalizeParagraph(finding.summary).split(/(?<=[.!?])\s+/, 1)[0];
+    return concernClause(lowercaseFirst(trimTrailingSentencePunctuation(summary ?? findingConcern(finding))));
+}
+function concernClause(concern) {
+    const isClause = /\b(?:allows|are|builds|can|contains|copies|could|did|do|does|exposes|has|have|includes|installs|is|lacks|may|might|must|reads|references|relies|requires|runs|uses|was|were|writes)\b/i.test(concern);
+    if (!isClause) {
+        return concern;
+    }
+    const hasDeterminer = /^(?:a|an|any|each|its|no|one|some|the|their|these|this|those)\b/i.test(concern);
+    return `that ${hasDeterminer ? concern : `the ${concern}`}`;
+}
+function joinSentences(...sentences) {
+    return sentences.filter(isNonEmptyString).join(" ");
+}
+function synthesizeOpinion(findings) {
+    if (findings.length === 0) {
+        return {
+            ship: true,
+            summary: "I would ship this as-is.",
+        };
+    }
+    const highestSeverity = highestFindingSeverity(findings);
+    const ship = severityWeight(highestSeverity) < severityWeight(Severity.High);
+    const subject = findingsReferenceDockerfile(findings) ? "this Dockerfile" : "this";
+    if (findings.length > 1) {
+        return {
+            ship,
+            summary: "I would address the remaining findings before production.",
+        };
+    }
+    const finding = findings[0];
+    const improvement = finding === undefined ? "Addressing the finding" : improvementPhrase(finding);
+    return {
+        ship,
+        summary: ship
+            ? `I would ship ${subject} as-is. ${improvement} is the only improvement I would recommend before production.`
+            : `${improvement} is the most important improvement to address before production.`,
+    };
+}
+function findingsReferenceDockerfile(findings) {
+    const files = findings.flatMap((finding) => finding.evidence
+        .map((evidence) => evidence.location?.file ?? evidence.file)
+        .filter(isNonEmptyString));
+    return files.length > 0 && files.every((file) => /(?:^|\/)Dockerfile$/.test(file));
+}
+function deduplicateScores(scores) {
+    const seen = new Set();
+    const result = [];
+    for (const score of scores) {
+        if (!seen.has(score.key)) {
+            seen.add(score.key);
+            result.push(score);
+        }
+    }
+    return result.sort((left, right) => compareStrings(left.key, right.key));
+}
+function observationToEvidence(observation) {
+    const metadata = isRecord(observation.evidence)
+        ? observation.evidence
+        : observation.evidence === undefined
+            ? undefined
+            : { evidence: observation.evidence };
+    const message = isRecord(observation.evidence)
+        ? structuredEvidenceMessage(observation.evidence)
+        : stringFromUnknown(observation.evidence);
+    const snippet = isRecord(observation.evidence)
+        ? (stringFromUnknown(observation.evidence.snippet) ??
+            stringFromUnknown(observation.evidence.instruction))
+        : observation.location?.snippet;
+    return omitUndefined({
+        location: observation.location?.location ?? {
+            file: observation.location?.file,
+            line: observation.location?.line,
+            endLine: observation.location?.endLine,
+        },
+        file: observation.location?.file,
+        line: observation.location?.line,
+        endLine: observation.location?.endLine,
+        label: observation.location?.label ?? message,
+        message: observation.location?.message ?? message,
+        snippet,
+        data: metadata,
+        metadata,
+    });
+}
+function structuredEvidenceMessage(evidence) {
+    const explicitMessage = stringFromUnknown(evidence.message);
+    if (explicitMessage !== undefined) {
+        return explicitMessage;
+    }
+    const stage = stringFromUnknown(evidence.stage);
+    if (stage !== undefined) {
+        return `${stage} stage`;
+    }
+    const label = stringFromUnknown(evidence.label) ?? stringFromUnknown(evidence.name);
+    if (label !== undefined) {
+        return label;
+    }
+    return stringFromUnknown(evidence.summary) ?? stringFromUnknown(evidence.instruction);
+}
+function synthesizeObservationTitle(title, count, groupedTitle) {
+    if (typeof title === "string") {
+        return count > 1 && groupedTitle !== undefined ? groupedTitle : title;
+    }
+    return count > 1 ? title.plural : title.singular;
+}
+function summarizeObservationGroup(group) {
+    const first = group[0];
+    if (first === undefined) {
+        throw new Error("Cannot summarize an empty observation group.");
+    }
+    if (first.summary !== undefined) {
+        if (typeof first.summary === "string") {
+            return normalizeParagraph(renderObservationTemplate(first.summary, group));
+        }
+        const template = group.length > 1 ? first.summary.grouped : first.summary.singular;
+        if (template !== undefined) {
+            return normalizeParagraph(renderObservationTemplate(template, group));
+        }
+    }
+    const recommendation = typeof first.recommendation === "string" ? undefined : first.recommendation?.summary;
+    if (group.length === 1) {
+        return recommendation ?? synthesizeObservationTitle(first.title, 1, first.groupedTitle);
+    }
+    return `${group.length} related observations were reported for ${first.subject}.`;
+}
+function synthesizeRecommendation(group) {
+    const recommendations = uniqueStrings(group.flatMap((observation) => {
+        if (typeof observation.recommendation === "string") {
+            return [observation.recommendation];
+        }
+        if (observation.recommendation !== undefined) {
+            return [
+                joinRecommendation(observation.recommendation.summary, observation.recommendation.details),
+            ];
+        }
+        return [];
+    }));
+    return recommendations.map(normalizeParagraph).join("\n\n");
+}
+function joinRecommendation(summary, details) {
+    if (!isNonEmptyString(details)) {
+        return summary;
+    }
+    const compactSummary = trimTrailingSentencePunctuation(summary);
+    const compactDetails = trimTrailingSentencePunctuation(details);
+    if (/^use\s+/i.test(compactDetails)) {
+        return `${compactSummary} and ${lowercaseFirst(compactDetails)}.`;
+    }
+    return `${compactSummary}. ${compactDetails}.`;
+}
+function defaultObservationGroupKey(observation, rule) {
+    const groupBy = observation.groupBy ?? rule?.groupBy;
+    if (groupBy !== undefined && groupBy.length > 0) {
+        return groupBy
+            .map((field) => `${field}:${stringFromUnknown(observationValue(observation, field)) ?? ""}`)
+            .join("|");
+    }
+    return `${observation.ruleId}:${observation.subject}:${observation.category ?? rule?.category ?? "general"}`;
+}
+function renderObservationTemplate(template, group) {
+    const values = observationTemplateValues(group);
+    return template.replace(/\{([a-zA-Z][a-zA-Z0-9_]*)\}/g, (match, key) => {
+        return values[key] ?? match;
+    });
+}
+function observationTemplateValues(group) {
+    const first = group[0];
+    const subjects = uniqueStrings(group.map((observation) => observation.subject));
+    const stages = uniqueStrings(group.map(extractStage).filter(isNonEmptyString));
+    const locations = uniqueStrings(group.map(formatObservationLocation).filter(isNonEmptyString));
+    return omitUndefined({
+        count: numberWord(group.length),
+        location: locations[0],
+        locations: joinHumanList(locations),
+        subject: first?.subject,
+        subjects: joinHumanList(subjects),
+        stage: stages[0],
+        stages: joinHumanList(stages),
+    });
+}
+function observationValue(observation, field) {
+    if (field.includes(".")) {
+        return field.split(".").reduce((value, part) => {
+            return isRecord(value) ? value[part] : undefined;
+        }, observation);
+    }
+    return observation[field];
+}
+function extractStage(observation) {
+    if (isRecord(observation.evidence)) {
+        const explicit = stringFromUnknown(observation.evidence.stage);
+        if (explicit !== undefined) {
+            return explicit;
+        }
+        const label = stringFromUnknown(observation.evidence.label);
+        if (label !== undefined) {
+            return trimTrailingWord(label, "stage");
+        }
+    }
+    return trimTrailingWord(observation.location?.label, "stage");
+}
+function formatObservationLocation(observation) {
+    if (observation.location?.file === undefined) {
+        return undefined;
+    }
+    if (observation.location.line === undefined) {
+        return observation.location.file;
+    }
+    return `${observation.location.file}:${observation.location.line}`;
+}
+function joinHumanList(values) {
+    if (values.length <= 2) {
+        return values.join(" and ");
+    }
+    return `${values.slice(0, -1).join(", ")}, and ${values.at(-1)}`;
+}
+function highestRisk(findings) {
+    const severity = highestFindingSeverity(findings);
+    if (severity === Severity.Info) {
+        return "none";
+    }
+    return severity;
+}
+function highestFindingSeverity(findings) {
+    return aggregateSeverity(findings.map((finding) => finding.severity), "highest");
+}
+function findingConcern(finding) {
+    return lowercaseFirst(trimTrailingSentencePunctuation(finding.title));
+}
+function improvementPhrase(finding) {
+    const recommendation = recommendationSubject(finding.recommendation);
+    if (recommendation !== undefined) {
+        return recommendation;
+    }
+    return `Addressing ${findingConcern(finding)}`;
+}
+function recommendationSubject(recommendation) {
+    if (recommendation === undefined) {
+        return undefined;
+    }
+    const normalized = trimTrailingSentencePunctuation(normalizeParagraph(recommendation));
+    const pinDigest = normalized.match(/\bpin\b.*\bby digest\b/i);
+    if (pinDigest !== null) {
+        return "Digest pinning";
+    }
+    const firstClause = normalized.split(/\s+(?:and|when|where|with)\s+/i)[0]?.trim();
+    if (!isNonEmptyString(firstClause)) {
+        return undefined;
+    }
+    return gerundPhrase(firstClause);
+}
+function gerundPhrase(phrase) {
+    const words = phrase.split(/\s+/);
+    const first = words[0];
+    if (first === undefined) {
+        return phrase;
+    }
+    return capitalize([toGerund(first), ...words.slice(1)].join(" "));
+}
+function toGerund(verb) {
+    const lower = verb.toLowerCase();
+    const irregular = {
+        run: "running",
+        use: "using",
+    };
+    const known = irregular[lower];
+    if (known !== undefined) {
+        return known;
+    }
+    if (lower.endsWith("e") && !lower.endsWith("ee")) {
+        return `${lower.slice(0, -1)}ing`;
+    }
+    return `${lower}ing`;
+}
+function highSignalSemanticTokens(value) {
+    return value
+        .split(" ")
+        .map(canonicalSemanticToken)
+        .filter((word) => highSignalReviewTerms.has(word));
+}
+function canonicalSemanticToken(value) {
+    if (value === "stages") {
+        return "stage";
+    }
+    if (value === "artifacts") {
+        return "artifact";
+    }
+    return trimTrailingWord(trimTrailingWord(value, "ing"), "ed") ?? value;
+}
+function normalizeSemanticText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .split(/\s+/)
+        .filter((word) => word.length > 0 && !semanticStopWords.has(word))
+        .join(" ");
+}
+function trimTrailingWord(value, word) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const pattern = new RegExp(`\\s+${word}$`, "i");
+    const trimmed = value.replace(pattern, "").trim();
+    return trimmed.length > 0 ? trimmed : value;
+}
+function numberWord(value) {
+    return ({
+        1: "One",
+        2: "Two",
+        3: "Three",
+        4: "Four",
+        5: "Five",
+        6: "Six",
+        7: "Seven",
+        8: "Eight",
+        9: "Nine",
+        10: "Ten",
+    }[value] ?? String(value));
+}
+function calibrateFindingSeverity(finding, policy) {
+    const override = policy.severityOverrides?.[finding.ruleId ?? ""] ??
+        policy.severityOverrides?.[finding.groupKey ?? ""];
+    return override === undefined ? finding : { ...finding, severity: override };
+}
+function scoreFinding(finding) {
+    const locationScore = Math.min(finding.evidence.length, 5) * 3;
+    const runtimeScore = finding.tags?.some((tag) => ["production", "runtime"].includes(tag)) ? 8 : 0;
+    const remediationScore = finding.remediation?.complexity === "trivial" ? 3 : 0;
+    return (severityWeight(finding.severity) * 10 +
+        confidenceWeight(finding.confidence) * 12 +
+        locationScore +
+        runtimeScore +
+        remediationScore);
+}
+function severityWeight(severity) {
+    switch (severity) {
+        case Severity.Critical:
+            return 5;
+        case Severity.High:
+            return 4;
+        case Severity.Medium:
+            return 3;
+        case Severity.Low:
+            return 2;
+        case Severity.Info:
+            return 1;
+    }
+}
+function confidenceWeight(confidence) {
+    switch (confidence) {
+        case Confidence.High:
+            return 3;
+        case Confidence.Medium:
+            return 2;
+        case Confidence.Low:
+            return 1;
+    }
+}
+function aggregateSeverity(values, strategy) {
+    const sorted = [...values].sort((left, right) => severityWeight(right) - severityWeight(left));
+    if (strategy === "lowest") {
+        return sorted.at(-1) ?? Severity.Info;
+    }
+    return sorted[0] ?? Severity.Info;
+}
+function aggregateConfidence(values, strategy) {
+    if (values.length === 0) {
+        return Confidence.Low;
+    }
+    if (strategy === "minimum") {
+        return ([...values].sort((left, right) => confidenceWeight(left) - confidenceWeight(right))[0] ??
+            Confidence.Low);
+    }
+    if (strategy === "average") {
+        const average = values.reduce((total, confidence) => total + confidenceNumericValue(confidence), 0) /
+            values.length;
+        return normalizeConfidence(average);
+    }
+    return ([...values].sort((left, right) => confidenceWeight(right) - confidenceWeight(left))[0] ??
+        Confidence.Low);
+}
+function confidenceNumericValue(confidence) {
+    switch (confidence) {
+        case Confidence.High:
+            return 0.95;
+        case Confidence.Medium:
+            return 0.72;
+        case Confidence.Low:
+            return 0.3;
+    }
+}
+function stableId(value) {
+    let hash = 0;
+    for (const character of value) {
+        hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+    }
+    return `finding-${hash.toString(16).padStart(8, "0")}`;
+}
+function stableStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableStringify).join(",")}]`;
+    }
+    if (isRecord(value)) {
+        return `{${Object.keys(value)
+            .sort(compareStrings)
+            .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function uniqueStrings(values) {
+    return [...new Set(values.filter(isNonEmptyString))].sort(compareStrings);
+}
+function assertObservationInit(value, source) {
+    requireString(value.ruleId, `${source}.ruleId`);
+    requireString(value.subject, `${source}.subject`);
+    requireObservationTitle(value.title, `${source}.title`);
+    const rule = ruleRegistry.lookup(value.ruleId);
+    if (value.category === undefined && rule?.category === undefined) {
+        throw new Error(`${source}.category is required when rule.category is not defined.`);
+    }
+    optionalString(value.category, `${source}.category`);
+    if (value.severity === undefined && rule?.defaultSeverity === undefined) {
+        throw new Error(`${source}.severity is required when rule.defaultSeverity is not defined.`);
+    }
+    if (value.severity !== undefined && !isSeverity(value.severity)) {
+        throw new Error(`${source}.severity must be one of info, low, medium, high, critical.`);
+    }
+    const ruleConfidence = rule?.defaultConfidence;
+    if (value.confidence === undefined && ruleConfidence === undefined) {
+        throw new Error(`${source}.confidence is required when rule.defaultConfidence is not defined.`);
+    }
+    if (value.confidence !== undefined) {
+        normalizeConfidence(value.confidence);
+    }
+    optionalObservationSummary(value.summary, `${source}.summary`);
+    optionalEvidence(value.location, `${source}.location`);
+    optionalString(value.groupKey, `${source}.groupKey`);
+    optionalStringArray(value.groupBy, `${source}.groupBy`);
+    optionalStringArray(value.tags, `${source}.tags`);
+}
+function assertFindingInput(value, source) {
+    requireString(value.title, `${source}.title`);
+    requireString(value.category, `${source}.category`);
+    requireString(value.summary, `${source}.summary`);
+    if (!isSeverity(value.severity)) {
+        throw new Error(`${source}.severity must be one of info, low, medium, high, critical.`);
+    }
+    normalizeConfidence(value.confidence);
+    if (!Array.isArray(value.evidence) || value.evidence.length === 0) {
+        throw new Error(`${source}.evidence must contain at least one evidence item.`);
+    }
+    for (const [index, evidence] of value.evidence.entries()) {
+        optionalEvidence(evidence, `${source}.evidence[${index}]`);
+    }
+    optionalString(value.id, `${source}.id`);
+    optionalString(value.ruleId, `${source}.ruleId`);
+    optionalString(value.groupKey, `${source}.groupKey`);
+    optionalStringArray(value.tags, `${source}.tags`);
+}
+function assertReviewNote(value, source) {
+    requireString(value.key, `${source}.key`);
+    requireString(value.summary, `${source}.summary`);
+    if (value.evidence !== undefined) {
+        for (const [index, evidence] of value.evidence.entries()) {
+            optionalEvidence(evidence, `${source}.evidence[${index}]`);
+        }
+    }
+}
+function assertReviewScore(value) {
+    requireString(value.key, "ctx.review.score.key");
+    if (typeof value.score !== "number" || Number.isNaN(value.score)) {
+        throw new Error("ctx.review.score.score must be a number.");
+    }
+    if (value.max !== undefined && (typeof value.max !== "number" || Number.isNaN(value.max))) {
+        throw new Error("ctx.review.score.max must be a number.");
+    }
+    optionalString(value.label, "ctx.review.score.label");
+    optionalString(value.summary, "ctx.review.score.summary");
+}
+function assertAssessment(value) {
+    if (!["none", "low", "medium", "high", "critical"].includes(value.risk)) {
+        throw new Error("ctx.review.assessment.risk must be one of none, low, medium, high, critical.");
+    }
+    optionalString(value.summary, "ctx.review.assessment.summary");
+}
+function assertOpinion(value) {
+    requireString(value.summary, "ctx.review.opinion.summary");
+}
+function assertRuleDefinition(rule) {
+    requireString(rule.id, "rule.id");
+    optionalString(rule.category, "rule.category");
+    if (rule.defaultSeverity !== undefined && !isSeverity(rule.defaultSeverity)) {
+        throw new Error("rule.defaultSeverity must be one of info, low, medium, high, critical.");
+    }
+    if (rule.defaultConfidence !== undefined) {
+        normalizeConfidence(rule.defaultConfidence);
+    }
+    optionalStringArray(rule.groupBy, "rule.groupBy");
+    if (rule.aggregate !== undefined && typeof rule.aggregate !== "function") {
+        throw new Error("rule.aggregate must be a function.");
+    }
+}
+function requireObservationTitle(value, field) {
+    if (typeof value === "string") {
+        requireString(value, field);
+        return;
+    }
+    if (!isRecord(value)) {
+        throw new Error(`${field} must be a string or { singular, plural }.`);
+    }
+    requireString(value.singular, `${field}.singular`);
+    requireString(value.plural, `${field}.plural`);
+}
+function optionalObservationSummary(value, field) {
+    if (value === undefined) {
+        return;
+    }
+    if (typeof value === "string") {
+        optionalString(value, field);
+        return;
+    }
+    if (!isRecord(value)) {
+        throw new Error(`${field} must be a string or { singular, grouped }.`);
+    }
+    optionalString(value.singular, `${field}.singular`);
+    optionalString(value.grouped, `${field}.grouped`);
+}
+function optionalEvidence(value, field) {
+    if (value === undefined) {
+        return;
+    }
+    if (!isRecord(value)) {
+        throw new Error(`${field} must be an object.`);
+    }
+    optionalString(value.file, `${field}.file`);
+    optionalPositiveInteger(value.line, `${field}.line`);
+    optionalPositiveInteger(value.endLine, `${field}.endLine`);
+    optionalString(value.message, `${field}.message`);
+    optionalString(value.snippet, `${field}.snippet`);
+    optionalString(value.label, `${field}.label`);
+}
+function writeLog(level, message) {
+    process.stderr.write(`[adversary] ${level}: ${String(message)}\n`);
+}
+function parseBooleanEnv(value) {
+    if (value === undefined || value.length === 0) {
+        return undefined;
+    }
+    return ["1", "true", "TRUE", "yes", "YES"].includes(value);
+}
+function isVerbose() {
+    return verboseValues.has(process.env.ADVERSARY_VERBOSE ?? "");
+}
+function compareStrings(left, right) {
+    return left.localeCompare(right);
+}
+function compareNumbers(left, right) {
+    return (left ?? Number.MAX_SAFE_INTEGER) - (right ?? Number.MAX_SAFE_INTEGER);
+}
+function toPosixPath(path) {
+    return path.replaceAll("\\", "/");
+}
+function basename(path) {
+    return path.split("/").at(-1) ?? path;
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${field} must be a non-empty string.`);
+    }
+}
+function optionalString(value, field) {
+    if (value !== undefined && typeof value !== "string") {
+        throw new Error(`${field} must be a string.`);
+    }
+}
+function optionalStringArray(value, field) {
+    if (value !== undefined &&
+        (!Array.isArray(value) || value.some((item) => typeof item !== "string"))) {
+        throw new Error(`${field} must be an array of strings.`);
+    }
+}
+function optionalPositiveInteger(value, field) {
+    if (value !== undefined && (!Number.isInteger(value) || Number(value) < 1)) {
+        throw new Error(`${field} must be a positive integer.`);
+    }
+}
+function isConfidence(value) {
+    return value === Confidence.Low || value === Confidence.Medium || value === Confidence.High;
+}
+function isSeverity(value) {
+    return (value === Severity.Info ||
+        value === Severity.Low ||
+        value === Severity.Medium ||
+        value === Severity.High ||
+        value === Severity.Critical);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringFromUnknown(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function capitalize(value) {
+    return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+const semanticStopWords = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "from",
+    "in",
+    "is",
+    "of",
+    "the",
+    "to",
+    "uses",
+    "using",
+]);
+const highSignalReviewTerms = new Set([
+    "artifact",
+    "builder",
+    "digest",
+    "multi",
+    "runtime",
+    "stage",
+]);
+function formatEvidenceLocation(evidence) {
+    const file = evidence.location?.file ?? evidence.file;
+    const line = evidence.location?.line ?? evidence.line;
+    const endLine = evidence.location?.endLine ?? evidence.endLine;
+    if (file === undefined) {
+        return "";
+    }
+    if (line !== undefined && endLine !== undefined) {
+        return `${file}:${line}-${endLine}`;
+    }
+    if (line !== undefined) {
+        return `${file}:${line}`;
+    }
+    return file;
+}
+function formatEvidenceLines(evidence) {
+    const location = formatEvidenceLocation(evidence);
+    const label = evidence.label ?? evidence.message;
+    const firstLine = location.length > 0 && label !== undefined
+        ? `- ${location} — ${label}`
+        : `- ${location.length > 0 ? location : (label ?? "Evidence")}`;
+    const lines = [firstLine];
+    if (evidence.snippet !== undefined) {
+        lines.push(`  ${evidence.snippet}`);
+    }
+    return lines;
+}
+function formatScore(score) {
+    const label = score.label ?? score.key;
+    const max = score.max ?? 10;
+    const summary = score.summary === undefined ? "" : ` - ${normalizeParagraph(score.summary)}`;
+    return `${label}: ${score.score} / ${max}${summary}`;
+}
+function normalizeParagraph(value) {
+    return value
+        .split(/\n+/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join(" ");
+}
+function trimTrailingSentencePunctuation(value) {
+    return value.trim().replace(/[.!?]+$/g, "");
+}
+function lowercaseFirst(value) {
+    return `${value.slice(0, 1).toLowerCase()}${value.slice(1)}`;
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
+}
+//# sourceMappingURL=index.js.map