@dailephd/my-dev-kit-lab 0.2.0

package/dist/src/report/buildExperimentReportInput.js

@@ -0,0 +1,339 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
+const DEFAULT_MAX_PROMPT_CHARS = 1800;
+const DEFAULT_MAX_FILE_TREE_ENTRIES = 80;
+export async function buildExperimentReportInput(options) {
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const experimentDir = path.resolve(repoRoot, options.experimentDir);
+    const warnings = [];
+    const summary = await readRequiredJson(experimentDir, "experiment-summary.json");
+    const runsPayload = await readRequiredJson(experimentDir, "experiment-runs.json");
+    const comparisonsPayload = await readRequiredJson(experimentDir, "experiment-comparisons.json");
+    const config = await readRequiredJson(experimentDir, "experiment-config.json");
+    const runs = runsPayload.runs ?? [];
+    const comparisons = comparisonsPayload.comparisons ?? [];
+    const profilesPath = typeof summary.projectProfilesPath === "string" ? summary.projectProfilesPath : "benchmarks/contracts/benchmark-project-profiles.json";
+    const profiles = await readBenchmarkProjectProfiles(path.resolve(repoRoot, profilesPath), repoRoot);
+    const cases = await readEvaluationCases(path.resolve(repoRoot, summary.casesPath), repoRoot, {
+        projectProfiles: profiles,
+        requireProjectProfileRef: true
+    });
+    const selectedProjectIds = unique(runs.map((run) => run.benchmarkProject));
+    const selectedCaseIds = unique(runs.map((run) => run.caseId));
+    const selectedProfiles = selectedProjectIds
+        .map((projectId) => profiles.find((profile) => profile.projectId === projectId))
+        .filter((profile) => Boolean(profile));
+    const selectedCases = selectedCaseIds
+        .map((caseId) => cases.find((evaluationCase) => evaluationCase.id === caseId))
+        .filter((evaluationCase) => Boolean(evaluationCase));
+    const promptSections = await buildPromptSections({
+        experimentDir,
+        runs,
+        warnings,
+        maxPromptChars: options.maxPromptChars ?? DEFAULT_MAX_PROMPT_CHARS
+    });
+    const plotSections = await buildPlotSections({ repoRoot, plotsDir: options.plotsDir, warnings });
+    const visualizationSections = await buildVisualizationSections({ repoRoot, visualizationsDir: options.visualizationsDir, warnings });
+    const aggregate = buildAggregateAnswers({ summary, runs, comparisons });
+    return {
+        generatedAt: new Date().toISOString(),
+        sourceExperimentDir: experimentDir,
+        title: options.title ?? "Controlled Experiment Report",
+        subtitle: options.subtitle ?? "raw-full-file vs my-dev-kit-guided strategy comparison",
+        executiveSummary: aggregate,
+        methodology: buildMethodology(summary),
+        projectProfiles: selectedProfiles.map(buildProjectSection),
+        benchmarkCases: selectedCases.map(buildBenchmarkCaseSection),
+        fileTreeSections: selectedProfiles.map((profile) => buildFileTreeSection(profile, options.maxFileTreeEntries ?? DEFAULT_MAX_FILE_TREE_ENTRIES)),
+        promptComparisonSections: promptSections,
+        agentRunSections: runs,
+        correctnessSections: runs,
+        tokenSections: comparisons,
+        timingSections: comparisons,
+        comparisonSections: comparisons,
+        plotSections,
+        visualizationSections,
+        formulaSections: buildFormulaSections(),
+        limitations: buildLimitations(runs),
+        warnings: unique([...summary.warnings, ...runs.flatMap((run) => run.warnings), ...comparisons.flatMap((comparison) => comparison.warnings), ...warnings]),
+        artifactLinks: buildArtifactLinks(experimentDir, runs),
+        nextSteps: [
+            "Run optional Codex and Claude experiments when local CLI sessions and account limits allow.",
+            "Use JSON artifacts as the source of truth for follow-up analysis."
+        ],
+        rawArtifacts: {
+            summary,
+            runs,
+            comparisons,
+            config
+        }
+    };
+}
+async function buildPlotSections(args) {
+    if (!args.plotsDir)
+        return [];
+    const plotsDir = path.resolve(args.repoRoot, args.plotsDir);
+    try {
+        const data = JSON.parse(await readFile(path.join(plotsDir, "plot-data.json"), "utf8"));
+        return (data.plots ?? []).map((plot) => ({
+            id: plot.id,
+            title: plot.title,
+            kind: "svg",
+            path: path.join(plotsDir, "charts", `${plot.id}.svg`)
+        }));
+    }
+    catch (error) {
+        args.warnings.push(`Plot artifacts unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+async function buildVisualizationSections(args) {
+    if (!args.visualizationsDir)
+        return [];
+    const visualizationsDir = path.resolve(args.repoRoot, args.visualizationsDir);
+    try {
+        const runsPayload = JSON.parse(await readFile(path.join(visualizationsDir, "visualization-demo-runs.json"), "utf8"));
+        return (runsPayload.runs ?? []).map((run) => ({
+            id: run.id,
+            name: run.name,
+            status: run.ok ? "completed" : "warning",
+            durationMs: run.durationMs,
+            producedArtifactPaths: run.producedArtifactPaths ?? [],
+            warnings: run.warnings ?? []
+        }));
+    }
+    catch (error) {
+        args.warnings.push(`Visualization demo artifacts unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+export function buildAggregateAnswers(args) {
+    const reliabilityCounts = countBy(args.comparisons.map((comparison) => comparison.reliabilityLabel));
+    const tokenAnswer = answerFromComparisonValues(args.comparisons.filter((comparison) => comparison.tokenComparisonAvailable).map((comparison) => comparison.tokenSavingsPercent));
+    const correctnessAnswer = answerCorrectness(args.comparisons);
+    const timingAnswer = answerFromComparisonValues(args.comparisons.map((comparison) => comparison.durationReductionPercent));
+    const fakeOnly = args.runs.length > 0 && args.runs.every((run) => run.agentId === "fake-agent");
+    const externalIssues = args.summary.limitReachedRuns + args.summary.timeoutRuns + args.summary.unavailableRuns + args.summary.invalidOutputRuns;
+    const qualifier = fakeOnly
+        ? " Results are deterministic fake-agent smoke evidence, not real Codex or Claude evidence."
+        : externalIssues > 0
+            ? " Some real-agent outcomes were incomplete and qualify the aggregate answers."
+            : "";
+    return {
+        doesMyDevKitSaveTokens: tokenAnswer,
+        doesMyDevKitPreserveCorrectness: correctnessAnswer,
+        doesMyDevKitReduceExecutionTime: timingAnswer,
+        completedRuns: args.summary.completedRuns,
+        failedRuns: args.summary.failedRuns,
+        unavailableRuns: args.summary.unavailableRuns,
+        limitReachedRuns: args.summary.limitReachedRuns,
+        timeoutRuns: args.summary.timeoutRuns,
+        invalidOutputRuns: args.summary.invalidOutputRuns,
+        comparisonReliabilityCounts: reliabilityCounts,
+        summaryText: [
+            `Completed ${args.summary.completedRuns} of ${args.summary.totalRuns} runs across ${args.summary.totalComparisons} comparisons.`,
+            `Token savings: ${tokenAnswer}. Correctness preserved: ${correctnessAnswer}. Execution time reduced: ${timingAnswer}.`,
+            qualifier.trim()
+        ]
+            .filter(Boolean)
+            .join(" ")
+    };
+}
+async function readRequiredJson(experimentDir, fileName) {
+    const filePath = path.join(experimentDir, fileName);
+    try {
+        return JSON.parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Missing or invalid required experiment artifact ${fileName}: ${message}`);
+    }
+}
+async function buildPromptSections(args) {
+    const sections = [];
+    for (const run of args.runs) {
+        const promptPath = run.artifactPaths.promptPath ?? path.join(args.experimentDir, "runs", run.runId, "prompt.txt");
+        let promptText = run.promptTextForArtifact ?? "";
+        try {
+            promptText = await readFile(promptPath, "utf8");
+        }
+        catch {
+            args.warnings.push(`Optional prompt artifact missing for run ${run.runId}.`);
+        }
+        const truncated = promptText.length > args.maxPromptChars;
+        sections.push({
+            runId: run.runId,
+            caseId: run.caseId,
+            agentId: run.agentId,
+            strategy: run.promptStrategy,
+            complexityLevel: run.promptComplexityLevel,
+            promptPath,
+            promptExcerpt: truncated ? `${promptText.slice(0, args.maxPromptChars)}\n...` : promptText,
+            promptWasTruncated: truncated,
+            metrics: run.promptMetrics
+        });
+    }
+    return sections;
+}
+function buildProjectSection(profile) {
+    return {
+        profile,
+        complexityMetrics: pickComplexityMetrics(profile.complexityMetrics)
+    };
+}
+function pickComplexityMetrics(metrics) {
+    return {
+        fileCount: metrics.fileCount,
+        sourceFileCount: metrics.sourceFileCount,
+        testFileCount: metrics.testFileCount,
+        totalLinesOfCode: metrics.totalLinesOfCode,
+        sourceLinesOfCode: metrics.sourceLinesOfCode,
+        testLinesOfCode: metrics.testLinesOfCode,
+        languageCount: metrics.languageCount,
+        internalImportCount: metrics.internalImportCount,
+        exportedSymbolEstimate: metrics.exportedSymbolEstimate,
+        taskCount: metrics.taskCount,
+        expectedRelevantFilesAverage: metrics.expectedRelevantFilesAverage,
+        expectedRelevantSymbolsAverage: metrics.expectedRelevantSymbolsAverage,
+        maxFileLines: metrics.maxFileLines,
+        averageFileLines: metrics.averageFileLines
+    };
+}
+function buildFileTreeSection(profile, maxEntries) {
+    return {
+        projectId: profile.projectId,
+        entries: profile.fileTree.entries.slice(0, maxEntries),
+        totalEntries: profile.fileTree.entries.length,
+        truncated: profile.fileTree.entries.length > maxEntries
+    };
+}
+function buildBenchmarkCaseSection(evaluationCase) {
+    const answerKey = evaluationCase.answerKey;
+    return {
+        caseId: evaluationCase.id,
+        title: evaluationCase.title,
+        benchmarkProject: evaluationCase.benchmarkProject,
+        query: evaluationCase.query,
+        expectedOperation: evaluationCase.expectedOperation,
+        expectedFiles: answerKey?.expectedFiles ?? evaluationCase.expectedFiles,
+        expectedSymbols: answerKey?.expectedSymbols ?? evaluationCase.expectedSymbols,
+        expectedFacts: answerKey?.expectedFacts ?? [],
+        minimumCorrectFacts: answerKey?.minimumCorrectFacts ?? 0,
+        notes: evaluationCase.notes
+    };
+}
+function buildMethodology(summary) {
+    return [
+        `Benchmark projects were selected from ${summary.projectProfilesPath ?? "benchmark project profiles"}.`,
+        `Prompt strategies tested: ${summary.strategies.join(", ")}.`,
+        `Prompt complexity levels tested: ${summary.complexityLevels.join(", ")}.`,
+        `Agents tested: ${summary.agents.join(", ")}.`,
+        "Run statuses distinguish completed, failed, skipped, unavailable, external limit, timeout, and invalid-output outcomes.",
+        "Correctness scoring is deterministic and answer-key based; no semantic LLM judging is used.",
+        "Token comparison uses agent session token totals only when both paired runs provide totalTokens.",
+        "Timing comparison uses measured run duration from normalized agent run results.",
+        "Provider telemetry dashboards and OpenTelemetry collection are not part of this report."
+    ];
+}
+function buildFormulaSections() {
+    return [
+        {
+            id: "correctness",
+            title: "Correctness Score",
+            formula: "correctnessScore = 0.25 * fileMatchScore + 0.25 * symbolMatchScore + 0.50 * factMatchScore",
+            notes: [
+                "Pass condition: required facts found unless minimumCorrectFacts applies.",
+                "Pass condition: found facts >= minimumCorrectFacts.",
+                "Pass condition: correctnessScore >= 0.70."
+            ]
+        },
+        {
+            id: "tokens",
+            title: "Token Savings",
+            formula: "tokenDelta = rawTotalTokens - myDevKitTotalTokens; tokenSavingsPercent = tokenDelta / rawTotalTokens * 100",
+            notes: [
+                "Computed only when both paired runs expose totalTokens and rawTotalTokens is greater than zero.",
+                "Prompt estimated tokens are shown separately and are not substituted for provider session tokens."
+            ]
+        },
+        {
+            id: "timing",
+            title: "Execution Time Reduction",
+            formula: "durationDeltaMs = rawDurationMs - myDevKitDurationMs; durationReductionPercent = durationDeltaMs / rawDurationMs * 100",
+            notes: ["Computed only when both paired runs expose durationMs and rawDurationMs is greater than zero."]
+        }
+    ];
+}
+function buildLimitations(runs) {
+    const fakeOnly = runs.length > 0 && runs.every((run) => run.agentId === "fake-agent");
+    return [
+        fakeOnly ? "fake-agent results are deterministic smoke results, not real Codex or Claude evidence." : undefined,
+        "Codex and Claude may fail due external account, usage, or session limits.",
+        "Token usage depends on agent output availability.",
+        "Prompt estimated tokens are not provider session tokens.",
+        "Correctness scoring is answer-key based and deterministic, not semantic.",
+        "Charts are deterministic static SVG summaries, not provider telemetry dashboards.",
+        "Visualization demos are bounded command smoke checks and may report unsupported graph commands as warnings."
+    ].filter((item) => Boolean(item));
+}
+function buildArtifactLinks(experimentDir, runs) {
+    return [
+        { label: "Metric glossary", path: path.resolve("docs", "METRICS.md"), kind: "markdown" },
+        { label: "Experiment summary", path: path.join(experimentDir, "experiment-summary.json"), kind: "json" },
+        { label: "Experiment runs", path: path.join(experimentDir, "experiment-runs.json"), kind: "json" },
+        { label: "Experiment comparisons", path: path.join(experimentDir, "experiment-comparisons.json"), kind: "json" },
+        { label: "Experiment config", path: path.join(experimentDir, "experiment-config.json"), kind: "json" },
+        ...runs.flatMap((run) => [
+            { label: `${run.runId} prompt`, path: run.artifactPaths.promptPath ?? path.join(experimentDir, "runs", run.runId, "prompt.txt"), kind: "text" },
+            {
+                label: `${run.runId} correctness`,
+                path: run.artifactPaths.correctnessScorePath ?? path.join(experimentDir, "runs", run.runId, "correctness-score.json"),
+                kind: "json"
+            }
+        ])
+    ];
+}
+function answerFromComparisonValues(values) {
+    const usable = values.filter((value) => typeof value === "number" && Number.isFinite(value));
+    if (usable.length === 0) {
+        return "unavailable";
+    }
+    const positive = usable.filter((value) => value > 0).length;
+    const negative = usable.filter((value) => value < 0).length;
+    if (positive > usable.length / 2)
+        return "yes";
+    if (negative > usable.length / 2)
+        return "no";
+    return "mixed";
+}
+function answerCorrectness(comparisons) {
+    const completed = comparisons.filter((comparison) => comparison.rawStatus === "completed" && comparison.myDevKitStatus === "completed");
+    if (completed.length === 0) {
+        return comparisons.length === 0 ? "unavailable" : "inconclusive";
+    }
+    const preserved = completed.filter((comparison) => comparison.sameCorrectnessPass).length;
+    if (preserved === completed.length)
+        return "yes";
+    if (preserved === 0)
+        return "no";
+    return "mixed";
+}
+function countBy(values) {
+    return values.reduce((counts, value) => {
+        counts[value] = (counts[value] ?? 0) + 1;
+        return counts;
+    }, {});
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+export async function assertExperimentReportCanRead(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/report/experimentReportTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/src/report/experiments/buildPluginExperimentReport.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+export function buildPluginExperimentReport(args) {
+    const outputRoot = args.outputRoot ?? readString(args.run.metadata?.outputRoot) ?? null;
+    const allOutcomes = args.run.cases.flatMap((experimentCase) => experimentCase.outcomes);
+    return {
+        metadata: {
+            generatedAt: args.generatedAt ?? new Date().toISOString(),
+            runId: args.run.runId,
+            startedAt: args.run.startedAt,
+            completedAt: args.run.completedAt ?? null,
+            status: args.run.status,
+            outputRoot,
+        },
+        plugin: args.plugin,
+        target: {
+            ...args.run.target,
+            mode: args.run.target.isSelf ? "self" : "external target",
+        },
+        summary: args.run.summary ?? null,
+        variants: args.run.variants.map((variant) => buildVariantSummary(variant, allOutcomes)),
+        cases: args.run.cases.map(buildCaseSummary),
+        metrics: args.run.metrics,
+        artifacts: relativizeArtifacts(args.run.artifacts, outputRoot),
+        warnings: args.run.warnings,
+        failures: args.run.failures,
+        skippedOutcomes: allOutcomes.filter((outcome) => outcome.status === "skipped"),
+        findings: buildFindings(args.run),
+        interpretation: buildInterpretation(args.run),
+        rawRun: {
+            ...args.run,
+            artifacts: relativizeArtifacts(args.run.artifacts, outputRoot),
+        },
+    };
+}
+function buildVariantSummary(variant, outcomes) {
+    const variantOutcomes = outcomes.filter((outcome) => outcome.variantId === variant.id);
+    return {
+        ...variant,
+        outcomeCount: variantOutcomes.length,
+        completedOutcomes: countStatus(variantOutcomes, "completed"),
+        partialOutcomes: countStatus(variantOutcomes, "partial"),
+        failedOutcomes: countStatus(variantOutcomes, "failed"),
+        skippedOutcomes: countStatus(variantOutcomes, "skipped"),
+        metrics: variantOutcomes.flatMap((outcome) => outcome.metrics),
+    };
+}
+function buildCaseSummary(experimentCase) {
+    return {
+        id: experimentCase.id,
+        name: experimentCase.name,
+        status: summarizeStatus(experimentCase.outcomes),
+        outcomeCount: experimentCase.outcomes.length,
+        completedOutcomes: countStatus(experimentCase.outcomes, "completed"),
+        partialOutcomes: countStatus(experimentCase.outcomes, "partial"),
+        failedOutcomes: countStatus(experimentCase.outcomes, "failed"),
+        skippedOutcomes: countStatus(experimentCase.outcomes, "skipped"),
+        outcomes: experimentCase.outcomes,
+    };
+}
+function buildFindings(run) {
+    const skipped = run.cases.flatMap((experimentCase) => experimentCase.outcomes
+        .filter((outcome) => outcome.status === "skipped")
+        .map((outcome) => ({
+        severity: "skip",
+        code: "outcome-skipped",
+        message: `Outcome skipped: ${outcome.id}`,
+        caseId: outcome.caseId,
+        variantId: outcome.variantId,
+    })));
+    return [
+        ...run.warnings.map((warning) => ({
+            severity: "warning",
+            code: warning.code,
+            message: warning.message,
+            caseId: warning.caseId,
+            variantId: warning.variantId,
+        })),
+        ...run.failures.map((failure) => ({
+            severity: "failure",
+            code: failure.code,
+            message: failure.message,
+            caseId: failure.caseId,
+            variantId: failure.variantId,
+        })),
+        ...skipped,
+    ];
+}
+function buildInterpretation(run) {
+    if (run.pluginId === "context-strategy-comparison") {
+        const tokenSavings = metricNumber(run.metrics, "average-token-savings-percent");
+        const correctnessDelta = metricNumber(run.metrics, "average-correctness-delta");
+        const durationReduction = metricNumber(run.metrics, "average-duration-reduction-percent");
+        const better = tokenSavings !== undefined && tokenSavings > 0 && (correctnessDelta ?? 0) >= 0
+            ? "my-dev-kit-guided"
+            : correctnessDelta !== undefined && correctnessDelta < 0
+                ? "raw-full-file"
+                : "inconclusive";
+        return {
+            summary: [
+                "raw-full-file vs my-dev-kit-guided comparison",
+                `Best-supported strategy: ${better}.`,
+                tokenSavings === undefined ? undefined : `Average token savings: ${tokenSavings}%.`,
+                durationReduction === undefined ? undefined : `Average duration reduction: ${durationReduction}%.`,
+                correctnessDelta === undefined ? undefined : `Average correctness delta: ${correctnessDelta}.`,
+            ]
+                .filter(Boolean)
+                .join(" "),
+            recommendedNextStep: run.status === "completed"
+                ? "Review case-level outcomes and repeat with real agents if this was a fake-agent smoke run."
+                : "Review warnings, skipped outcomes, and failures before using this run as evidence.",
+        };
+    }
+    return {
+        summary: `Experiment ${run.pluginId} finished with status ${run.status}.`,
+        recommendedNextStep: run.failures.length > 0 || run.warnings.length > 0
+            ? "Review warnings and failures before comparing results."
+            : "Use the JSON report as the source of truth for follow-up analysis.",
+    };
+}
+function relativizeArtifacts(artifacts, outputRoot) {
+    if (!outputRoot)
+        return artifacts;
+    return artifacts.map((artifact) => {
+        if (!artifact.path)
+            return artifact;
+        const relative = path.relative(outputRoot, artifact.path);
+        return {
+            ...artifact,
+            path: relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : artifact.path,
+        };
+    });
+}
+function countStatus(outcomes, status) {
+    return outcomes.filter((outcome) => outcome.status === status).length;
+}
+function summarizeStatus(outcomes) {
+    if (outcomes.length === 0)
+        return "skipped";
+    if (outcomes.every((outcome) => outcome.status === "completed"))
+        return "completed";
+    if (outcomes.every((outcome) => outcome.status === "skipped"))
+        return "skipped";
+    if (outcomes.some((outcome) => outcome.status === "completed"))
+        return "partial";
+    return "failed";
+}
+function metricNumber(metrics, id) {
+    const value = metrics.find((metric) => metric.id === id)?.value;
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function readString(value) {
+    return typeof value === "string" && value ? value : undefined;
+}

package/dist/src/report/experiments/experimentReportModel.js

@@ -0,0 +1 @@
+export {};

package/dist/src/report/experiments/index.js

@@ -0,0 +1,4 @@
+export * from "./buildPluginExperimentReport.js";
+export * from "./experimentReportModel.js";
+export * from "./renderPluginExperimentReportHtml.js";
+export * from "./writePluginExperimentReports.js";

package/dist/src/report/experiments/renderPluginExperimentReportHtml.js

@@ -0,0 +1,133 @@
+export function renderPluginExperimentReportHtml(report) {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(report.plugin.name)} Report</title>
+  <style>
+    :root { color-scheme: light; font-family: Arial, Helvetica, sans-serif; }
+    body { margin: 0; color: #18212b; background: #f6f8fb; }
+    main { max-width: 1120px; margin: 0 auto; padding: 28px; }
+    h1 { margin: 0 0 6px; font-size: 32px; }
+    h2 { margin: 0 0 12px; font-size: 22px; }
+    h3 { margin: 14px 0 8px; font-size: 17px; }
+    p, li { line-height: 1.45; }
+    section, .hero { background: #fff; border: 1px solid #d7e0ea; border-radius: 8px; padding: 18px; margin-bottom: 16px; }
+    table { width: 100%; border-collapse: collapse; margin: 8px 0 16px; background: #fff; }
+    th, td { border: 1px solid #d9e1ea; padding: 8px 10px; text-align: left; vertical-align: top; }
+    th { background: #edf2f7; }
+    code { font-family: Consolas, "Courier New", monospace; }
+    .muted { color: #5b6b7b; }
+    .grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }
+    .card { border: 1px solid #d9e1ea; border-radius: 6px; padding: 12px; background: #fbfcfe; }
+    .badge { display: inline-block; border-radius: 999px; padding: 3px 9px; font-size: 12px; font-weight: 700; text-transform: uppercase; background: #e8eef7; }
+    .status-completed { background: #dcf4e4; color: #0c6b30; }
+    .status-partial, .status-skipped { background: #fff0ce; color: #785400; }
+    .status-failed { background: #fde2e2; color: #8a1f1f; }
+    @media (max-width: 860px) { main { padding: 14px; } .grid { grid-template-columns: 1fr; } table { font-size: 13px; } }
+  </style>
+</head>
+<body>
+<main>
+  <header class="hero">
+    <h1>${escapeHtml(report.plugin.name)}</h1>
+    <p>${escapeHtml(report.plugin.description)}</p>
+    <p><span class="badge status-${escapeHtml(report.metadata.status)}">${escapeHtml(report.metadata.status)}</span></p>
+    <p class="muted">Generated ${escapeHtml(report.metadata.generatedAt)} for run <code>${escapeHtml(report.metadata.runId)}</code></p>
+  </header>
+
+  <section>
+    <h2>Plugin And Target</h2>
+    ${table(["Field", "Value"], [
+        ["Plugin ID", report.plugin.id],
+        ["Plugin schema", report.plugin.schemaVersion],
+        ["Mode", report.target.mode],
+        ["Tool root", report.target.toolRoot],
+        ["Target root", report.target.targetRoot],
+        ["Target package", report.target.packageName ? `${report.target.packageName}@${report.target.packageVersion ?? "unknown"}` : "unavailable"],
+        ["Target branch/commit", report.target.hasGit ? `${report.target.branch ?? "unknown"} / ${report.target.commit ?? "unknown"}` : "unavailable"],
+        ["Has package.json", String(report.target.hasPackageJson)],
+        ["Has lockfile", String(report.target.hasLockfile)],
+        ["Output root", report.metadata.outputRoot ?? "unavailable"],
+    ])}
+  </section>
+
+  <section>
+    <h2>Interpretation</h2>
+    <p>${escapeHtml(report.interpretation.summary)}</p>
+    <p><strong>Recommended next step:</strong> ${escapeHtml(report.interpretation.recommendedNextStep)}</p>
+  </section>
+
+  <section>
+    <h2>Variants</h2>
+    ${table(["Variant", "Completed", "Partial", "Failed", "Skipped"], report.variants.map((variant) => [
+        `${variant.name} (${variant.id})`,
+        String(variant.completedOutcomes),
+        String(variant.partialOutcomes),
+        String(variant.failedOutcomes),
+        String(variant.skippedOutcomes),
+    ]))}
+  </section>
+
+  <section>
+    <h2>Cases</h2>
+    ${table(["Case", "Status", "Completed", "Partial", "Failed", "Skipped"], report.cases.map((experimentCase) => [
+        `${experimentCase.name} (${experimentCase.id})`,
+        experimentCase.status,
+        String(experimentCase.completedOutcomes),
+        String(experimentCase.partialOutcomes),
+        String(experimentCase.failedOutcomes),
+        String(experimentCase.skippedOutcomes),
+    ]))}
+  </section>
+
+  <section>
+    <h2>Metrics</h2>
+    ${table(["Metric", "Value", "Unit", "Variant", "Case"], report.metrics.map((metric) => [
+        `${metric.name} (${metric.id})`,
+        String(metric.value ?? ""),
+        metric.unit ?? "",
+        metric.variantId ?? "",
+        metric.caseId ?? "",
+    ]))}
+  </section>
+
+  <section>
+    <h2>Warnings, Skips, And Failures</h2>
+    ${report.findings.length ? table(["Severity", "Code", "Message", "Variant", "Case"], report.findings.map((finding) => [
+        finding.severity,
+        finding.code,
+        finding.message,
+        finding.variantId ?? "",
+        finding.caseId ?? "",
+    ])) : "<p>No warnings, skips, or failures.</p>"}
+  </section>
+
+  <section>
+    <h2>Artifacts</h2>
+    ${table(["Artifact", "Kind", "Path", "Variant", "Case"], report.artifacts.map((artifact) => [
+        `${artifact.label} (${artifact.id})`,
+        artifact.kind,
+        artifact.path ?? "",
+        artifact.variantId ?? "",
+        artifact.caseId ?? "",
+    ]))}
+  </section>
+</main>
+</body>
+</html>`;
+}
+function table(headers, rows) {
+    return `<table><thead><tr>${headers.map((header) => `<th>${escapeHtml(header)}</th>`).join("")}</tr></thead><tbody>${rows
+        .map((row) => `<tr>${row.map((cell) => `<td>${escapeHtml(cell)}</td>`).join("")}</tr>`)
+        .join("")}</tbody></table>`;
+}
+function escapeHtml(value) {
+    return String(value ?? "")
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/src/report/experiments/writePluginExperimentReports.js

@@ -0,0 +1,30 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveWithinRoot } from "../../core/pathSafety.js";
+import { buildPluginExperimentReport } from "./buildPluginExperimentReport.js";
+import { renderPluginExperimentReportHtml } from "./renderPluginExperimentReportHtml.js";
+export async function writePluginExperimentReports(args) {
+    const rawOutDir = args.outputRoot ?? readString(args.run.metadata?.outputRoot);
+    if (!rawOutDir) {
+        throw new Error("Plugin experiment report output root is required.");
+    }
+    const outDir = path.resolve(rawOutDir);
+    const outputPaths = {
+        outDir,
+        jsonPath: resolveWithinRoot(outDir, "report.json"),
+        htmlPath: resolveWithinRoot(outDir, "report.html"),
+    };
+    await mkdir(outputPaths.outDir, { recursive: true });
+    const report = buildPluginExperimentReport({
+        run: args.run,
+        plugin: args.plugin,
+        outputRoot: outputPaths.outDir,
+        generatedAt: args.generatedAt,
+    });
+    await writeFile(outputPaths.jsonPath, `${JSON.stringify({ report, outputPaths }, null, 2)}\n`, "utf8");
+    await writeFile(outputPaths.htmlPath, renderPluginExperimentReportHtml(report), "utf8");
+    return { report, outputPaths };
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}

package/dist/src/report/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./renderHtmlReport.js";
+export * from "./writeReportArtifacts.js";
+export * from "./experimentReportTypes.js";
+export * from "./buildExperimentReportInput.js";
+export * from "./renderExperimentHtmlReport.js";
+export * from "./writeExperimentReportArtifacts.js";
+export * from "./experiments/index.js";