@robhowley/pi-structured-return 0.1.0

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

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./rspec-json";
+import type { RunContext } from "../types";
+
+function makeCtx(stdout: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "rspec-test-"));
+  const stdoutPath = path.join(dir, "stdout");
+  fs.writeFileSync(stdoutPath, stdout);
+  return {
+    command: "bundle exec rspec --format json",
+    argv: ["bundle", "exec", "rspec", "--format", "json"],
+    cwd,
+    artifactPaths: [],
+    stdoutPath,
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+const passing = (id: string, file: string, line: number): object => ({
+  id,
+  full_description: id,
+  status: "passed",
+  file_path: file,
+  line_number: line,
+});
+
+const failing = (id: string, file: string, line: number, message: string): object => ({
+  id,
+  full_description: id,
+  status: "failed",
+  file_path: file,
+  line_number: line,
+  exception: {
+    class: "RSpec::Expectations::ExpectationNotMetError",
+    message,
+    backtrace: [`${file}:${line}:in 'block (2 levels) in <top (required)>'`],
+  },
+});
+
+function report(examples: object[], failureCount: number, pendingCount = 0): string {
+  return JSON.stringify({
+    examples,
+    summary: {
+      example_count: examples.length,
+      failure_count: failureCount,
+      pending_count: pendingCount,
+    },
+  });
+}
+
+describe("rspec-json parser", () => {
+  it("mix of passed and failed → status fail, correct counts, failures listed", async () => {
+    const cwd = "/project";
+    const stdout = report(
+      [
+        passing("Foo does something", "./spec/foo_spec.rb", 5),
+        failing("Foo blows up", "./spec/foo_spec.rb", 10, "expected: 2\n     got: 1"),
+        passing("Bar works", "./spec/bar_spec.rb", 3),
+        failing("Bar also blows up", "./spec/bar_spec.rb", 8, "expected true\n     got false"),
+      ],
+      2
+    );
+    const result = await parser.parse(makeCtx(stdout, cwd));
+    expect(result.status).toBe("fail");
+    expect(result.summary).toBe("2 failed, 2 passed");
+    expect(result.failures).toHaveLength(2);
+    expect(result.failures![0].file).toBe("spec/foo_spec.rb");
+    expect(result.failures![1].file).toBe("spec/bar_spec.rb");
+  });
+
+  it("all passing → status pass, summary reflects passed count", async () => {
+    const stdout = report(
+      [passing("Foo works", "./spec/foo_spec.rb", 5), passing("Bar works", "./spec/bar_spec.rb", 3)],
+      0
+    );
+    const result = await parser.parse(makeCtx(stdout));
+    expect(result.status).toBe("pass");
+    expect(result.summary).toBe("2 passed");
+    expect(result.failures).toHaveLength(0);
+  });
+
+  it("failure message → expected/got pair joined, stops at blank line", async () => {
+    const stdout = report(
+      [failing("Foo blows up", "./spec/foo_spec.rb", 10, "\nexpected: 2\n     got: 1\n\n(compared using ==)\n")],
+      1
+    );
+    const result = await parser.parse(makeCtx(stdout));
+    expect(result.failures![0].message).toBe("expected: 2 / got: 1");
+  });
+
+  it("file_path with ./ prefix → stripped in relative path output", async () => {
+    const stdout = report([failing("Foo blows up", "./spec/foo_spec.rb", 10, "error")], 1);
+    const result = await parser.parse(makeCtx(stdout, "/project"));
+    expect(result.failures![0].file).toBe("spec/foo_spec.rb");
+    expect(result.failures![0].file).not.toMatch(/^\.\//);
+  });
+
+  it("line number preserved on failure", async () => {
+    const stdout = report([failing("Foo blows up", "./spec/foo_spec.rb", 42, "error")], 1);
+    const result = await parser.parse(makeCtx(stdout));
+    expect(result.failures![0].line).toBe(42);
+  });
+
+  it("pending tests excluded from passed count", async () => {
+    const stdout = report(
+      [
+        passing("Foo works", "./spec/foo_spec.rb", 5),
+        { ...passing("Pending thing", "./spec/foo_spec.rb", 20), status: "pending" },
+      ],
+      0,
+      1
+    );
+    const result = await parser.parse(makeCtx(stdout));
+    expect(result.status).toBe("pass");
+    expect(result.summary).toBe("1 passed");
+  });
+
+  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/rspec-json.ts

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserModule } from "../types";
+
+interface RSpecException {
+  class: string;
+  message: string;
+  backtrace: string[];
+}
+
+interface RSpecExample {
+  id: string;
+  full_description: string;
+  status: "passed" | "failed" | "pending";
+  file_path: string;
+  line_number: number;
+  exception?: RSpecException;
+}
+
+interface RSpecReport {
+  examples: RSpecExample[];
+  summary: {
+    example_count: number;
+    failure_count: number;
+    pending_count: number;
+  };
+}
+
+/** Take all non-empty lines before the first blank line — captures expected/got pairs intact. */
+function firstParagraph(message: string): string {
+  const lines = message.trim().split("\n");
+  const paragraph: string[] = [];
+  for (const line of lines) {
+    if (line.trim() === "") break;
+    paragraph.push(line.trim());
+  }
+  return paragraph.join(" / ");
+}
+
+const parser: ParserModule = {
+  id: "rspec-json",
+  async parse(ctx) {
+    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8").trim();
+    const report = stdout ? (JSON.parse(stdout) as RSpecReport) : null;
+    if (!report) {
+      return {
+        tool: "rspec",
+        status: "error",
+        summary: "no output",
+        logPath: ctx.logPath,
+      };
+    }
+
+    const failures = report.examples
+      .filter((e) => e.status === "failed")
+      .map((e) => ({
+        id: e.id,
+        file: path.relative(ctx.cwd, path.resolve(ctx.cwd, e.file_path)),
+        line: e.line_number,
+        message: e.exception ? firstParagraph(e.exception.message) : e.full_description,
+      }));
+
+    const failed = report.summary.failure_count;
+    const passed = report.summary.example_count - failed - report.summary.pending_count;
+
+    return {
+      tool: "rspec",
+      status: failed > 0 ? "fail" : "pass",
+      summary: failed > 0 ? `${failed} failed, ${passed} passed` : `${passed} passed`,
+      failures,
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;

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

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./ruff-json";
+import type { RunContext } from "../types";
+
+function makeCtx(stdout: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ruff-test-"));
+  const stdoutPath = path.join(dir, "stdout");
+  fs.writeFileSync(stdoutPath, stdout);
+  return {
+    command: "ruff check . --output-format=json",
+    argv: ["ruff", "check", ".", "--output-format=json"],
+    cwd,
+    artifactPaths: [],
+    stdoutPath,
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+describe("ruff-json parser", () => {
+  it("multiple errors across multiple files → correct relative paths, rule code mapped to rule, status fail", async () => {
+    const cwd = "/project";
+    const stdout = JSON.stringify([
+      { filename: "/project/src/foo.py", code: "F401", message: "`os` imported but unused", location: { row: 1 } },
+      { filename: "/project/src/foo.py", code: "E741", message: "Ambiguous variable name: `l`", location: { row: 5 } },
+      {
+        filename: "/project/src/bar.py",
+        code: "F841",
+        message: "Local variable `x` is assigned to but never used",
+        location: { row: 3 },
+      },
+    ]);
+    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.py");
+    expect(result.failures![2].file).toBe("src/bar.py");
+    expect(result.failures![0].file).not.toContain("/project");
+    expect(result.failures![0].rule).toBe("F401");
+    expect(result.failures![1].rule).toBe("E741");
+  });
+
+  it("no errors → empty failures, status pass", async () => {
+    const result = await parser.parse(makeCtx(JSON.stringify([])));
+    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/ruff-json.ts

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserModule } from "../types";
+
+interface RuffItem {
+  filename: string;
+  code: string;
+  message: string;
+  location?: { row: number };
+}
+
+const parser: ParserModule = {
+  id: "ruff-json",
+  async parse(ctx) {
+    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8").trim();
+    const items = stdout ? (JSON.parse(stdout) as RuffItem[]) : [];
+    const failures = (Array.isArray(items) ? items : []).map((item) => {
+      const relPath = path.relative(ctx.cwd, item.filename);
+      return {
+        id: `${relPath}:${item.location?.row}:${item.code}`,
+        file: relPath,
+        line: item.location?.row,
+        message: item.message,
+        rule: item.code,
+      };
+    });
+    return {
+      tool: "ruff",
+      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/tail-fallback.test.ts

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./tail-fallback";
+import type { RunContext } from "../types";
+
+function makeCtx(logContent: string): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tail-test-"));
+  const logPath = path.join(dir, "log");
+  fs.writeFileSync(logPath, logContent);
+  return {
+    command: "some-command",
+    argv: ["some-command"],
+    cwd: "/project",
+    artifactPaths: [],
+    stdoutPath: path.join(dir, "stdout"),
+    stderrPath: path.join(dir, "stderr"),
+    logPath,
+  };
+}
+
+describe("tail-fallback parser", () => {
+  it("any command → status error, summary contains log path", async () => {
+    const ctx = makeCtx("some output");
+    const result = await parser.parse(ctx);
+    expect(result.status).toBe("error");
+    expect(result.summary).toBe("no parser matched; returning tail + log path");
+    expect(result.logPath).toBe(ctx.logPath);
+  });
+
+  it("long stdout → tail is bounded to last 200 lines", async () => {
+    const lines = Array.from({ length: 300 }, (_, i) => `line ${i + 1}`);
+    const ctx = makeCtx(lines.join("\n"));
+    const result = await parser.parse(ctx);
+    const tailLines = result.rawTail!.split("\n");
+    expect(tailLines.length).toBeLessThanOrEqual(200);
+    expect(tailLines[tailLines.length - 1]).toBe("line 300");
+    expect(tailLines[0]).toBe("line 101");
+  });
+});

package/extensions/structured-return/src/parsers/tail-fallback.ts

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import type { ParserModule } from "../types";
+
+const parser: ParserModule = {
+  id: "tail-fallback",
+  async parse(ctx) {
+    const log = fs.readFileSync(ctx.logPath, "utf8");
+    const lines = log.split(/\r?\n/);
+    const tail = lines.slice(-200).join("\n");
+    return {
+      tool: "unknown",
+      status: "error",
+      summary: "no parser matched; returning tail + log path",
+      logPath: ctx.logPath,
+      rawTail: tail,
+    };
+  },
+};
+
+export default parser;

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

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, it, expect } from "vitest";
+import parser from "./vitest-json";
+import type { RunContext } from "../types";
+
+function makeCtx(stdout: string, cwd = "/project"): RunContext {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "vitest-test-"));
+  const stdoutPath = path.join(dir, "stdout");
+  fs.writeFileSync(stdoutPath, stdout);
+  return {
+    command: "vitest run --reporter=json",
+    argv: ["vitest", "run", "--reporter=json"],
+    cwd,
+    artifactPaths: [],
+    stdoutPath,
+    stderrPath: path.join(dir, "stderr"),
+    logPath: path.join(dir, "log"),
+  };
+}
+
+const passing = (name: string) => ({
+  fullName: name,
+  status: "passed" as const,
+  failureMessages: [],
+});
+
+const failing = (name: string, message: string) => ({
+  fullName: name,
+  status: "failed" as const,
+  failureMessages: [`${message}\n  at Object.<anonymous> (test.ts:10:5)`],
+});
+
+describe("vitest-json parser", () => {
+  it("all passing → status pass, summary reflects passed count", async () => {
+    const report = {
+      numPassedTests: 5,
+      numFailedTests: 0,
+      testResults: [
+        {
+          name: "/project/src/foo.test.ts",
+          status: "passed",
+          assertionResults: [passing("foo test a"), passing("foo test b")],
+        },
+      ],
+    };
+    const result = await parser.parse(makeCtx(JSON.stringify(report)));
+    expect(result.status).toBe("pass");
+    expect(result.summary).toBe("5 passed");
+    expect(result.failures).toHaveLength(0);
+  });
+
+  it("mix of passed and failed → status fail, correct counts, failures listed", async () => {
+    const cwd = "/project";
+    const report = {
+      numPassedTests: 3,
+      numFailedTests: 2,
+      testResults: [
+        {
+          name: "/project/src/foo.test.ts",
+          status: "failed",
+          assertionResults: [passing("foo passes"), failing("foo fails A", "AssertionError: expected 1 to equal 2")],
+        },
+        {
+          name: "/project/src/bar.test.ts",
+          status: "failed",
+          assertionResults: [failing("bar fails B", "AssertionError: expected true to be false")],
+        },
+      ],
+    };
+    const result = await parser.parse(makeCtx(JSON.stringify(report), cwd));
+    expect(result.status).toBe("fail");
+    expect(result.summary).toBe("2 failed, 3 passed");
+    expect(result.failures).toHaveLength(2);
+    expect(result.failures![0].file).toBe("src/foo.test.ts");
+    expect(result.failures![1].file).toBe("src/bar.test.ts");
+  });
+
+  it("failure message → first line only surfaced", async () => {
+    const report = {
+      numPassedTests: 0,
+      numFailedTests: 1,
+      testResults: [
+        {
+          name: "/project/src/foo.test.ts",
+          status: "failed",
+          assertionResults: [failing("foo fails", "AssertionError: expected 1 to equal 2")],
+        },
+      ],
+    };
+    const result = await parser.parse(makeCtx(JSON.stringify(report)));
+    expect(result.failures![0].message).toBe("AssertionError: expected 1 to equal 2");
+  });
+
+  it("relative paths in failure file field", async () => {
+    const cwd = "/project";
+    const report = {
+      numPassedTests: 0,
+      numFailedTests: 1,
+      testResults: [
+        {
+          name: "/project/src/deep/foo.test.ts",
+          status: "failed",
+          assertionResults: [failing("foo fails", "Error")],
+        },
+      ],
+    };
+    const result = await parser.parse(makeCtx(JSON.stringify(report), cwd));
+    expect(result.failures![0].file).toBe("src/deep/foo.test.ts");
+    expect(result.failures![0].file).not.toContain("/project");
+  });
+
+  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/vitest-json.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { ParserModule } from "../types";
+
+interface VitestAssertionResult {
+  fullName: string;
+  status: "passed" | "failed";
+  failureMessages: string[];
+}
+
+interface VitestTestResult {
+  name: string;
+  status: "passed" | "failed";
+  assertionResults: VitestAssertionResult[];
+}
+
+interface VitestReport {
+  numPassedTests: number;
+  numFailedTests: number;
+  testResults: VitestTestResult[];
+}
+
+const parser: ParserModule = {
+  id: "vitest-json",
+  async parse(ctx) {
+    const stdout = fs.readFileSync(ctx.stdoutPath, "utf8").trim();
+    const report = stdout ? (JSON.parse(stdout) as VitestReport) : null;
+    if (!report) {
+      return {
+        tool: "vitest",
+        status: "error",
+        summary: "no output",
+        logPath: ctx.logPath,
+      };
+    }
+
+    const failures = report.testResults.flatMap((suite) =>
+      suite.assertionResults
+        .filter((t) => t.status === "failed")
+        .map((t) => ({
+          id: t.fullName,
+          file: path.relative(ctx.cwd, suite.name),
+          message: t.failureMessages[0]?.split("\n")[0] ?? "test failed",
+        }))
+    );
+
+    const failed = report.numFailedTests;
+    const passed = report.numPassedTests;
+
+    return {
+      tool: "vitest",
+      status: failed > 0 ? "fail" : "pass",
+      summary: failed > 0 ? `${failed} failed, ${passed} passed` : `${passed} passed`,
+      failures,
+      logPath: ctx.logPath,
+    };
+  },
+};
+
+export default parser;

package/extensions/structured-return/src/storage/log-store.ts

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export function ensureRunDir(cwd: string): string {
+  const dir = path.join(cwd, ".pi", "structured-returns");
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function writeRunArtifacts(
+  dir: string,
+  runId: string,
+  stdout: string,
+  stderr: string
+): { stdoutPath: string; stderrPath: string; logPath: string } {
+  const stdoutPath = path.join(dir, `${runId}.stdout.log`);
+  const stderrPath = path.join(dir, `${runId}.stderr.log`);
+  const logPath = path.join(dir, `${runId}.combined.log`);
+  fs.writeFileSync(stdoutPath, stdout);
+  fs.writeFileSync(stderrPath, stderr);
+  fs.writeFileSync(logPath, [stdout, stderr].filter(Boolean).join("\n"));
+  return { stdoutPath, stderrPath, logPath };
+}

package/extensions/structured-return/src/types.ts

@@ -0,0 +1,55 @@
+export type ParsedFailure = {
+  id: string;
+  file?: string;
+  line?: number;
+  message?: string;
+  rule?: string;
+};
+
+export type ParsedResult = {
+  tool: string;
+  exitCode: number;
+  status: "pass" | "fail" | "error";
+  summary: string;
+  cwd?: string;
+  failures?: ParsedFailure[];
+  artifact?: string;
+  logPath?: string;
+  rawTail?: string;
+};
+
+export type ObservedRunArgs = {
+  command: string;
+  cwd?: string;
+  parseAs?: string;
+  artifactPaths?: string[];
+};
+
+export type RunContext = {
+  command: string;
+  argv: string[];
+  cwd: string;
+  artifactPaths: string[];
+  stdoutPath: string;
+  stderrPath: string;
+  logPath: string;
+};
+
+export type ParserModule = {
+  id: string;
+  parse: (ctx: RunContext) => Promise<Omit<ParsedResult, "exitCode">>;
+};
+
+export type ParserRegistration = {
+  id: string;
+  match?: {
+    argvIncludes?: string[];
+    regex?: string;
+  };
+  parseAs?: string;
+  module?: string;
+};
+
+export type ParserConfigFile = {
+  parsers: ParserRegistration[];
+};

package/extensions/structured-return/src/ui/widget.ts

@@ -0,0 +1,3 @@
+export function renderWidgetLine(command: string, summary: string): string[] {
+  return [`structured_return ${command}`, `→ ${summary}`];
+}

package/extensions/structured-return/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts", "examples/.pi/parsers/**/*.ts"]
+}

package/extensions/structured-return/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+import path from "node:path";
+
+export default defineConfig({
+  test: {
+    root: path.resolve(import.meta.dirname, "src"),
+    include: ["**/*.test.ts"],
+  },
+});