@robhowley/pi-structured-return 0.1.0

package/extensions/structured-return/src/parsers/eslint-json.test.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./eslint-json";
+import type { RunContext } from "../types";
+
+function makeCtx(stdout: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "eslint-test-"));
+  const stdoutPath = path.join(dir, "stdout");
+  fs.writeFileSync(stdoutPath, stdout);
+  return {
+    command: "eslint . -f json",
+    argv: ["eslint", ".", "-f", "json"],
+    cwd,
+    artifactPaths: [],
+    stdoutPath,
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+describe("eslint-json parser", () => {
+  it("multiple errors across multiple files → correct relative paths, correct failure count, status fail", async () => {
+    const cwd = "/project";
+    const stdout = JSON.stringify([
+      {
+        filePath: "/project/src/foo.ts",
+        messages: [
+          { line: 10, ruleId: "@typescript-eslint/no-explicit-any", message: "Unexpected any." },
+          { line: 12, ruleId: "@typescript-eslint/no-explicit-any", message: "Unexpected any." },
+        ],
+      },
+      {
+        filePath: "/project/src/bar.ts",
+        messages: [{ line: 3, ruleId: "no-unused-vars", message: "x is defined but never used." }],
+      },
+    ]);
+    const result = await parser.parse(makeCtx(stdout, cwd));
+    expect(result.status).toBe("fail");
+    expect(result.failures).toHaveLength(3);
+    expect(result.failures![0].file).toBe("src/foo.ts");
+    expect(result.failures![1].file).toBe("src/foo.ts");
+    expect(result.failures![2].file).toBe("src/bar.ts");
+    expect(result.failures![0].file).not.toContain("/project");
+  });
+
+  it("no errors → empty failures, status pass", async () => {
+    const stdout = JSON.stringify([{ filePath: "/project/src/foo.ts", messages: [] }]);
+    const result = await parser.parse(makeCtx(stdout));
+    expect(result.status).toBe("pass");
+    expect(result.failures).toHaveLength(0);
+  });
+
+  it("empty stdout → no crash, status pass", async () => {
+    const result = await parser.parse(makeCtx(""));
+    expect(result.status).toBe("pass");
+    expect(result.failures).toHaveLength(0);
+  });
+});

package/extensions/structured-return/src/parsers/eslint-json.ts

@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserModule } from "../types";
+
+const parser: ParserModule = {
+  id: "eslint-json",
+  async parse(ctx) {
+    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8").trim();
+    const files = stdout ? JSON.parse(stdout) : [];
+    const failures = [] as Array<{ id: string; file?: string; line?: number; message?: string; rule?: string }>;
+    for (const file of Array.isArray(files) ? files : []) {
+      const relPath = path.relative(ctx.cwd, file.filePath);
+      for (const msg of file.messages ?? []) {
+        failures.push({
+          id: `${relPath}:${msg.line}:${msg.ruleId ?? "unknown"}`,
+          file: relPath,
+          line: msg.line,
+          message: msg.message,
+          rule: msg.ruleId ?? undefined,
+        });
+      }
+    }
+    return {
+      tool: "eslint",
+      status: failures.length > 0 ? "fail" : "pass",
+      summary: failures.length > 0 ? `${failures.length} lint errors` : "no lint errors",
+      failures,
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;

package/extensions/structured-return/src/parsers/junit-xml.test.ts

@@ -0,0 +1,169 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./junit-xml";
+import type { RunContext } from "../types";
+
+function makeCtx(xml: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "junit-test-"));
+  const artifactPath = path.join(dir, "report.xml");
+  fs.writeFileSync(artifactPath, xml);
+  return {
+    command: "gradle test",
+    argv: ["gradle", "test"],
+    cwd,
+    artifactPaths: [artifactPath],
+    stdoutPath: path.join(dir, "stdout"),
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+const PASSING = (name: string, classname = "com.example.MyTest") =>
+  `<testcase name="${name}" classname="${classname}" time="0.001"/>`;
+
+const FAILING = (
+  name: string,
+  classname: string,
+  message: string,
+  type = "AssertionError",
+  file?: string,
+  line?: number
+) => {
+  const fileAttr = file ? ` file="${file}"` : "";
+  const lineAttr = line !== undefined ? ` line="${line}"` : "";
+  return `<testcase name="${name}" classname="${classname}"${fileAttr}${lineAttr} time="0.001">
+    <failure message="${message}" type="${type}">full details here</failure>
+  </testcase>`;
+};
+
+const ERROR = (name: string, classname: string, message: string, type = "RuntimeError") =>
+  `<testcase name="${name}" classname="${classname}" time="0.001">
+    <error message="${message}" type="${type}">stack trace</error>
+  </testcase>`;
+
+describe("junit-xml parser", () => {
+  describe("testsuites wrapper (multi-suite)", () => {
+    it("mix of passed and failed → status fail, correct counts", async () => {
+      const xml = `<?xml version="1.0"?>
+        <testsuites>
+          <testsuite name="suite1" tests="2" failures="1" errors="0">
+            ${PASSING("test_a")}
+            ${FAILING("test_b", "com.example.MyTest", "expected 2 but was 1")}
+          </testsuite>
+          <testsuite name="suite2" tests="2" failures="0" errors="0">
+            ${PASSING("test_c")}
+            ${PASSING("test_d")}
+          </testsuite>
+        </testsuites>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.status).toBe("fail");
+      expect(result.summary).toBe("1 failed, 3 passed");
+      expect(result.failures).toHaveLength(1);
+    });
+
+    it("all passing → status pass", async () => {
+      const xml = `<testsuites>
+        <testsuite name="suite" tests="2" failures="0" errors="0">
+          ${PASSING("test_a")}
+          ${PASSING("test_b")}
+        </testsuite>
+      </testsuites>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.status).toBe("pass");
+      expect(result.summary).toBe("2 passed");
+      expect(result.failures).toHaveLength(0);
+    });
+  });
+
+  describe("bare testsuite (no wrapper)", () => {
+    it("single testsuite at root → parsed correctly", async () => {
+      const xml = `<testsuite name="suite" tests="2" failures="1" errors="0">
+        ${PASSING("test_a")}
+        ${FAILING("test_b", "com.example.MyTest", "assert failed")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.status).toBe("fail");
+      expect(result.summary).toBe("1 failed, 1 passed");
+    });
+  });
+
+  describe("error elements", () => {
+    it("error counts as failure, message surfaced", async () => {
+      const xml = `<testsuite name="suite" tests="2" failures="0" errors="1">
+        ${PASSING("test_a")}
+        ${ERROR("test_b", "com.example.MyTest", "NullPointerException", "java.lang.NullPointerException")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.status).toBe("fail");
+      expect(result.summary).toBe("1 failed, 1 passed");
+      expect(result.failures![0].message).toBe("NullPointerException");
+      expect(result.failures![0].rule).toBe("java.lang.NullPointerException");
+    });
+  });
+
+  describe("file and line resolution", () => {
+    it("file on testcase → relativized to cwd", async () => {
+      const xml = `<testsuite name="suite" tests="1" failures="1" errors="0">
+        ${FAILING("test_b", "MyTest", "oops", "AssertionError", "/project/src/test/MyTest.java", 42)}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml, "/project"));
+      expect(result.failures![0].file).toBe("src/test/MyTest.java");
+      expect(result.failures![0].line).toBe(42);
+    });
+
+    it("file on testsuite (not testcase) → used as fallback", async () => {
+      const xml = `<testsuite name="suite" tests="1" failures="1" errors="0" file="src/spec/foo_spec.rb">
+        ${FAILING("test_b", "MyTest", "oops")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml, "/project"));
+      expect(result.failures![0].file).toBe("src/spec/foo_spec.rb");
+    });
+
+    it("no file attr → classname converted to java path", async () => {
+      const xml = `<testsuite name="suite" tests="1" failures="1" errors="0">
+        ${FAILING("test_b", "com.example.service.MyTest", "oops")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.failures![0].file).toBe("com/example/service/MyTest.java");
+    });
+  });
+
+  describe("failure message", () => {
+    it("message attr surfaced directly", async () => {
+      const xml = `<testsuite name="suite" tests="1" failures="1" errors="0">
+        ${FAILING("test_b", "MyTest", "expected: 99 but was: 12")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.failures![0].message).toBe("expected: 99 but was: 12");
+    });
+
+    it("failure type surfaced as rule", async () => {
+      const xml = `<testsuite name="suite" tests="1" failures="1" errors="0">
+        ${FAILING("test_b", "MyTest", "oops", "org.junit.ComparisonFailure")}
+      </testsuite>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.failures![0].rule).toBe("org.junit.ComparisonFailure");
+    });
+  });
+
+  describe("multi-suite totals", () => {
+    it("failures and errors summed across suites", async () => {
+      const xml = `<testsuites>
+        <testsuite name="s1" tests="2" failures="1" errors="0">
+          ${PASSING("a")}
+          ${FAILING("b", "Foo", "oops")}
+        </testsuite>
+        <testsuite name="s2" tests="2" failures="0" errors="1">
+          ${PASSING("c")}
+          ${ERROR("d", "Bar", "boom")}
+        </testsuite>
+      </testsuites>`;
+      const result = await parser.parse(makeCtx(xml));
+      expect(result.status).toBe("fail");
+      expect(result.summary).toBe("2 failed, 2 passed");
+      expect(result.failures).toHaveLength(2);
+    });
+  });
+});

package/extensions/structured-return/src/parsers/junit-xml.ts

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { XMLParser } from "fast-xml-parser";
+import type { ParserModule, ParsedFailure } from "../types";
+
+interface JUnitFailureOrError {
+  message?: string;
+  type?: string;
+  "#text"?: string;
+}
+
+interface JUnitTestCase {
+  name?: string;
+  classname?: string;
+  file?: string;
+  line?: string | number;
+  failure?: JUnitFailureOrError;
+  error?: JUnitFailureOrError;
+}
+
+interface JUnitTestSuite {
+  name?: string;
+  file?: string;
+  tests?: string | number;
+  failures?: string | number;
+  errors?: string | number;
+  testcase?: JUnitTestCase[];
+}
+
+interface JUnitDocument {
+  testsuites?: { testsuite?: JUnitTestSuite[] };
+  testsuite?: JUnitTestSuite[];
+}
+
+const xmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "",
+  isArray: (name) => ["testsuite", "testcase"].includes(name),
+});
+
+function resolveFile(tc: JUnitTestCase, suite: JUnitTestSuite, cwd: string): string | undefined {
+  const raw = tc.file ?? suite.file;
+  if (raw) return path.relative(cwd, path.resolve(cwd, raw));
+  // Java/JVM: classname like "com.example.MyTest" → "com/example/MyTest.java"
+  if (tc.classname) return tc.classname.replace(/\./g, "/") + ".java";
+  return undefined;
+}
+
+const parser: ParserModule = {
+  id: "junit-xml",
+  async parse(ctx) {
+    const artifactPath = ctx.artifactPaths[0] ?? ctx.stdoutPath;
+    const xml = fs.readFileSync(artifactPath, "utf8");
+    const doc = xmlParser.parse(xml) as JUnitDocument;
+
+    const suites: JUnitTestSuite[] = doc.testsuites?.testsuite ?? doc.testsuite ?? [];
+
+    let totalTests = 0;
+    let totalFailed = 0;
+    const failures: ParsedFailure[] = [];
+
+    for (const suite of suites) {
+      totalTests += Number(suite.tests ?? 0);
+      totalFailed += Number(suite.failures ?? 0) + Number(suite.errors ?? 0);
+
+      for (const tc of suite.testcase ?? []) {
+        const problem = tc.failure ?? tc.error;
+        if (!problem) continue;
+
+        const file = resolveFile(tc, suite, ctx.cwd);
+        const line = tc.line !== undefined ? Number(tc.line) : undefined;
+        const id = [file, line, tc.name].filter(Boolean).join(":");
+
+        failures.push({
+          id: id || String(failures.length),
+          file,
+          line: Number.isNaN(line) ? undefined : line,
+          message: problem.message ?? problem["#text"]?.trim().split("\n")[0],
+          rule: problem.type,
+        });
+      }
+    }
+
+    const passed = totalTests - totalFailed;
+
+    return {
+      tool: "junit",
+      status: totalFailed > 0 ? "fail" : "pass",
+      summary: totalFailed > 0 ? `${totalFailed} failed, ${passed} passed` : `${passed} passed`,
+      failures,
+      artifact: ctx.artifactPaths[0],
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;

package/extensions/structured-return/src/parsers/minitest-text.test.ts

@@ -0,0 +1,110 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./minitest-text";
+import type { RunContext } from "../types";
+
+function makeCtx(stdout: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "minitest-text-test-"));
+  const stdoutPath = path.join(dir, "stdout");
+  fs.writeFileSync(stdoutPath, stdout);
+  return {
+    command: "ruby test/math_test.rb",
+    argv: ["ruby", "test/math_test.rb"],
+    cwd,
+    artifactPaths: [],
+    stdoutPath,
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+const PASSING_OUTPUT = `Run options: --seed 12345
+
+# Running:
+
+...
+
+Finished in 0.001s, 3000.0 runs/s, 3000.0 assertions/s.
+
+3 runs, 3 assertions, 0 failures, 0 errors, 0 skips
+`;
+
+const MIXED_OUTPUT = `Run options: --seed 12345
+
+# Running:
+
+EF.
+
+Finished in 0.001s, 3000.0 runs/s, 2000.0 assertions/s.
+
+  1) Error:
+MathTest#test_does_not_divide_by_zero:
+ZeroDivisionError: divided by 0
+    /project/test/math_test.rb:13:in 'Integer#/'
+    /project/test/math_test.rb:13:in 'MathTest#test_does_not_divide_by_zero'
+
+  2) Failure:
+MathTest#test_multiplies_two_numbers_correctly [/project/test/math_test.rb:9]:
+Expected: 99
+  Actual: 12
+
+3 runs, 2 assertions, 1 failures, 1 errors, 0 skips
+`;
+
+describe("minitest-text parser", () => {
+  it("all passing → status pass, summary reflects passed count", async () => {
+    const result = await parser.parse(makeCtx(PASSING_OUTPUT));
+    expect(result.status).toBe("pass");
+    expect(result.summary).toBe("3 passed");
+    expect(result.failures).toHaveLength(0);
+  });
+
+  it("mix of failure and error → status fail, correct counts", async () => {
+    const result = await parser.parse(makeCtx(MIXED_OUTPUT, "/project"));
+    expect(result.status).toBe("fail");
+    expect(result.summary).toBe("2 failed, 1 passed");
+    expect(result.failures).toHaveLength(2);
+  });
+
+  it("assertion failure → file, line, and expected/actual message", async () => {
+    const result = await parser.parse(makeCtx(MIXED_OUTPUT, "/project"));
+    const failure = result.failures!.find((f) => f.id?.includes("multiplies"));
+    expect(failure?.file).toBe("test/math_test.rb");
+    expect(failure?.line).toBe(9);
+    expect(failure?.message).toBe("Expected: 99 / Actual: 12");
+  });
+
+  it("unexpected error → file, line from backtrace, exception message only", async () => {
+    const result = await parser.parse(makeCtx(MIXED_OUTPUT, "/project"));
+    const error = result.failures!.find((f) => f.id?.includes("divide_by_zero"));
+    expect(error?.file).toBe("test/math_test.rb");
+    expect(error?.line).toBe(13);
+    expect(error?.message).toBe("divided by 0");
+  });
+
+  it("absolute paths in output → made relative to cwd", async () => {
+    const result = await parser.parse(makeCtx(MIXED_OUTPUT, "/project"));
+    for (const f of result.failures!) {
+      expect(f.file).not.toContain("/project");
+    }
+  });
+
+  it("relative paths in output → kept relative", async () => {
+    const output = MIXED_OUTPUT.replace(/\/project\/test\//g, "./test/").replace(/\/project\/test\//g, "./test/");
+    const result = await parser.parse(makeCtx(output, "/project"));
+    const failure = result.failures!.find((f) => f.id?.includes("multiplies"));
+    expect(failure?.file).toBe("test/math_test.rb");
+  });
+
+  it("no minitest output → status error, no crash", async () => {
+    const result = await parser.parse(makeCtx("something completely different"));
+    expect(result.status).toBe("error");
+  });
+
+  it("empty stdout → status error, no crash", async () => {
+    const result = await parser.parse(makeCtx(""));
+    expect(result.status).toBe("error");
+  });
+});

package/extensions/structured-return/src/parsers/minitest-text.ts

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserModule, ParsedFailure } from "../types";
+
+/**
+ * Parses minitest's default text output. No flags or reporters required —
+ * works with plain `ruby test/my_test.rb` or `bundle exec ruby test/my_test.rb`.
+ */
+const parser: ParserModule = {
+  id: "minitest-text",
+  async parse(ctx) {
+    const output = fs.readFileSync(ctx.stdoutPath, "utf8");
+
+    // "3 runs, 2 assertions, 1 failures, 1 errors, 0 skips"
+    const summaryMatch = output.match(/(\d+) runs?, \d+ assertions?, (\d+) failures?, (\d+) errors?, (\d+) skips?/);
+    if (!summaryMatch) {
+      return { tool: "minitest", status: "error", summary: "no minitest output found", logPath: ctx.logPath };
+    }
+
+    const totalRuns = parseInt(summaryMatch[1], 10);
+    const failureCount = parseInt(summaryMatch[2], 10);
+    const errorCount = parseInt(summaryMatch[3], 10);
+    const skipCount = parseInt(summaryMatch[4], 10);
+    const totalFailed = failureCount + errorCount;
+    const passed = totalRuns - totalFailed - skipCount;
+
+    const failures = parseBlocks(output, ctx.cwd);
+
+    return {
+      tool: "minitest",
+      status: totalFailed > 0 ? "fail" : "pass",
+      summary: totalFailed > 0 ? `${totalFailed} failed, ${passed} passed` : `${passed} passed`,
+      failures,
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;
+
+function parseBlocks(output: string, cwd: string): ParsedFailure[] {
+  const failures: ParsedFailure[] = [];
+  const lines = output.split("\n");
+  let i = 0;
+
+  while (i < lines.length) {
+    const headerMatch = lines[i].match(/^\s+\d+\) (Failure|Error):$/);
+    if (!headerMatch) {
+      i++;
+      continue;
+    }
+
+    const type = headerMatch[1];
+    i++;
+
+    if (type === "Failure") {
+      // "ClassName#method [file:line]:"
+      const nameMatch = lines[i]?.match(/^(.+?)\s+\[(.+):(\d+)\]:$/);
+      if (nameMatch) {
+        const [, id, rawFile, lineStr] = nameMatch;
+        i++;
+        // Message lines until blank line
+        const msgLines: string[] = [];
+        while (i < lines.length && lines[i].trim() !== "") {
+          msgLines.push(lines[i].trim());
+          i++;
+        }
+        failures.push({
+          id,
+          file: path.relative(cwd, path.resolve(cwd, rawFile)),
+          line: parseInt(lineStr, 10),
+          message: msgLines.filter(Boolean).join(" / ") || undefined,
+        });
+      }
+    } else {
+      // Error — "ClassName#method:"
+      const nameMatch = lines[i]?.match(/^(.+):$/);
+      if (nameMatch) {
+        const id = nameMatch[1];
+        i++;
+        // "ExceptionClass: message"
+        const exceptionLine = lines[i]?.trim() ?? "";
+        const colonIdx = exceptionLine.indexOf(": ");
+        const message = colonIdx !== -1 ? exceptionLine.slice(colonIdx + 2) : exceptionLine;
+        i++;
+        // First backtrace line: "    file.rb:line:in 'method'"
+        const backtraceMatch = lines[i]?.match(/^\s+(.+\.rb):(\d+):/);
+        failures.push({
+          id,
+          file: backtraceMatch ? path.relative(cwd, path.resolve(cwd, backtraceMatch[1])) : undefined,
+          line: backtraceMatch ? parseInt(backtraceMatch[2], 10) : undefined,
+          message: message || undefined,
+        });
+      }
+    }
+  }
+
+  return failures;
+}

package/extensions/structured-return/src/parsers/pytest-json-report.test.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./pytest-json-report";
+import type { RunContext } from "../types";
+
+function makeCtx(report: object | null): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pytest-test-"));
+  const artifactPath = path.join(dir, "report.json");
+  if (report !== null) {
+    fs.writeFileSync(artifactPath, JSON.stringify(report));
+  }
+  return {
+    command: "pytest --json-report",
+    argv: ["pytest", "--json-report"],
+    cwd: "/project",
+    artifactPaths: [artifactPath],
+    stdoutPath: path.join(dir, "stdout"),
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+describe("pytest-json-report parser", () => {
+  it("mix of passed and failed tests → correct counts, status fail", async () => {
+    const report = {
+      summary: { passed: 3 },
+      tests: [
+        { nodeid: "test_foo.py::test_a", outcome: "passed" },
+        { nodeid: "test_foo.py::test_b", outcome: "failed", longrepr: "AssertionError: assert False" },
+        { nodeid: "test_foo.py::test_c", outcome: "failed", longrepr: "AssertionError: assert 1 == 2" },
+      ],
+    };
+    const result = await parser.parse(makeCtx(report));
+    expect(result.status).toBe("fail");
+    expect(result.failures).toHaveLength(2);
+    expect(result.summary).toBe("2 failed, 3 passed");
+  });
+
+  it("all passing → status pass, summary reflects passed count", async () => {
+    const report = {
+      summary: { passed: 5 },
+      tests: [
+        { nodeid: "test_foo.py::test_a", outcome: "passed" },
+        { nodeid: "test_foo.py::test_b", outcome: "passed" },
+      ],
+    };
+    const result = await parser.parse(makeCtx(report));
+    expect(result.status).toBe("pass");
+    expect(result.failures).toHaveLength(0);
+    expect(result.summary).toBe("5 passed");
+  });
+
+  it("failed test with longrepr → first line surfaced as message", async () => {
+    const report = {
+      summary: { passed: 0 },
+      tests: [
+        {
+          nodeid: "test_foo.py::test_a",
+          outcome: "failed",
+          longrepr: "AssertionError: assert False\nfull traceback line 2\nfull traceback line 3",
+        },
+      ],
+    };
+    const result = await parser.parse(makeCtx(report));
+    expect(result.failures![0].message).toBe("AssertionError: assert False");
+  });
+
+  it("missing artifact file → throws", async () => {
+    const ctx = makeCtx(null);
+    // point artifact at a file that doesn't exist
+    ctx.artifactPaths = ["/nonexistent/path/report.json"];
+    await expect(parser.parse(ctx)).rejects.toThrow();
+  });
+});

package/extensions/structured-return/src/parsers/pytest-json-report.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import type { ParserModule } from "../types";
+
+interface PytestTest {
+  nodeid: string;
+  outcome: string;
+  longrepr?: string;
+}
+
+interface PytestReport {
+  tests?: PytestTest[];
+  summary?: { passed?: number };
+}
+
+const parser: ParserModule = {
+  id: "pytest-json-report",
+  async parse(ctx) {
+    const artifact = ctx.artifactPaths[0];
+    const data = JSON.parse(fs.readFileSync(artifact, "utf8")) as PytestReport;
+    const tests = Array.isArray(data.tests) ? data.tests : [];
+    const failures = tests
+      .filter((t) => t.outcome === "failed")
+      .map((t) => ({
+        id: t.nodeid,
+        file: String(t.nodeid || "").split("::")[0] || undefined,
+        message: typeof t.longrepr === "string" ? t.longrepr.split("\n")[0] : "test failed",
+      }));
+    const failed = failures.length;
+    const passed = Number(data.summary?.passed ?? 0);
+    return {
+      tool: "pytest",
+      status: failed > 0 ? "fail" : "pass",
+      summary: failed > 0 ? `${failed} failed, ${passed} passed` : `${passed} passed`,
+      failures,
+      artifact,
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;