@speqkit/plugin-junit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 speqkit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @speqkit/plugin-junit
+
+JUnit XML, folded out of the run's event stream.
+
+```yaml
+# speq.yaml
+plugins:
+  - junit
+
+junit:
+  output: junit.xml     # relative to reports/, or an absolute path
+  suiteName: payments   # the name attribute on <testsuites>
+```
+
+```bash
+speq run --reporter console,junit
+```
+
+Reporters are opt-in per run. `--reporter` names them; the default is
+`console` alone, so adding this plugin costs a registration and nothing else
+until a run asks for it.
+
+## Where it writes, and why there
+
+`reports/junit.xml` — the stable directory, not `reports/<runId>/`.
+
+A CI workflow names one fixed path and cannot interpolate a run id it will not
+learn until the step has already finished:
+
+```yaml
+- run: speq install --frozen
+- run: speq run --env ci --reporter console,junit
+- uses: actions/upload-artifact@v4
+  if: always()
+  with:
+    name: speq-report
+    path: .speq/reports/
+```
+
+The per-run directory is right for artifacts, which are addressed from inside
+the report. It is wrong for the report itself.
+
+## `failure` and `error` are not the same thing
+
+JUnit distinguishes them and so does the spine. `failed` is the system under
+test saying no; `error` is the test never getting an answer at all. Collapsing
+both into failures is what makes a flaky environment look like a broken build,
+so a step that threw lands in `<error>` and an assertion that returned false
+lands in `<failure>`.
+
+Attachments are listed as `[[ATTACHMENT|path]]` in `<system-out>`, the
+convention several CI viewers already understand.
+
+## Nothing here reads the runner
+
+Every number in the file is built from `RunEvent`s alone — no access to the
+runner's result object, no hooks, no privileged channel. That is deliberate,
+and `packages/core/test/reporting.test.ts` pins it: replaying a recorded run
+through `speq report` has to produce a byte-identical file to the live run.
+
+If that test ever fails, the event stream has stopped being sufficient to
+describe a run, and every consumer resting on it — this plugin, a TUI, the VS
+Code panel — inherits the gap. The fix would belong in the event contract, not
+here.
+
+## Control characters
+
+Assertion messages routinely carry terminal colour codes; the console reporter
+emits them by design. XML 1.0 cannot represent them at all, and one is enough
+to make the file unparseable by the CI that has to read it — which shows up as
+a broken build rather than a broken report. They are stripped on the way out.

package/dist/build.d.ts

@@ -0,0 +1,46 @@
+import type { RunEvent, StepStatus } from '@speqkit/plugin-api';
+export interface JUnitCase {
+    name: string;
+    suite: string;
+    file?: string;
+    status: StepStatus;
+    durationMs: number;
+    /** Why it failed, in the order the run found out. */
+    failures: string[];
+    /** Free-form lines CI viewers show under the case. */
+    output: string[];
+}
+export interface JUnitSuite {
+    name: string;
+    cases: JUnitCase[];
+}
+export interface JUnitRun {
+    runId?: string;
+    durationMs: number;
+    suites: JUnitSuite[];
+}
+/**
+ * Folds the event stream into the shape JUnit wants.
+ *
+ * Kept apart from the file writing so it can be tested on a plain list of
+ * events, and so `speq report` and a live run go through exactly the same
+ * code — the event stream being sufficient on its own is the property worth
+ * protecting.
+ */
+export declare class RunBuilder {
+    #private;
+    on(event: RunEvent): void;
+    /**
+     * A reporter is registered once and may see several runs in one process —
+     * `speq report` replaying after a run, or a long-lived editor session. Two
+     * runs' worth of cases in one file would be nobody's intent.
+     */
+    reset(): void;
+    result(): JUnitRun;
+    private suiteFor;
+}
+export interface RenderOptions {
+    name: string;
+}
+export declare function renderJUnit(run: JUnitRun, options: RenderOptions): string;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAE/D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,UAAU,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,sDAAsD;IACtD,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,SAAS,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,UAAU,EAAE,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;;IAQrB,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IA0DzB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb,MAAM,IAAI,QAAQ;IAIlB,OAAO,CAAC,QAAQ;CASjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;CACb;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAsBzE"}

package/dist/build.js

@@ -0,0 +1,163 @@
+/**
+ * Folds the event stream into the shape JUnit wants.
+ *
+ * Kept apart from the file writing so it can be tested on a plain list of
+ * events, and so `speq report` and a live run go through exactly the same
+ * code — the event stream being sufficient on its own is the property worth
+ * protecting.
+ */
+export class RunBuilder {
+    #suites = [];
+    #byName = new Map();
+    #suite = '(inline)';
+    #case;
+    #runId;
+    #durationMs = 0;
+    on(event) {
+        switch (event.type) {
+            case 'run.started':
+                this.reset();
+                this.#runId = event.runId;
+                break;
+            // Tests do not carry their suite on the event; the bracketing does. That
+            // holds on replay too, because the log preserves the order.
+            case 'suite.started':
+                this.#suite = event.suite;
+                break;
+            case 'test.started':
+                this.#case = {
+                    name: event.test,
+                    suite: this.#suite,
+                    file: event.source,
+                    status: 'passed',
+                    durationMs: 0,
+                    failures: [],
+                    output: []
+                };
+                break;
+            case 'step.finished':
+                if (this.#case && event.status !== 'passed' && event.status !== 'skipped') {
+                    const label = event.stepId ? `${event.stepId} (${event.stepType})` : event.stepType;
+                    this.#case.failures.push(`step ${label}: ${event.message ?? event.status}`);
+                }
+                break;
+            case 'assertion.evaluated':
+                if (this.#case && !event.passed) {
+                    this.#case.failures.push(`assertion ${event.assertionType}: ${event.message}`);
+                }
+                break;
+            case 'artifact.attached':
+                this.#case?.output.push(`[[ATTACHMENT|${event.path ?? event.name}]]`);
+                break;
+            case 'test.finished': {
+                const entry = this.#case;
+                this.#case = undefined;
+                if (!entry)
+                    break;
+                entry.status = event.status;
+                entry.durationMs = event.durationMs;
+                this.suiteFor(entry.suite).cases.push(entry);
+                break;
+            }
+            case 'run.finished':
+                this.#durationMs = event.durationMs;
+                break;
+        }
+    }
+    /**
+     * A reporter is registered once and may see several runs in one process —
+     * `speq report` replaying after a run, or a long-lived editor session. Two
+     * runs' worth of cases in one file would be nobody's intent.
+     */
+    reset() {
+        this.#suites = [];
+        this.#byName = new Map();
+        this.#suite = '(inline)';
+        this.#case = undefined;
+        this.#runId = undefined;
+        this.#durationMs = 0;
+    }
+    result() {
+        return { runId: this.#runId, durationMs: this.#durationMs, suites: this.#suites };
+    }
+    suiteFor(name) {
+        let suite = this.#byName.get(name);
+        if (!suite) {
+            suite = { name, cases: [] };
+            this.#byName.set(name, suite);
+            this.#suites.push(suite);
+        }
+        return suite;
+    }
+}
+export function renderJUnit(run, options) {
+    const all = run.suites.flatMap((s) => s.cases);
+    const lines = [
+        `<?xml version="1.0" encoding="UTF-8"?>`,
+        `<testsuites name="${esc(options.name)}" tests="${all.length}" ` +
+            `failures="${count(all, 'failed')}" errors="${count(all, 'error')}" ` +
+            `skipped="${count(all, 'skipped')}" time="${seconds(run.durationMs)}">`
+    ];
+    for (const suite of run.suites) {
+        lines.push(`  <testsuite name="${esc(suite.name)}" tests="${suite.cases.length}" ` +
+            `failures="${count(suite.cases, 'failed')}" errors="${count(suite.cases, 'error')}" ` +
+            `skipped="${count(suite.cases, 'skipped')}" ` +
+            `time="${seconds(suite.cases.reduce((sum, c) => sum + c.durationMs, 0))}">`);
+        for (const entry of suite.cases)
+            lines.push(...renderCase(entry));
+        lines.push(`  </testsuite>`);
+    }
+    lines.push(`</testsuites>`);
+    return `${lines.join('\n')}\n`;
+}
+function renderCase(entry) {
+    const attrs = `name="${esc(entry.name)}" classname="${esc(entry.suite)}" ` +
+        `time="${seconds(entry.durationMs)}"` +
+        (entry.file ? ` file="${esc(entry.file)}"` : '');
+    const body = [];
+    if (entry.status === 'skipped') {
+        body.push(`      <skipped/>`);
+    }
+    else if (entry.status === 'failed' || entry.status === 'error') {
+        // JUnit distinguishes the two, and so does the spine: `failed` is the
+        // system under test saying no, `error` is the test never getting an answer
+        // at all. Reporting both as failures is what makes a flaky environment
+        // look like a broken build.
+        const tag = entry.status === 'error' ? 'error' : 'failure';
+        const message = entry.failures[0] ?? entry.status;
+        body.push(`      <${tag} message="${esc(message)}" type="${entry.status}">` +
+            `${esc(entry.failures.join('\n'))}</${tag}>`);
+    }
+    if (entry.output.length > 0) {
+        body.push(`      <system-out>${esc(entry.output.join('\n'))}</system-out>`);
+    }
+    return body.length === 0
+        ? [`    <testcase ${attrs}/>`]
+        : [`    <testcase ${attrs}>`, ...body, `    </testcase>`];
+}
+function count(cases, status) {
+    return cases.filter((c) => c.status === status).length;
+}
+function seconds(ms) {
+    return (ms / 1000).toFixed(3);
+}
+/**
+ * Escapes for both attribute and text position, so one function covers every
+ * place a value can land.
+ *
+ * The control-character strip is not pedantry. XML 1.0 cannot represent them at
+ * all, and assertion messages routinely carry terminal colour codes — the
+ * console reporter's own output is full of them. One escape sequence is enough
+ * to make the file unparseable by the CI that has to read it, and a CI that
+ * cannot parse the report shows the build as broken rather than the report.
+ */
+function esc(value) {
+    return value
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/\r?\n/g, '&#10;');
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The format CI already knows how to read.
+ *
+ * It is a plugin, and that is the whole argument: JUnit is one of a dozen
+ * report formats a team might need, and none of them belong in the kernel.
+ * What the kernel owes a reporter is the event stream, and this plugin is the
+ * proof that the stream carries enough — every number in the file below is
+ * folded out of events, with no access to the runner's own result object.
+ */
+declare const _default: import("@speqkit/plugin-api").PluginSpec;
+export default _default;
+export { RunBuilder, renderJUnit } from './build.js';
+export type { JUnitRun, JUnitSuite, JUnitCase } from './build.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;;AACH,wBAqCE;AAgBF,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACpD,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,63 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { definePlugin } from '@speqkit/plugin-api';
+import { RunBuilder, renderJUnit } from './build.js';
+/**
+ * The format CI already knows how to read.
+ *
+ * It is a plugin, and that is the whole argument: JUnit is one of a dozen
+ * report formats a team might need, and none of them belong in the kernel.
+ * What the kernel owes a reporter is the event stream, and this plugin is the
+ * proof that the stream carries enough — every number in the file below is
+ * folded out of events, with no access to the runner's own result object.
+ */
+export default definePlugin({
+    name: '@speqkit/plugin-junit',
+    configSchema: {
+        type: 'object',
+        properties: {
+            output: { type: 'string' },
+            suiteName: { type: 'string' }
+        },
+        additionalProperties: false
+    },
+    setup(ctx) {
+        const builder = new RunBuilder();
+        let target;
+        ctx.defineReporter('junit', {
+            init(run) {
+                builder.reset();
+                target = targetFile(ctx.config(), run);
+            },
+            on(event) {
+                builder.on(event);
+            },
+            finalize() {
+                if (!target)
+                    return;
+                mkdirSync(dirname(target), { recursive: true });
+                const xml = renderJUnit(builder.result(), {
+                    name: ctx.config().suiteName ?? 'speq'
+                });
+                writeFileSync(target, xml);
+                process.stdout.write(`junit: ${target}\n`);
+            }
+        });
+    }
+});
+/**
+ * Defaults to `reports/junit.xml` — the stable directory, not `reports/<runId>/`.
+ *
+ * A workflow names one fixed path in `upload-artifact` and cannot interpolate a
+ * run id it will not learn until the step has already finished. The per-run
+ * directory is right for artifacts, which are addressed from inside the report;
+ * it is wrong for the report itself.
+ */
+function targetFile(config, run) {
+    const output = config.output ?? 'junit.xml';
+    if (isAbsolute(output))
+        return output;
+    return run.outputDir ? join(run.outputDir, output) : resolve(process.cwd(), output);
+}
+export { RunBuilder, renderJUnit } from './build.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC9D,OAAO,EAAE,YAAY,EAAwB,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AASpD;;;;;;;;GAQG;AACH,eAAe,YAAY,CAAC;IAC1B,IAAI,EAAE,uBAAuB;IAE7B,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC9B;QACD,oBAAoB,EAAE,KAAK;KAC5B;IAED,KAAK,CAAC,GAAG;QACP,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAA;QAChC,IAAI,MAA0B,CAAA;QAE9B,GAAG,CAAC,cAAc,CAAC,OAAO,EAAE;YAC1B,IAAI,CAAC,GAAoB;gBACvB,OAAO,CAAC,KAAK,EAAE,CAAA;gBACf,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,EAAe,EAAE,GAAG,CAAC,CAAA;YACrD,CAAC;YAED,EAAE,CAAC,KAAK;gBACN,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;YACnB,CAAC;YAED,QAAQ;gBACN,IAAI,CAAC,MAAM;oBAAE,OAAM;gBACnB,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC/C,MAAM,GAAG,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE;oBACxC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAe,CAAC,SAAS,IAAI,MAAM;iBACpD,CAAC,CAAA;gBACF,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;gBAC1B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,MAAM,IAAI,CAAC,CAAA;YAC5C,CAAC;SACF,CAAC,CAAA;IACJ,CAAC;CACF,CAAC,CAAA;AAEF;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,MAAmB,EAAE,GAAoB;IAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,WAAW,CAAA;IAC3C,IAAI,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAA;IACrC,OAAO,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAA;AACrF,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@speqkit/plugin-junit",
+  "version": "0.1.0",
+  "description": "JUnit XML from the run's event stream. What CI reads.",
+  "license": "MIT",
+  "author": "Stepan Kaziatko",
+  "homepage": "https://github.com/speqkit/speqkit#readme",
+  "bugs": "https://github.com/speqkit/speqkit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/speqkit/speqkit.git",
+    "directory": "packages/plugin-junit"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "speqkit-plugin"
+  ],
+  "peerDependencies": {
+    "@speqkit/plugin-api": "^0.4.0"
+  },
+  "devDependencies": {
+    "@speqkit/plugin-api": "0.4.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/build.ts

@@ -0,0 +1,213 @@
+import type { RunEvent, StepStatus } from '@speqkit/plugin-api'
+
+export interface JUnitCase {
+  name: string
+  suite: string
+  file?: string
+  status: StepStatus
+  durationMs: number
+  /** Why it failed, in the order the run found out. */
+  failures: string[]
+  /** Free-form lines CI viewers show under the case. */
+  output: string[]
+}
+
+export interface JUnitSuite {
+  name: string
+  cases: JUnitCase[]
+}
+
+export interface JUnitRun {
+  runId?: string
+  durationMs: number
+  suites: JUnitSuite[]
+}
+
+/**
+ * Folds the event stream into the shape JUnit wants.
+ *
+ * Kept apart from the file writing so it can be tested on a plain list of
+ * events, and so `speq report` and a live run go through exactly the same
+ * code — the event stream being sufficient on its own is the property worth
+ * protecting.
+ */
+export class RunBuilder {
+  #suites: JUnitSuite[] = []
+  #byName = new Map<string, JUnitSuite>()
+  #suite = '(inline)'
+  #case: JUnitCase | undefined
+  #runId: string | undefined
+  #durationMs = 0
+
+  on(event: RunEvent): void {
+    switch (event.type) {
+      case 'run.started':
+        this.reset()
+        this.#runId = event.runId
+        break
+
+      // Tests do not carry their suite on the event; the bracketing does. That
+      // holds on replay too, because the log preserves the order.
+      case 'suite.started':
+        this.#suite = event.suite
+        break
+
+      case 'test.started':
+        this.#case = {
+          name: event.test,
+          suite: this.#suite,
+          file: event.source,
+          status: 'passed',
+          durationMs: 0,
+          failures: [],
+          output: []
+        }
+        break
+
+      case 'step.finished':
+        if (this.#case && event.status !== 'passed' && event.status !== 'skipped') {
+          const label = event.stepId ? `${event.stepId} (${event.stepType})` : event.stepType
+          this.#case.failures.push(`step ${label}: ${event.message ?? event.status}`)
+        }
+        break
+
+      case 'assertion.evaluated':
+        if (this.#case && !event.passed) {
+          this.#case.failures.push(`assertion ${event.assertionType}: ${event.message}`)
+        }
+        break
+
+      case 'artifact.attached':
+        this.#case?.output.push(`[[ATTACHMENT|${event.path ?? event.name}]]`)
+        break
+
+      case 'test.finished': {
+        const entry = this.#case
+        this.#case = undefined
+        if (!entry) break
+        entry.status = event.status
+        entry.durationMs = event.durationMs
+        this.suiteFor(entry.suite).cases.push(entry)
+        break
+      }
+
+      case 'run.finished':
+        this.#durationMs = event.durationMs
+        break
+    }
+  }
+
+  /**
+   * A reporter is registered once and may see several runs in one process —
+   * `speq report` replaying after a run, or a long-lived editor session. Two
+   * runs' worth of cases in one file would be nobody's intent.
+   */
+  reset(): void {
+    this.#suites = []
+    this.#byName = new Map()
+    this.#suite = '(inline)'
+    this.#case = undefined
+    this.#runId = undefined
+    this.#durationMs = 0
+  }
+
+  result(): JUnitRun {
+    return { runId: this.#runId, durationMs: this.#durationMs, suites: this.#suites }
+  }
+
+  private suiteFor(name: string): JUnitSuite {
+    let suite = this.#byName.get(name)
+    if (!suite) {
+      suite = { name, cases: [] }
+      this.#byName.set(name, suite)
+      this.#suites.push(suite)
+    }
+    return suite
+  }
+}
+
+export interface RenderOptions {
+  name: string
+}
+
+export function renderJUnit(run: JUnitRun, options: RenderOptions): string {
+  const all = run.suites.flatMap((s) => s.cases)
+  const lines: string[] = [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<testsuites name="${esc(options.name)}" tests="${all.length}" ` +
+      `failures="${count(all, 'failed')}" errors="${count(all, 'error')}" ` +
+      `skipped="${count(all, 'skipped')}" time="${seconds(run.durationMs)}">`
+  ]
+
+  for (const suite of run.suites) {
+    lines.push(
+      `  <testsuite name="${esc(suite.name)}" tests="${suite.cases.length}" ` +
+        `failures="${count(suite.cases, 'failed')}" errors="${count(suite.cases, 'error')}" ` +
+        `skipped="${count(suite.cases, 'skipped')}" ` +
+        `time="${seconds(suite.cases.reduce((sum, c) => sum + c.durationMs, 0))}">`
+    )
+    for (const entry of suite.cases) lines.push(...renderCase(entry))
+    lines.push(`  </testsuite>`)
+  }
+
+  lines.push(`</testsuites>`)
+  return `${lines.join('\n')}\n`
+}
+
+function renderCase(entry: JUnitCase): string[] {
+  const attrs =
+    `name="${esc(entry.name)}" classname="${esc(entry.suite)}" ` +
+    `time="${seconds(entry.durationMs)}"` +
+    (entry.file ? ` file="${esc(entry.file)}"` : '')
+
+  const body: string[] = []
+  if (entry.status === 'skipped') {
+    body.push(`      <skipped/>`)
+  } else if (entry.status === 'failed' || entry.status === 'error') {
+    // JUnit distinguishes the two, and so does the spine: `failed` is the
+    // system under test saying no, `error` is the test never getting an answer
+    // at all. Reporting both as failures is what makes a flaky environment
+    // look like a broken build.
+    const tag = entry.status === 'error' ? 'error' : 'failure'
+    const message = entry.failures[0] ?? entry.status
+    body.push(
+      `      <${tag} message="${esc(message)}" type="${entry.status}">` +
+        `${esc(entry.failures.join('\n'))}</${tag}>`
+    )
+  }
+  if (entry.output.length > 0) {
+    body.push(`      <system-out>${esc(entry.output.join('\n'))}</system-out>`)
+  }
+
+  return body.length === 0
+    ? [`    <testcase ${attrs}/>`]
+    : [`    <testcase ${attrs}>`, ...body, `    </testcase>`]
+}
+
+function count(cases: JUnitCase[], status: StepStatus): number {
+  return cases.filter((c) => c.status === status).length
+}
+
+function seconds(ms: number): string {
+  return (ms / 1000).toFixed(3)
+}
+
+/**
+ * Escapes for both attribute and text position, so one function covers every
+ * place a value can land.
+ *
+ * The control-character strip is not pedantry. XML 1.0 cannot represent them at
+ * all, and assertion messages routinely carry terminal colour codes — the
+ * console reporter's own output is full of them. One escape sequence is enough
+ * to make the file unparseable by the CI that has to read it, and a CI that
+ * cannot parse the report shows the build as broken rather than the report.
+ */
+function esc(value: string): string {
+  return value
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\r?\n/g, '&#10;')
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+import { definePlugin, type ReporterContext } from '@speqkit/plugin-api'
+import { RunBuilder, renderJUnit } from './build.js'
+
+interface JUnitConfig {
+  /** Where to write, relative to `reports/` unless absolute. */
+  output?: string
+  /** The `name` attribute on `<testsuites>`. */
+  suiteName?: string
+}
+
+/**
+ * The format CI already knows how to read.
+ *
+ * It is a plugin, and that is the whole argument: JUnit is one of a dozen
+ * report formats a team might need, and none of them belong in the kernel.
+ * What the kernel owes a reporter is the event stream, and this plugin is the
+ * proof that the stream carries enough — every number in the file below is
+ * folded out of events, with no access to the runner's own result object.
+ */
+export default definePlugin({
+  name: '@speqkit/plugin-junit',
+
+  configSchema: {
+    type: 'object',
+    properties: {
+      output: { type: 'string' },
+      suiteName: { type: 'string' }
+    },
+    additionalProperties: false
+  },
+
+  setup(ctx) {
+    const builder = new RunBuilder()
+    let target: string | undefined
+
+    ctx.defineReporter('junit', {
+      init(run: ReporterContext) {
+        builder.reset()
+        target = targetFile(ctx.config<JUnitConfig>(), run)
+      },
+
+      on(event) {
+        builder.on(event)
+      },
+
+      finalize() {
+        if (!target) return
+        mkdirSync(dirname(target), { recursive: true })
+        const xml = renderJUnit(builder.result(), {
+          name: ctx.config<JUnitConfig>().suiteName ?? 'speq'
+        })
+        writeFileSync(target, xml)
+        process.stdout.write(`junit: ${target}\n`)
+      }
+    })
+  }
+})
+
+/**
+ * Defaults to `reports/junit.xml` — the stable directory, not `reports/<runId>/`.
+ *
+ * A workflow names one fixed path in `upload-artifact` and cannot interpolate a
+ * run id it will not learn until the step has already finished. The per-run
+ * directory is right for artifacts, which are addressed from inside the report;
+ * it is wrong for the report itself.
+ */
+function targetFile(config: JUnitConfig, run: ReporterContext): string {
+  const output = config.output ?? 'junit.xml'
+  if (isAbsolute(output)) return output
+  return run.outputDir ? join(run.outputDir, output) : resolve(process.cwd(), output)
+}
+
+export { RunBuilder, renderJUnit } from './build.js'
+export type { JUnitRun, JUnitSuite, JUnitCase } from './build.js'